Node.js e aplicações com backend
Para aplicações Node.js, use uma biblioteca OIDC mantida e mantenha o fluxo OAuth no backend sempre que possível. O exemplo utiliza openid-client v6 e corresponde a um cliente público com método none; aplicações registradas com private_key_jwt precisam de configuração própria de autenticação do cliente.
Instalação
pnpm add openid-clientConfiguração e descoberta
import * as oidc from "openid-client";
const issuer = new URL("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(
issuer,
clientId,
undefined,
oidc.None(),
);
// Habilita a verificação adicional da assinatura dos JWTs processados.
// Requer que o issuer publique um jwks_uri compatível.
oidc.enableNonRepudiationChecks(config);Mantenha clientId e demais configurações no ambiente do servidor. O exemplo não inclui credenciais confidenciais.
Iniciar a autenticação
const codeVerifier = oidc.randomPKCECodeVerifier();
const codeChallenge = await oidc.calculatePKCECodeChallenge(codeVerifier);
const state = oidc.randomState();
const nonce = oidc.randomNonce();
// Implemente estas funções com o armazenamento de sessão do seu framework.
// Os valores devem ser vinculados à sessão e consumidos uma única vez. Armazene as tentativas por `state`; `consumeTransactionFromSession(state)` deve remover atomicamente somente a tentativa solicitada.
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,
});
// Responda com um redirecionamento HTTP para authorizationUrl.href.Processar o callback
// Use a origem e o caminho do Redirect URI registrado; nunca confie no Host.
const callbackUrl = new URL(redirectUri);
if (callbackUrl.search) {
throw new Error("Registre o Redirect URI sem query string.");
}
// Em http.Server, request.url normalmente contém apenas caminho e query.
// A origem fixa impede que o cabeçalho Host controle o endereço usado.
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;
// Só consuma a transação após validar o endereço do callback.
// 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();
// Crie uma sessão local após a validação bem-sucedida.As funções de sessão e o objeto request são abstrações: conecte-os ao framework utilizado. Não aceite parâmetros de sessão enviados pelo navegador sem integridade e vinculação à sessão original. Registre o Redirect URI sem query string: openid-client deriva o parâmetro redirect_uri da URL de callback removendo sua query, que contém os parâmetros de resposta OAuth.
A verificação de assinatura habilitada com enableNonRepudiationChecks é uma camada adicional de não repúdio; a biblioteca também autentica a comunicação direta com o endpoint de token por TLS. Mantenha o jwks_uri publicado pelo issuer acessível e atualizado.
Requisitos para produção
- Proteja a sessão com cookie
HttpOnly,SecureeSameSiteadequado. - Consuma a transação de autenticação uma única vez.
- Não registre códigos, tokens, cookies ou valores PKCE.
- Valide o ID Token pela biblioteca; não confie em JWT apenas decodificado.
- Use
private_key_jwtapenas em backend e mantenha a chave privada fora do repositório. - Consulte erros e diagnóstico para tratar falhas.
Consulte também o guia OAuth 2.0 e a documentação oficial do openid-client.