OAuth 2.0
OAuth 2.0 permite que uma aplicação obtenha autorização para acessar recursos dentro dos limites concedidos pelo titular. Quando a finalidade é autenticar uma pessoa, utilize OpenID Connect sobre OAuth 2.0.
Fluxo recomendado
Para aplicações que atuam em nome de uma pessoa, utilize Authorization Code com PKCE S256:
- Descubra os metadados do issuer e obtenha o
authorization_endpointe otoken_endpoint. - Gere um
code_verifier, umcode_challengeS256 e valores imprevisíveis destateenonce. - Armazene os valores da transação no contexto de sessão do usuário, vinculados à tentativa de login.
- Redirecione o navegador ao endpoint de autorização com
response_type=code,client_id,redirect_uri,scope,state,noncee os parâmetros PKCE. - No callback, valide e consuma a transação, incluindo
state. - Troque o código no endpoint de token com o mesmo
redirect_uriecode_verifier. - Valide o ID Token por meio de uma biblioteca OIDC confiável.
O Redirect URI enviado deve corresponder exatamente a um endereço registrado. Não reutilize state, nonce ou code_verifier entre tentativas. Para os exemplos com openid-client v6, registre um Redirect URI sem query string: a biblioteca remove os parâmetros de consulta da URL de callback ao derivar o redirect_uri enviado na troca do código.
Exemplo JavaScript com openid-client
O exemplo abaixo ilustra um cliente público registrado com o método de autenticação none. A persistência da transação deve ser implementada no armazenamento de sessão do seu framework; as funções saveTransactionToSession e consumeTransactionFromSession(state) representam essa camada da aplicação. A segunda função deve remover atomicamente apenas a transação associada ao state recebido; isso permite várias tentativas simultâneas e impede que um callback desconhecido consuma outra transação.
Instale a biblioteca:
pnpm add openid-clientInicie a autorização no backend da aplicação:
import * as oidc from "openid-client";
const issuer = "https://id.centralmacatuba.qzz.io";
const clientId = process.env.CM_ID_CLIENT_ID;
const redirectUri = "https://app.example.com/auth/callback";
const config = await oidc.discovery(
new URL(issuer),
clientId,
undefined,
oidc.None(),
);
// Verificação adicional de assinatura dos JWTs processados via JWKS.
oidc.enableNonRepudiationChecks(config);
const codeVerifier = oidc.randomPKCECodeVerifier();
const codeChallenge = await oidc.calculatePKCECodeChallenge(codeVerifier);
const state = oidc.randomState();
const nonce = oidc.randomNonce();
await saveTransactionToSession({
codeVerifier,
state,
nonce,
redirectUri,
});
const authorizationUrl = oidc.buildAuthorizationUrl(config, {
redirect_uri: redirectUri,
response_type: "code",
scope: "openid profile email",
code_challenge: codeChallenge,
code_challenge_method: "S256",
state,
nonce,
});
// Redirecione o navegador para authorizationUrl.href.No callback registrado:
// A origem e o caminho vêm do Redirect URI registrado, nunca do Host.
const callbackUrl = new URL(redirectUri);
if (callbackUrl.search) {
throw new Error("Registre o Redirect URI sem query string.");
}
const incomingCallbackUrl = new URL(request.url, callbackUrl.origin);
if (
incomingCallbackUrl.origin !== callbackUrl.origin ||
incomingCallbackUrl.pathname !== callbackUrl.pathname
) {
throw new Error("Callback recebido em um endereço inesperado.");
}
callbackUrl.search = incomingCallbackUrl.search;
// Valide o callback antes de consumir a transação da sessão.
// O state identifica a tentativa exata, inclusive quando há logins simultâneos na mesma sessão.
const callbackStates = callbackUrl.searchParams.getAll("state");
if (callbackStates.length !== 1 || !callbackStates[0]) {
throw new Error("Callback deve conter exatamente um parâmetro state.");
}
// A implementação da sessão deve remover atomicamente somente a transação desse state.
// Um state desconhecido nunca pode consumir outra tentativa pendente.
const transaction = await consumeTransactionFromSession(callbackStates[0]);
if (!transaction || transaction.state !== callbackStates[0]) {
throw new Error("Transação OAuth não encontrada para o state recebido.");
}
const tokens = await oidc.authorizationCodeGrant(
config,
callbackUrl,
{
pkceCodeVerifier: transaction.codeVerifier,
expectedState: transaction.state,
expectedNonce: transaction.nonce,
idTokenExpected: true,
},
);
const claims = tokens.claims();
// Use as claims validadas pela biblioteca conforme a política da aplicação.O exemplo pressupõe que os scopes solicitados foram aprovados para o cliente. O backend deve proteger a sessão, consumir a transação uma única vez e nunca registrar códigos, tokens ou valores de PKCE. Para clientes private_key_jwt, configure a biblioteca com esse método e mantenha a chave privada exclusivamente no backend; não reutilize a configuração None().
A opção enableNonRepudiationChecks habilita uma verificação criptográfica adicional das assinaturas dos JWTs processados, utilizando o JWKS publicado pelo issuer. A biblioteca também autentica a comunicação direta com o endpoint de token por TLS; portanto, essa opção deve ser entendida como uma camada extra de não repúdio, não como substituta da validação de issuer, audience, expiração, nonce e demais verificações OIDC.
A API de openid-client pode evoluir. Consulte a documentação da versão instalada antes de atualizar a integração: documentação oficial do openid-client.
Descoberta de endpoints
Não fixe endpoints no código. Utilize os metadados OAuth Authorization Server Metadata:
https://id.centralmacatuba.qzz.io/.well-known/oauth-authorization-serverUse os valores publicados para authorization_endpoint, token_endpoint, jwks_uri e demais campos relevantes. A descoberta deve validar o issuer esperado.
Scopes
O portal de registro aceita openid, profile, email e offline_access. O scope openid é obrigatório para solicitações OIDC. A lista anunciada nos metadados do servidor pode incluir capacidades que não estão disponíveis no formulário de registro; não tente solicitar scopes não aprovados para o seu cliente.
Refresh tokens
Solicite offline_access somente quando a aplicação realmente precisar manter uma sessão delegada entre visitas. A emissão depende das políticas aplicáveis e da concessão do usuário. Armazene refresh tokens em local protegido, aplique a política de rotação publicada pelo serviço e descarte-os ao encerrar a autorização.
O que não fazer
- Evite implicit grant e Resource Owner Password Credentials.
- Mantenha Client IDs exclusivos para cada aplicação.
- Aceite somente Redirect URIs registrados.
- Solicite apenas os scopes necessários.
- Não trate um access token como prova de identidade do usuário; para identidade, valide o ID Token OIDC.
- Evite armazenar tokens em
localStoragequando puder mantê-los no backend em uma sessão protegida.