Skip to Content

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-client

2. 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 state ou 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 (SameSite correto e, em produção, cookies secure sobre HTTPS).
  • Nunca é devolvido um refresh token. Inclua offline_access no scope e confirme que a aplicação está configurada para receber refresh tokens.

Passos seguintes

Nesta página