Skip to Content

Backend Node / Express

Añada el inicio de sesión a una aplicación Express de Node.js con la biblioteca openid-client y el flujo Authorization Code con PKCE.

Esta guía añade el inicio de sesión OIDC a una aplicación Express con la biblioteca openid-client, que se encarga del discovery, de PKCE y de la validación de tokens. Parte de un cliente confidential (un backend capaz de guardar un secreto).

Si aún no ha registrado una aplicación, consulte Antes de empezar. Para el protocolo que hay detrás, consulte OpenID Connect (Authorization Code + PKCE).

1. Instalar las dependencias

npm install express express-session openid-client

2. Configurar el 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);

Mantenga OIDC_CLIENT_ID y OIDC_CLIENT_SECRET en el entorno, nunca en el control de versiones.

3. Iniciar el inicio de sesión

Construya la URL de autorización con un challenge PKCE y un state, guarde ambos en la sesión y redirija el navegador.

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. Procesar el callback

Canjee el código por tokens. openid-client valida por usted la respuesta, el state y el verifier 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. Cerrar sesión

Envíe al usuario al endpoint de end session y borre después su propia sesión.

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));
});

Registre https://app.example.com/ como redirect URI de post-logout en la aplicación, igual que registra una redirect URI.

Solución de problemas

  • La llamada de discovery falla. Compruebe que https://<your-domain>/.well-known/openid-configuration es accesible desde su servidor y que el dominio es el host de inicio de sesión de su instancia.
  • Errores de state o de PKCE en el callback. La sesión que inició el acceso debe ser la misma que procesa el callback. Asegúrese de que las cookies de sesión sobreviven a la redirección (SameSite correcto y, en producción, cookies secure sobre HTTPS).
  • Nunca se devuelve un refresh token. Incluya offline_access en el scope y confirme que la aplicación está configurada para recibir refresh tokens.

Siguientes pasos

En esta página