Autorizando um usuário

Envie o usuário para o Autentique, solicite permissões e valide o retorno da autorização.

Nesta etapa, sua integração envia o usuário para o Autentique. O usuário entra na conta, confere as permissões solicitadas e decide se deseja conceder o acesso.

Antes de continuar, crie um aplicativo OAuth e tenha em mãos:

• o Client ID;

• a URL de redirecionamento cadastrada;

• as permissões que serão solicitadas.

O Client Secret ainda não será enviado ao navegador. Ele será usado somente pelo backend na troca do código pelos tokens.

Proteja cada tentativa de autorização

Antes de redirecionar o usuário, crie três valores:

Valor	Para que serve
state	Vincula o callback à tentativa iniciada pela sua integração e ajuda a impedir requisições forjadas.
code_verifier	Segredo temporário, criado especificamente para aquela tentativa de autorização.
code_challenge	Versão derivada do code_verifier, enviada ao Autentique sem expor o valor original.

Crie valores novos para cada tentativa. O code_verifier deve ter de 43 a 128 caracteres e o desafio deve usar S256.

O exemplo abaixo usa Web Crypto e funciona em runtimes JavaScript que oferecem crypto.subtle:

const base64url = (bytes) =>
  btoa(String.fromCharCode(...bytes))
    .replace(/\+/g, '-')
    .replace(/\//g, '_')
    .replace(/=+$/, '');

const randomValue = (length = 32) =>
  base64url(crypto.getRandomValues(new Uint8Array(length)));

export async function createOAuthSession() {
  const state = randomValue();
  const codeVerifier = randomValue(64); // 86 caracteres, dentro do limite PKCE

  const digest = await crypto.subtle.digest(
    'SHA-256',
    new TextEncoder().encode(codeVerifier),
  );

  return {
    state,
    codeVerifier,
    codeChallenge: base64url(new Uint8Array(digest)),
  };
}

Guarde o state e o codeVerifier em uma sessão temporária no servidor, vinculada ao usuário que iniciou a conexão. Defina uma expiração curta e remova a sessão depois que o callback for processado.

Se sua arquitetura gerar esses valores no navegador, transfira-os imediatamente para a sessão temporária no servidor. Não reutilize os valores e não mantenha o codeVerifier no armazenamento do navegador.

Monte a URL de autorização

O endpoint de autorização é:

https://api.autentique.com.br/oauth/authorize

Envie os seguintes parâmetros:

Parâmetro	Valor
client_id	Client ID do aplicativo.
redirect_uri	URL cadastrada no aplicativo.
response_type	Use code.
scope	Permissões solicitadas, separadas por espaços.
state	Valor temporário criado pela integração.
code_challenge	Desafio derivado do code_verifier.
code_challenge_method	Use S256.

Exemplo:

const url = new URL('https://api.autentique.com.br/oauth/authorize');

url.search = new URLSearchParams({
  client_id: process.env.AUTENTIQUE_CLIENT_ID,
  redirect_uri: process.env.AUTENTIQUE_REDIRECT_URI,
  response_type: 'code',
  scope: 'user:read documents:read',
  state: oauthSession.state,
  code_challenge: oauthSession.codeChallenge,
  code_challenge_method: 'S256',
  // prompt: 'consent',
}).toString();

return url.toString();

O valor de scope deve conter apenas permissões configuradas para o aplicativo. Separe múltiplas permissões com espaços.

Use prompt=consent somente quando precisar mostrar novamente a tela de consentimento.

Redirecione o navegador do usuário para a URL gerada. Não faça uma requisição AJAX para o endpoint de autorização.

Receba o callback

Depois da decisão do usuário, o Autentique redireciona o navegador para a URL cadastrada.

Se o acesso for aprovado, o callback terá code e state:

https://app.exemplo.com/integracoes/autentique/callback?code=CODIGO&state=VALOR

Antes de usar o código:

1. localize a sessão temporária daquela autorização;

2. compare o state retornado com o valor salvo;

3. confirme que a sessão ainda não expirou;

4. remova ou marque a sessão como utilizada.

Se o state estiver ausente ou for diferente, encerre a tentativa. Não troque o código por tokens.

O código de autorização é temporário, de uso único e vinculado ao aplicativo, à URL de redirecionamento e ao code_verifier daquela tentativa.

Trate uma autorização negada

Se o usuário negar o acesso ou a autorização não puder ser concluída, o callback poderá conter:

• error;

• error_description;

• state.

Por exemplo:

https://app.exemplo.com/integracoes/autentique/callback?error=access_denied&state=VALOR

Valide o state também nos retornos com erro. Depois, informe que a conexão não foi concluída e permita que o usuário tente novamente se desejar.

Não trate uma negativa como falha inesperada e não inicie outra autorização automaticamente.

Com o callback validado, continue em Obtendo e usando os tokens.