OAuth 2.0: autorização e fluxo com PKCE

O que OAuth autoriza

OAuth 2.0 permite que uma aplicação obtenha acesso limitado a recursos de outra plataforma. O usuário autoriza a conexão sem entregar sua senha à aplicação integradora. O servidor de autorização emite um token, e a API de recursos avalia esse token e as permissões concedidas.

OAuth trata de autorização. Para identificar um usuário em um fluxo de login, OpenID Connect acrescenta uma camada de identidade e um ID token. Um access token serve para acessar a API; um ID token descreve a autenticação do usuário. Usar um no lugar do outro pode levar a validações incorretas.

Escolha o fluxo para o seu contexto

Quando a integração age em nome de uma pessoa, o fluxo Authorization Code com PKCE é um ponto de partida comum. Aplicações públicas, como aplicativos móveis ou código executado no navegador, não conseguem manter um client secret confidencial. Não distribua esse segredo no pacote da aplicação.

No servidor, um cliente confidencial pode se autenticar no endpoint de tokens, seguindo o método do provedor. Para comunicação entre serviços sem uma pessoa autorizando, verifique se o cenário admite Client Credentials. O escopo e os recursos acessíveis nesse fluxo podem ser diferentes daqueles de uma conta de usuário.

Prepare redirecionamento, state e PKCE

Cadastre uma URI de retorno exata no provedor e use HTTPS fora dos cenários locais previstos pela documentação. Em cada tentativa, gere um state aleatório e vincule-o à sessão que iniciou o processo. Ao retornar, compare o valor recebido com o guardado e descarte tentativas ausentes, divergentes, expiradas ou já usadas.

PKCE cria um code_verifier exclusivo para a transação e envia apenas o desafio derivado na etapa de autorização. Com S256, o desafio é o SHA-256 do verifier, codificado em base64url. Na troca do código, o cliente envia o verifier original. O servidor verifica a relação entre os dois valores.

// Node.js: gere novos valores em cada tentativa de autorização.
import { createHash, randomBytes } from 'node:crypto';

const state = randomBytes(32).toString('base64url');
const codeVerifier = randomBytes(32).toString('base64url');
const codeChallenge = createHash('sha256')
  .update(codeVerifier)
  .digest('base64url');

// Guarde state e codeVerifier na sessão, com expiração e uso único.
// Envie na autorização:
// response_type=code
// code_challenge=<codeChallenge>
// code_challenge_method=S256
// state=<state>
// client_id, redirect_uri e scope conforme o provedor.
// Envie code_verifier=<codeVerifier> apenas na troca do código.

Troque o código e valide a conexão

Após conferir o retorno e a sessão, troque o authorization code no endpoint de tokens por uma conexão protegida. Inclua o code_verifier, a URI de retorno e os parâmetros definidos na documentação. O código é temporário e de uso único: mantenha a troca no fluxo que iniciou a autorização.

Solicite apenas os escopos necessários e confirme o acesso efetivamente concedido. No sistema integrador, associe a credencial à conta e à empresa corretas. Essa associação é uma decisão da sua aplicação e deve ser validada antes de sincronizar dados ou realizar uma ação em nome do usuário.

Cuide do ciclo de vida dos tokens

Guarde tokens e seus metadados de expiração em um armazenamento protegido. Tokens de acesso não são necessariamente JWTs e não devem ser interpretados como tal sem o contrato do provedor. Se houver refresh token, use o endpoint e as regras de renovação documentados.

Quando o provedor rotacionar o refresh token, salve a nova credencial de forma atômica. Coordene chamadas concorrentes para evitar que duas renovações disputem o mesmo token. Se a autorização for revogada ou a renovação falhar de forma definitiva, interrompa o acesso e solicite uma nova conexão ao usuário.

Revise os controles de segurança

As boas práticas atuais do IETF desaconselham fluxos que ampliam a exposição de tokens, como Implicit, e proíbem o fluxo que coleta diretamente a senha do usuário para obter tokens. Prefira bibliotecas mantidas para executar o protocolo e leia as recomendações de segurança do provedor.

Teste retorno com state incorreto, repetição do callback, verifier inválido, expiração, recusa do consentimento e revogação. Não registre códigos ou tokens em logs e não aceite URLs de retorno arbitrárias. Para login com OpenID Connect, valide também assinatura, emissor, audiência e os demais requisitos do ID token.

Fontes e referências oficiais

Consulte o contrato e as recomendações da plataforma que você está integrando. Os detalhes variam por serviço e podem evoluir.

Continue aprendendo

Encontrar uma API