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-client2. 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-configurationsia raggiungibile dal proprio server e che il dominio sia l'host di accesso della propria istanza. - Errori di
stateo 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 (SameSitecorretto e, in produzione, cookiesecuresu HTTPS). - Non viene mai restituito un refresh token. Includere
offline_accessnello scope e verificare che l'applicazione sia configurata per ricevere refresh token.
Passi successivi
- Applicazione single-page React per un client che vive solo nel browser.
- Applicazioni per rivedere le durate dei token e le altre impostazioni del client.
OpenID Connect (Authorization Code + PKCE)
Il flusso OIDC Authorization Code con PKCE dall'inizio alla fine, con HTTP puro e curl, per comprendere ogni passaggio prima di ricorrere a una libreria.
Backend Python / Flask
Aggiungere l'accesso a un'app Python Flask utilizzando la libreria Authlib e il flusso Authorization Code con PKCE.