Skip to Content

Backend Node / Express

Aggiungere l'accesso a un'app Node.js Express utilizzando la libreria openid-client e il flusso Authorization Code con PKCE.

Questa guida aggiunge l'accesso OIDC a un'app Express utilizzando la libreria openid-client, che si occupa di discovery, PKCE e validazione dei token. Presuppone un client confidential (un backend in grado di custodire un secret).

Chi non ha ancora registrato un'applicazione può consultare Prima di iniziare. Per il protocollo sottostante, vedere OpenID Connect (Authorization Code + PKCE).

1. Installare le dipendenze

npm install express express-session openid-client

2. Configurare il client

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

Mantenere OIDC_CLIENT_ID e OIDC_CLIENT_SECRET nell'ambiente, mai nel controllo di versione.

3. Avviare l'accesso

Costruire l'URL di autorizzazione con una challenge PKCE e uno state, memorizzarli entrambi nella sessione e reindirizzare il 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. Gestire il callback

Scambiare il code con i token. openid-client si occupa di validare la risposta, lo state e il 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. Disconnettersi

Inviare l'utente all'endpoint di end session, quindi azzerare la propria sessione.

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

Registrare https://app.example.com/ come post-logout redirect URI sull'applicazione, nello stesso modo in cui si registra un redirect URI.

Risoluzione dei problemi

  • La chiamata di discovery non riesce. Verificare che https://<your-domain>/.well-known/openid-configuration sia raggiungibile dal proprio server e che il dominio sia l'host di accesso della propria istanza.
  • Errori di state o di PKCE nel callback. La sessione che ha avviato l'accesso deve essere la stessa che gestisce il callback. Assicurarsi che i cookie di sessione sopravvivano al redirect (SameSite corretto e, in produzione, cookie secure su HTTPS).
  • Non viene mai restituito un refresh token. Includere offline_access nello scope e verificare che l'applicazione sia configurata per ricevere refresh token.

Passi successivi

In questa pagina