OAuth e OpenID Connect
OAuth permite que uma aplicação externa obtenha acesso delegado sem receber a senha da pessoa. No Portal 2, a aplicação inicia uma autorização, a pessoa entra e aprova ou nega o pedido, e a aplicação troca um código de uso único por tokens.
O caminho recomendado para aplicações com navegador é Authorization Code com PKCE S256. PKCE associa o código entregue no redirecionamento à prova criada pela própria aplicação, reduzindo o risco de uso indevido de um código interceptado.
Antes de começar
Você precisa de um cliente OAuth registrado, uma redirect_uri HTTPS permitida e uma implementação de PKCE. O cadastro e a alteração de clientes exigem platformAdmin.
Não coloque client_secret, tokens ou códigos de autorização em documentação, logs de navegador ou URLs além do redirecionamento previsto pelo protocolo.
Fluxo principal: Authorization Code com PKCE
Happy path
- Gere um
code_verifiercriptograficamente aleatório e derive ocode_challengecom S256. - Redirecione o navegador para GET /v1/oauth/authorize com
client_id,redirect_uri,response_type=code,state,code_challengeecode_challenge_method=S256. - A pessoa entra no Portal 2 se ainda não houver sessão.
- A tela de consentimento apresenta o cliente e os scopes solicitados.
- Depois da aprovação, receba o
codee o mesmostatenaredirect_uriregistrada. - No servidor da sua aplicação, envie o código e o
code_verifierpara POST /v1/oauth/token. - Valide assinatura,
issuer,audience, expiração e os claims necessários antes de usar o token.
Rotas e contratos relacionados
| Etapa | Rota | Referência |
|---|---|---|
| Iniciar autorização externa | GET /v1/oauth/authorize | Autorização OAuth |
| Consultar pedido de consentimento | GET /v1/auth/oauth/authorization | Pedido atual |
| Aprovar | POST /v1/auth/oauth/authorization/approve | Aprovar pedido |
| Negar | POST /v1/auth/oauth/authorization/deny | Negar pedido |
| Completar redirecionamento | GET /v1/auth/oauth/redirect | Redirecionar |
| Trocar código | POST /v1/oauth/token | Trocar código |
| Ler identidade autenticada | GET /v1/userinfo | UserInfo |
Validações e caminhos não felizes
| Situação | Onde é validada | Resultado |
|---|---|---|
client_id desconhecido | Identity. | A autorização não continua. |
redirect_uri não registrada, sem HTTPS ou diferente da esperada | Identity e configuração do cliente. | A aplicação não recebe código. |
state ausente, expirado ou diferente | Aplicação cliente e fluxo de autorização. | Interrompa o fluxo; não troque o código. |
PKCE ausente ou code_verifier incompatível | Identity. | A troca de código falha. |
| Código reutilizado | Identity. | O código é de uso único e não emite novos tokens. |
| Scopes fora do permitido | Identity. | O pedido é recusado ou limitado ao escopo permitido. |
| Origem ou CSRF inválidos na aprovação | BFF. | A decisão de consentimento retorna 403. |
| Pessoa nega consentimento | Portal e BFF. | O redirecionamento retorna erro OAuth e o state original. |
O discovery informa os endpoints e algoritmos suportados. O JWKS expõe somente chaves públicas. O Portal usa RS256 e declara suporte a S256 para PKCE.
Permissões
Uma pessoa autenticada pode aprovar ou negar uma autorização em seu próprio contexto. A criação, alteração e rotação de clientes OAuth são operações administrativas e exigem platformAdmin. OAuth não concede automaticamente uma permissão de negócio: o serviço que recebe a chamada continua avaliando os scopes e as regras do recurso.
Próximos passos
Veja Entrar pelo navegador para o trecho em que a pessoa cria uma sessão. Veja Sessão e segurança do navegador para entender a proteção do consentimento no browser.