Collega un provider OpenID Connect

Usa questa guida quando il tuo provider di identità parla OpenID Connect invece che SAML. Funziona qualsiasi issuer certificato OIDC — Pocket ID, Keycloak, Auth0, Zitadel, Google Workspace e simili seguono tutti gli stessi passaggi; cambia solo il punto in cui il tuo provider mostra i valori.

Prerequisiti

• un provider OIDC su cui puoi creare un client — annota l’ID client e l’URL dell’emittente (la base sotto cui vive il documento .well-known/openid-configuration), più il suo segreto client quando il client è di tipo confidenziale (i client pubblici con PKCE non ne hanno),
• un server Control Center di cui sei amministratore (il proprietario del server).

Passaggi

1. Apri Impostazioni → Server → Accesso single sign-on e passa a OpenID Connect.
2. Compila URL dell’emittente, ID client e Segreto client (opzionale) quando il provider ne ha emesso uno. Control Center individua gli endpoint dal documento di discovery standard dell’issuer — nessuna configurazione per singolo provider.
3. Presso il provider, registra su quel client il redirect https://<your-server>/oidc/callback.
4. Se i tuoi gruppi rientrano in un claim diverso da groups, imposta il nome del Claim dei gruppi; se vuoi, mappa i gruppi sui ruoli (l’SSO non può mai concedere il ruolo proprietario).
5. Scegli la policy di appartenenza (aggiunta automatica a ogni spazio di lavoro, oppure un invito per ogni spazio di lavoro), attiva Usa OpenID Connect per l’accesso e premi Salva connessione.
6. Premi Testa connessione — il server recupera il documento di discovery dell’issuer e ne conferma gli endpoint, quindi un messaggio verde significa che tutto funziona tranne il round-trip del browser. Per verificare anche la registrazione del client, usa il verificatore qui sotto.
7. Esegui un accesso: la schermata di connessione web mostra Accedi con OpenID Connect, oppure apri direttamente https://<your-server>/oidc/login.

I claim (email, nome, gruppi) vengono letti dall’endpoint del token dell’issuer su TLS dal tuo server — il browser non li fornisce mai, quindi non è coinvolta alcuna verifica locale della firma JWT. Al client va consentito di richiedere lo scope openid profile email, che è esattamente ciò che chiede Control Center.

Poiché quel canale TLS è l’unica cosa che autentica i claim, l’URL dell’issuer deve essere https — un issuer in chiaro permetterebbe a chiunque si trovi sul percorso di rete di falsificare identità in blocco. http è accettato solo per gli issuer di loopback (localhost, 127.0.0.1, ::1), per lo sviluppo locale.

Client pubblico o client confidenziale?

La forma predefinita — e consigliata — è un client pubblico che usa il flusso authorization code con PKCE (RFC 7636): il code verifier monouso detenuto dal server sostituisce il segreto e lo scambio del token è vincolato alla richiesta di autorizzazione che lo ha avviato. Non c’è alcun segreto da far trapelare e un authorization code rubato è inutile senza il verifier. Alcuni provider chiamano «SPA» o «native» questo tipo di client quando lo crei.

Se invece il tuo provider ha emesso un client confidenziale, contrassegna il client come pubblico presso il provider (in entrambi i casi la PKCE resta attiva), oppure incolla il segreto client nel campo Segreto client (opzionale) della connessione. Il segreto è memorizzato nel file dei segreti del server con permessi 0600 (mai nel database), inviato all’endpoint del token come client_secret_post e non restituito mai via RPC; lasciando il campo vuoto al salvataggio, il segreto memorizzato resta invariato. Quando un accesso fallisce allo scambio del token, il log del server riporta l’errore del provider (invalid_client quasi sempre significa che il segreto manca o è sbagliato).

Raggiungibilità

L’accesso stesso è mediato dal browser: l’issuer reindirizza soltanto il browser dell’utente verso /oidc/callback e il tuo server effettua una chiamata HTTPS in uscita all’endpoint del token — non serve alcuna connessione in ingresso dall’issuer, quindi un server dietro NAT funziona purché i browser degli utenti possano raggiungerlo (LAN, VPN, Tailscale o un tunnel). Il provisioning SCIM è l’eccezione: l’IdP chiama direttamente il tuo server, il che richiede un tunnel o un URL pubblico — vedi esegui il provisioning degli utenti con SCIM.

Verifica la configurazione da questa pagina

Il verificatore qui sotto viene eseguito nel tuo browser. Recupera direttamente il documento di discovery del tuo issuer, quindi questo sito non lo vede mai, e applica le regole del server: un issuer https che corrisponde al documento, endpoint sull’origine dell’issuer stesso, PKCE S256 e il metodo di autenticazione del token richiesto dal tipo di client. Con un ID client e l’indirizzo del server, può aprire un accesso di prova che mostra se il client e il suo URI di reindirizzamento sono registrati. Non chiede mai il segreto client.

Runs in your browserYour browser fetches the discovery document straight from your issuer. Add a server address and it also asks that server which sign-in methods it offers. This site never receives what you type.

Issuer URL

Client ID (optional)

Needed for the test sign-in.

Groups claim (optional)

Client type

Public, PKCE only Confidential, has a client secret

Never paste the secret here. The check only needs to know whether one exists.

Server address (optional)

The address your users open. Adds a reachability check and a test sign-in.

Paste the discovery document instead

Discovery document JSON

For providers that block other sites from reading it.

Check issuer