Diagrama de fluxo do OAuth 2.0: authorization code com PKCE, passo a passo

O OAuth 2.0 é fácil de usar e difícil de visualizar. Um botão de login dispara redirecionamentos entre três ou quatro partes, cada uma com parâmetros de nomes parecidos, e a maioria dos bugs vem de uma parte que pula uma checagem que deveria fazer. Um diagrama de sequência é o jeito mais claro de ver quem manda o quê para quem, e em que ordem.

Este artigo desenha o fluxo que você deve usar hoje em quase todo cliente: o authorization code grant com PKCE. Ele percorre cada passo, explica o que cada parte checa e lista os fluxos antigos que as recomendações atuais mandam abandonar.

As quatro partes

O cliente nunca vê a senha do usuário. Esse é o ponto do OAuth: o servidor de autorização autentica o usuário e entrega ao cliente um token com escopo e validade limitados.

Qual fluxo usar em 2026

O framework original do OAuth 2.0, a RFC 6749, definia vários grants. A OAuth 2.0 Security Best Current Practice, RFC 9700, publicada em janeiro de 2025, estreita a escolha:

• Authorization code com PKCE para login de usuários, a partir de qualquer tipo de cliente. Clientes públicos (apps mobile, single-page apps) precisam usar PKCE; para clientes confidenciais com um segredo no servidor, ele é recomendado.
• Nada de implicit grant. Ele devolve os tokens no redirecionamento do navegador, onde podem vazar; os clientes não devem usá-lo.
• Nada de resource owner password credentials grant. Entregar a senha do usuário ao cliente anula o propósito; a BCP diz que ele não deve ser usado.
• Client credentials para chamadas entre serviços, sem usuário envolvido.

O rascunho do OAuth 2.1 reúne essas regras em um único documento, então bibliotecas novas cada vez mais partem delas.

PKCE em um parágrafo

O Proof Key for Code Exchange, RFC 7636, protege o authorization code. Antes de redirecionar, o cliente cria um code_verifier aleatório (de 43 a 128 caracteres) e envia só o hash SHA-256 dele, o code_challenge, com code_challenge_method=S256. Quando o cliente troca o código por tokens depois, ele envia o verifier. O servidor calcula o hash e compara. Um atacante que intercepta o código não consegue usá-lo sem o verifier, que nunca saiu do cliente.

O fluxo, passo a passo

1. O usuário clica em Entrar. O cliente gera state (um valor aleatório ligado à sessão do usuário) e o verifier e o challenge do PKCE.
2. O cliente redireciona para /authorize com response_type=code, client_id, a redirect_uri registrada, o scope pedido, state e o code challenge.
3. O servidor de autorização mostra sua página de login e consentimento. O cliente não participa; isso acontece no domínio do servidor.
4. O usuário faz login, conclui o MFA se for preciso e consente com os escopos.
5. O servidor redireciona de volta para a redirect_uri registrada exata, com um code de uso único e vida curta e o mesmo state. O cliente checa se state bate com o que ele enviou; se não bater, para. A RFC 6749 recomenda uma validade de no máximo 10 minutos para o código.
6. O cliente faz um POST em /token com o código, a URI de redirecionamento e o code_verifier (mais a autenticação do cliente, se for um cliente confidencial). É uma requisição pelo back channel, não um redirecionamento.
7. O servidor devolve os tokens: um access token, geralmente um refresh token e um ID token se você usa OpenID Connect.
8. O cliente chama a API com Authorization: Bearer <access token>.
9. A API valida o token e responde. Para access tokens JWT, ela checa localmente assinatura, emissor, audiência, expiração e escopos; para tokens opacos, consulta o endpoint de introspecção do servidor de autorização.
10. Quando o access token expira, o cliente envia o refresh token por POST para /token.
11. O servidor devolve um novo access token, e para clientes públicos um novo refresh token. A RFC 9700 exige que os refresh tokens de clientes públicos sejam vinculados ao remetente ou rotacionados, para que um refresh token roubado pare de funcionar depois de um uso por qualquer uma das partes.

O diagrama de sequência

Como ler:

• Quatro linhas de vida, da esquerda para a direita: o usuário, o app cliente, o servidor de autorização e a API.
• Setas contínuas com ponta cheia são requisições; setas tracejadas são respostas e redirecionamentos de volta.
• Os passos 2 a 5 são redirecionamentos pelo front channel, através do navegador; o passo 6 é a requisição de token pelo back channel, onde o PKCE faz diferença.
• O fragmento opt embaixo só roda quando o access token expirou.
• O bloco Markdown lista as checagens de cada parte, que é onde se escondem a maioria dos bugs reais.

Erros que aparecem em revisões

• Não checar o state. Sem essa checagem, um atacante pode concluir um fluxo de login no navegador da vítima com a conta do atacante.
• Comparação frouxa da URI de redirecionamento. O servidor precisa comparar exatamente com a URI registrada; comparar por prefixo ou curinga permite roubar códigos.
• Tokens no local storage de uma single-page app. Qualquer injeção de script consegue lê-los. Muitos times colocam um pequeno backend na frente da SPA (um backend-for-frontend) que guarda os tokens e dá ao navegador um cookie de sessão.
• APIs que aceitam qualquer token válido. Cheque a audiência, ou um token emitido para outra API vai funcionar na sua.
• Web views embutidas em apps mobile. A RFC 8252 diz que apps nativos devem usar o navegador do sistema, para que o app não veja as credenciais do usuário.
• Access tokens longos para fugir da lógica de refresh. Mantenha os access tokens curtos e renove-os; assim uma revogação vale rápido.

O que desenhar em um diagrama de OAuth

• Cada parte na sua própria linha de vida, incluindo o navegador se o seu cliente tem backend.
• Front channel e back channel diferenciados, porque têm propriedades de segurança diferentes.
• Os nomes dos parâmetros nas setas: state, code_challenge, code, code_verifier. Quem revisa procura por eles.
• Quem valida o quê. As checagens são o design; as setas só movem dados.

Se você está desenhando o panorama de segurança mais amplo, o diagrama de arquitetura zero trust mostra onde o provedor de identidade fica entre os outros controles, e o diagrama de arquitetura de API gateway cobre a validação dos tokens uma única vez na borda. O exemplo de diagrama de sequência explica com mais detalhes a notação usada aqui.

Monte no Archboard

1. Entre com Google ou GitHub e crie um diagrama.
2. Do pack Sequência, adicione um Ator para o usuário e três nós Linha de vida para o app cliente, o servidor de autorização e a API, em uma linha e com a mesma altura.
3. Desenhe cada mensagem como uma aresta reta entre as linhas de vida, de cima para baixo, com os nomes dos parâmetros no rótulo. Use arestas tracejadas com ponta aberta para respostas e redirecionamentos.
4. Adicione um Fragmento combinado com o operador opt em volta dos passos de refresh.
5. Adicione um bloco Markdown do pack Básico com as checagens de cada parte.

O exemplo usa 6 nós de diagrama e fica dentro do plano Free.

Perguntas frequentes

Qual a diferença entre OAuth 2.0 e OpenID Connect? O OAuth 2.0 trata de acesso delegado: o cliente recebe um token para chamar uma API. O OpenID Connect acrescenta identidade por cima: um ID token que diz ao cliente quem é o usuário e um endpoint padrão de informações do usuário.

Preciso de PKCE se meu app tem um client secret? A RFC 9700 recomenda também para clientes confidenciais. Ele protege contra injeção de código e custa um parâmetro a mais de cada lado.

O implicit grant ainda deve ser usado? Não. A boa prática atual diz que os clientes não devem usá-lo. Use o authorization code grant com PKCE no lugar, inclusive em single-page apps.

Onde uma single-page app deve guardar os tokens? De preferência, em lugar nenhum do navegador: um backend-for-frontend pode guardar os tokens no servidor e dar ao navegador um cookie de sessão seguro. Se os tokens precisarem ficar no navegador, mantenha-os em memória, mantenha os access tokens curtos e use rotação de refresh tokens.

Como a API valida um access token? Para access tokens JWT, checando a assinatura com as chaves publicadas pelo servidor de autorização, além de emissor, audiência, expiração e escopo. Para tokens opacos, chamando o endpoint de introspecção.

Comece grátis — um assento, sem cartão de crédito.