Backend Node / Express
Acrescente o início de sessão a uma aplicação Node.js Express com a biblioteca openid-client e o fluxo Authorization Code com PKCE.
Este guia acrescenta o início de sessão OIDC a uma aplicação Express com a biblioteca openid-client, que trata da discovery, do PKCE e da validação dos tokens. Parte do princípio de que se trata de um cliente confidential (um backend capaz de guardar um segredo).
Se ainda não registou uma aplicação, consulte Antes de começar. Para o protocolo subjacente, consulte OpenID Connect (Authorization Code + PKCE).
1. Instalar as dependências
npm install express express-session openid-client2. Configurar o cliente
import * as client from 'openid-client';
// Your instance's login domain (issuer). openid-client reads the
// discovery document at <issuer>/.well-known/openid-configuration.
const server = new URL('https://<your-domain>');
const clientId = process.env.OIDC_CLIENT_ID;
const clientSecret = process.env.OIDC_CLIENT_SECRET;
const redirectUri = 'https://app.example.com/callback';
const scope = 'openid profile email offline_access';
// Discover endpoints and prepare the client (default: client_secret_basic).
const config = await client.discovery(server, clientId, clientSecret);Mantenha OIDC_CLIENT_ID e OIDC_CLIENT_SECRET no ambiente, nunca no controlo de versões.
3. Iniciar a autenticação
Construa o URL de autorização com um desafio PKCE e um state, guarde ambos na sessão e redirecione o browser.
import express from 'express';
import session from 'express-session';
const app = express();
app.use(session({ secret: process.env.SESSION_SECRET, resave: false, saveUninitialized: false }));
app.get('/login', async (req, res) => {
const codeVerifier = client.randomPKCECodeVerifier();
const codeChallenge = await client.calculatePKCECodeChallenge(codeVerifier);
const state = client.randomState();
// stash for the callback
req.session.codeVerifier = codeVerifier;
req.session.state = state;
const authUrl = client.buildAuthorizationUrl(config, {
redirect_uri: redirectUri,
scope,
code_challenge: codeChallenge,
code_challenge_method: 'S256',
state,
});
res.redirect(authUrl.href);
});4. Processar o callback
Troque o código por tokens. A biblioteca openid-client valida a resposta, o state e o verifier do PKCE.
app.get('/callback', async (req, res) => {
const currentUrl = new URL(req.originalUrl, 'https://app.example.com');
const tokens = await client.authorizationCodeGrant(config, currentUrl, {
pkceCodeVerifier: req.session.codeVerifier,
expectedState: req.session.state,
});
const claims = tokens.claims(); // validated ID-token claims
req.session.user = { sub: claims.sub, name: claims.name, email: claims.email };
req.session.idToken = tokens.id_token;
// Optional: fetch additional claims from UserInfo
// const userinfo = await client.fetchUserInfo(config, tokens.access_token, claims.sub);
res.redirect('/');
});5. Terminar sessão
Envie o utilizador para o endpoint de end session e limpe depois a sua própria sessão.
app.get('/logout', (req, res) => {
const endSession = client.buildEndSessionUrl(config, {
id_token_hint: req.session.idToken,
post_logout_redirect_uri: 'https://app.example.com/',
});
req.session.destroy(() => res.redirect(endSession.href));
});Registe https://app.example.com/ como post-logout redirect URI na aplicação, da mesma forma que regista um redirect URI.
Resolução de problemas
- A chamada de discovery falha. Confirme que
https://<your-domain>/.well-known/openid-configurationé acessível a partir do seu servidor e que o domínio é o host de início de sessão da sua instância. - Erros de
stateou de PKCE no callback. A sessão que iniciou a autenticação tem de ser a mesma que processa o callback. Garanta que os cookies de sessão sobrevivem ao redirecionamento (SameSitecorreto e, em produção, cookiessecuresobre HTTPS). - Nunca é devolvido um refresh token. Inclua
offline_accessno scope e confirme que a aplicação está configurada para receber refresh tokens.
Passos seguintes
- Aplicação de página única em React para um cliente exclusivamente de browser.
- Aplicações para rever os tempos de vida dos tokens e outras definições do cliente.
OpenID Connect (Authorization Code + PKCE)
O fluxo OIDC Authorization Code com PKCE de ponta a ponta, com HTTP simples e curl, para que perceba cada passo antes de recorrer a uma biblioteca.
Backend Python / Flask
Acrescente o início de sessão a uma aplicação Python Flask com a biblioteca Authlib e o fluxo Authorization Code com PKCE.