Fluxo authorization code do OAuth 2.0 com PKCE para clientes públicos

O que é

No fluxo authorization code grant, o navegador é redirecionado para o servidor de autorização, o usuário dá o consentimento e o servidor redireciona de volta com um code de curta duração, que o cliente troca por tokens no token endpoint. Um cliente confidencial autentica essa troca com o seu client secret; um cliente público não tem nenhum, de modo que um code roubado poderia ser resgatado por qualquer pessoa. A RFC 7636 (citada) fecha essa brecha: o cliente gera um code_verifier, uma string aleatória de 43 a 128 caracteres não reservados, envia code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier))) com code_challenge_method=S256 na requisição de autorização e, no token endpoint, envia o code_verifier em texto puro junto com o code. O servidor recalcula o hash e rejeita se não coincidir. A RFC determina que um cliente capaz de usar S256 deve usá-lo; o método plain existe apenas para clientes com recursos limitados.

Por que importa

A RFC 8252 (citada) exige que clientes públicos de apps nativos implementem PKCE e que os servidores de autorização o suportem, e pede que apps nativos usem o navegador do sistema em vez de uma web view embutida. A RFC 9700 (citada), a melhor prática atual de segurança do OAuth, amplia a exigência: clientes públicos devem usar PKCE, recomenda-se que clientes confidenciais também o usem, clientes não devem usar o implicit grant (tokens no fragmento da URL vazam pelo histórico e por referrers), refresh tokens de clientes públicos devem ser vinculados ao remetente (sender-constrained) ou rotacionados, e as redirect URIs devem ser comparadas por correspondência exata de string (exceto a porta, no caso de localhost em apps nativos). O PKCE também protege contra a injeção de authorization code, em que um atacante insere na sessão da vítima um code obtido em outro lugar.

Como aplicar

• Gere o verifier com uma fonte aleatória criptograficamente segura a cada requisição de autorização; guarde-o junto com o valor de state em um local vinculado ao user agent (session storage em um app de navegador, memória do processo em uma CLI).
• Registre redirect URIs exatas. Para um app nativo, de CLI ou desktop, a RFC 8252 descreve três formas de receber a resposta: um esquema de URI de uso privado, uma URI https reivindicada (claimed) ou redirecionamento por loopback (http://127.0.0.1:<port>/).
• Verifique o state no retorno, troque o code uma única vez e descarte o verifier.
• Peça o scope mínimo, mantenha os access tokens de curta duração e use rotação de refresh tokens, para que o vazamento de um refresh token seja detectado quando ele for reutilizado.
• Use uma biblioteca cliente mantida; o fluxo tem mais casos extremos (mix-up, downgrade de code_challenge_method) do que cabe em código escrito à mão.

Armadilhas

Enviar code_challenge, mas deixar o servidor aceitar requisições ao token endpoint sem verifier (um downgrade descrito na BCP). Reutilizar um mesmo verifier em várias requisições. Guardar refresh tokens no localStorage de uma página que também executa scripts de terceiros. Tratar um access token como prova de identidade; para isso existem os ID tokens do OpenID Connect.

Aplicações de página única: prefira um backend for frontend

Uma aplicação de navegador que tem servidor próprio não precisa ser um cliente público. A RFC 10017 (BCP 212, 'OAuth 2.0 for Browser-Based Applications') descreve a arquitetura backend-for-frontend, em que um pequeno backend executa o fluxo authorization code como cliente confidencial (ainda com PKCE), mantém os access e refresh tokens no servidor e entrega ao navegador apenas um cookie de sessão same-site. A BCP a recomenda fortemente para aplicações de negócio, aplicações sensíveis e aplicações que tratam dados pessoais, porque um script injetado na página poderia, caso contrário, usar ou exfiltrar qualquer token que o navegador guarde. Use o fluxo no navegador descrito acima somente quando não houver um backend para guardar os tokens e, nesse caso, mantenha-os em memória, e não em web storage.