Single Sign-On Keycloak

Last reviewed 2025-01-13 UTC

Questa guida mostra come configurare il servizio Single Sign-On (SSO) tra Keycloak e il tuo account Cloud Identity o Google Workspace utilizzando la federazione SAML. Il documento presuppone che tu abbia installato e stia utilizzando Keycloak.

Obiettivi

  • Configura il server Keycloak in modo che possa essere utilizzato come provider di identità (IdP) da Cloud Identity o Google Workspace.
  • Configura il tuo account Cloud Identity o Google Workspace in modo che utilizzi Keycloak per l'SSO.

Prima di iniziare

  1. Se non hai un account Cloud Identity, registrati per crearne uno.
  2. Assicurati che il tuo account Cloud Identity disponga dei privilegi di super amministratore.
  3. Se il server Keycloak viene utilizzato per gestire più di un realm, decidi quale realm vuoi utilizzare per la federazione.
  4. Assicurati di disporre dell'accesso amministrativo al realm selezionato.

Creare un profilo SAML

Per configurare Single Sign-On con Keycloak, devi prima creare un profilo SAML nel tuo account Cloud Identity o Google Workspace. Il profilo SAML contiene le impostazioni relative al server Keycloak, inclusi l'URL e il certificato di firma.

In un secondo momento, assegni il profilo SAML a determinati gruppi o unità organizzative.

Per creare un nuovo profilo SAML nel tuo account Cloud Identity o Google Workspace, segui questi passaggi:

  1. Nella Console di amministrazione, vai a Sicurezza > Autenticazione > SSO con IdP terzo.

    Vai a SSO con IdP terzo

  2. Fai clic su Profili SSO di terze parti > Aggiungi profilo SAML.

  3. Nella pagina Profilo SSO SAML, inserisci le seguenti impostazioni:

    • Nome: Keycloak
    • ID entità dell'IdP:

      Keycloak 17 o versioni successive

      https://KEYCLOAK/realms/REALM
      

      Keycloak 16 o versioni precedenti

      https://KEYCLOAK/auth/realms/REALM
      
    • URL della pagina di accesso:

      Keycloak 17 o versioni successive

      https://KEYCLOAK/realms/REALM/protocol/saml
      

      Keycloak 16 o versioni precedenti

      https://KEYCLOAK/auth/realms/REALM/protocol/saml
      
    • URL della pagina di uscita:

      Keycloak 17 o versioni successive

      https://KEYCLOAK/realms/REALM/protocol/openid-connect/logout
      

      Keycloak 16 o versioni precedenti

      https://KEYCLOAK/auth/realms/REALM/protocol/openid-connect/logout?redirect_uri=https://KEYCLOAK/auth/realms/REALM/account/
      
    • URL per la modifica della password:

      Keycloak 17 o versioni successive

      https://KEYCLOAK/realms/REALM/account
      

      Keycloak 16 o versioni precedenti

      https://KEYCLOAK/auth/realms/REALM/account
      

    In tutti gli URL, sostituisci quanto segue:

    • KEYCLOAK: il nome di dominio completo del server Keycloak
    • REALM: il nome del regno selezionato

    Non caricare ancora un certificato di verifica.

  4. Fai clic su Salva.

    La pagina Profilo SSO SAML visualizzata contiene due URL:

    • ID entità
    • URL ACS

    Questi URL ti serviranno nella sezione successiva, quando configurerai Keycloak.

Configura Keycloak

Configura il server Keycloak creando un client.

Crea un client

Crea un nuovo client SAML in Keycloak:

  1. Accedi a Keycloak e apri la console di amministrazione.
  2. Seleziona il realm che vuoi utilizzare per la federazione.
  3. Nel menu, seleziona Clienti.
  4. Fai clic su Crea cliente.
  5. Configura le seguenti impostazioni per il client:

    Keycloak 19 o versioni successive

    • Tipo di client: SAML
    • ID client: URL entità del tuo profilo SSO.
    • Nome: Google Cloud

    Keycloak 18 o versioni precedenti

    • ID client: URL entità del tuo profilo SSO.
    • Protocollo client: saml
    • Client SAML Endpoint (Endpoint SAML client): lascia vuoto
  6. Fai clic su Salva.

  7. Specifica i dettagli del client configurando le seguenti impostazioni:

    Keycloak 19 o versioni successive

    Nella scheda Impostazioni:

    • URI di reindirizzamento validi: URL ACS del tuo profilo SSO
    • Name ID Format (Formato ID nome): email
    • Forza formato ID nome: on
    • Firma i documenti: off
    • Sign Assertions: on

    Nella scheda Chiavi:

    • Client Signature Required: off

    Keycloak 18 o versioni precedenti

    • Name: un nome come Google Cloud
    • Sign Assertions: on
    • Client Signature Required: off
    • Forza formato ID nome: on
    • Name ID Format (Formato ID nome): email
    • URI di reindirizzamento validi: URL ACS del tuo profilo SSO

    Mantieni i valori predefiniti per tutte le altre impostazioni.

  8. Fai clic su Salva.

Esporta il certificato di firma

Dopo aver autenticato un utente, Keycloak trasmette un'asserzione SAML a Cloud Identity o Google Workspace. Per consentire a Cloud Identity e Google Workspace di verificare l'integrità e l'autenticità dell'asserzione, Keycloak firma l'asserzione con una chiave di firma del token speciale e fornisce un certificato che consente a Cloud Identity o Google Workspace di controllare la firma.

Ora esporta il certificato di firma da Keycloak:

  1. Nel menu, seleziona Impostazioni del regno.
  2. Seleziona la scheda Chiavi.
  3. Trova la riga per Algorithm: RS256. Se è presente più di una riga, utilizza quella con Usa: SIG. Poi seleziona Certificato.

    Viene visualizzata una finestra di dialogo contenente un certificato con codifica Base64.

  4. Copia il valore del certificato con codifica Base64 negli appunti.

Prima di poter utilizzare il certificato di firma, devi convertirlo in formato PEM aggiungendo un'intestazione e un piè di pagina.

  1. Apri un editor di testo come Blocco note o vim.
  2. Incolla la seguente intestazione, seguita da una nuova riga:

    -----BEGIN CERTIFICATE-----
    
  3. Incolla il certificato con codifica Base64 dagli appunti.

  4. Aggiungi una nuova riga e incolla il seguente piè di pagina:

    -----END CERTIFICATE-----
    

    Dopo la modifica, il file è simile al seguente:

    -----BEGIN CERTIFICATE-----
    MIICmzCCAYMCBgF7v8/V1TANBgkq...
    -----END CERTIFICATE-----
    
  5. Salva il file in una posizione temporanea sul computer.

Completa il profilo SAML

Utilizzi il certificato di firma per completare la configurazione del profilo SAML:

  1. Torna alla Console di amministrazione e vai a Sicurezza > Autenticazione > SSO con IdP terzo.

    Vai a SSO con IdP terzo

  2. Apri il profilo SAML Keycloak che hai creato in precedenza.

  3. Fai clic sulla sezione Dettagli IDP per modificare le impostazioni.

  4. Fai clic su Carica certificato e seleziona il certificato di firma token che hai scaricato in precedenza.

  5. Fai clic su Salva.

Il tuo profilo SAML è completo, ma devi ancora assegnarlo.

Assegna il profilo SAML

Seleziona gli utenti a cui deve essere applicato il nuovo profilo SAML:

  1. Nella Console di amministrazione, nella pagina SSO con IdP di terze parti, fai clic su Gestisci assegnazioni di profili SSO > Gestisci.

    Vai a Gestisci assegnazione di profili SSO

  2. Nel riquadro a sinistra, seleziona il gruppo o l'unità organizzativa a cui vuoi applicare il profilo SSO. Per applicare il profilo a tutti gli utenti, seleziona l'unità organizzativa principale.

  3. Nel riquadro a destra, seleziona Un altro profilo SSO.

  4. Nel menu, seleziona il profilo SSO Keycloak - SAML creato in precedenza.

  5. Fai clic su Salva.

Ripeti i passaggi per assegnare il profilo SAML a un altro gruppo o unità organizzativa.

Testare il Single Sign-On

Hai completato la configurazione Single Sign-On. Ora puoi verificare se SSO funziona come previsto.

  1. Scegli un utente Keycloak che soddisfi i seguenti criteri:

    • L'utente ha un indirizzo email.
    • L'indirizzo email corrisponde all'indirizzo email principale di un utente esistente nel tuo account Cloud Identity o Google Workspace.
    • L'utente Cloud Identity non dispone dei privilegi di super amministratore.

      Gli account utente con privilegi di super amministratore devono sempre accedere utilizzando le credenziali Google, pertanto non sono adatti per testare l'accesso unico.

  2. Apri una nuova finestra del browser e vai alla console.Google Cloud

  3. Nella pagina di accesso di Google, inserisci l'indirizzo email dell'account utente, quindi fai clic su Avanti.

    Pagina Accedi con Google.

    Viene visualizzata la pagina di Keycloak.

  4. Inserisci le tue credenziali Keycloak e poi fai clic su Accedi.

    Una volta autenticato, Keycloak ti reindirizza alla consoleGoogle Cloud . Poiché questo è il primo accesso per questo utente, ti viene chiesto di accettare i Termini di servizio e le Norme sulla privacy di Google.

  5. Se accetti i termini, fai clic su Accetta.

  6. Viene visualizzata la console Google Cloud , che ti chiede di confermare le preferenze e accettare i Google Cloud termini di servizio. Se accetti i termini, fai clic su , quindi su Accetta e continua.

  7. Fai clic sull'icona dell'avatar, quindi su Esci.

    Viene visualizzata la pagina di Keycloak.

Se hai difficoltà ad accedere, tieni presente che gli account utente con privilegi di super amministratore possono bypassare l'SSO, quindi puoi comunque utilizzare la Console di amministrazione per verificare o modificare le impostazioni.

(Facoltativo) Configura i reindirizzamenti per gli URL di servizio specifici del dominio

Quando crei un link alla Google Cloud console da portali o documenti interni, puoi migliorare l'esperienza utente utilizzando URL di servizio specifici del dominio.

A differenza degli URL di servizio regolari, come https://console.cloud.google.com/, gli URL di servizio specifici del dominio includono il nome del tuo dominio principale. Gli utenti non autenticati che fanno clic su un link a un URL di servizio specifico del dominio vengono reindirizzati immediatamente a Keycloak anziché visualizzare prima una pagina di accesso di Google.

Ecco alcuni esempi di URL di servizio specifici del dominio:

Servizio Google URL Logo
ConsoleGoogle Cloud https://www.google.com/a/DOMAIN/ServiceLogin?continue=https://console.cloud.google.com/ Logo Google Cloud
Documenti Google https://docs.google.com/a/DOMAIN Logo di Documenti Google
Fogli Google https://www.google.com/a/DOMAIN/ServiceLogin?continue=https://sheets.google.com/ Logo di Fogli Google
Google Sites https://www.google.com/a/DOMAIN/ServiceLogin?continue=https://slides.google.com/ Logo di Google Sites
Google Drive https://drive.google.com/a/DOMAIN Logo di Google Drive
Gmail https://mail.google.com/a/DOMAIN Logo di Gmail
Google Gruppi https://www.google.com/a/DOMAIN/ServiceLogin?continue=https://groups.google.com/ Logo di Google Gruppi
Google Keep https://www.google.com/a/DOMAIN/ServiceLogin?continue=https://keep.google.com/ Logo di Google Keep
Looker Studio https://www.google.com/a/DOMAIN/ServiceLogin?continue=https://lookerstudio.google.com/ Logo di Looker Studio
YouTube https://www.google.com/a/DOMAIN/ServiceLogin?continue=https://www.youtube.com/ Logo YouTube

Per configurare gli URL di servizio specifici del dominio in modo che reindirizzino a Keycloak, esegui le seguenti operazioni:

  1. Nella Console di amministrazione, nella pagina SSO con IdP di terze parti, fai clic su URL di servizio specifici del dominio > Modifica.

    Vai agli URL di servizio specifici del dominio

  2. Imposta Reindirizza automaticamente gli utenti all'IdP di terze parti nel profilo SSO seguente su attivato.

  3. Imposta Profilo SSO su Keycloak.

  4. Fai clic su Salva.

(Facoltativo) Configurare le verifiche dell'accesso

L'accesso a Google potrebbe chiedere agli utenti un'ulteriore verifica quando accedono da dispositivi sconosciuti o quando il tentativo di accesso sembra sospetto per altri motivi. Queste verifiche dell'accesso contribuiscono a migliorare la sicurezza e ti consigliamo di lasciarle attive.

Se ritieni che le verifiche dell'accesso causino troppi problemi, puoi disattivarle nel seguente modo:

  1. Nella Console di amministrazione, vai a Sicurezza > Autenticazione > Verifiche dell'accesso.
  2. Nel riquadro a sinistra, seleziona un'unità organizzativa per cui vuoi disattivare le verifiche dell'accesso. Per disattivare le richieste di accesso per tutti gli utenti, seleziona l'unità organizzativa principale.
  3. Nella sezione Impostazioni per gli utenti che eseguono l'accesso con altri profili SSO, seleziona Non chiedere agli utenti ulteriori verifiche da parte di Google.
  4. Fai clic su Salva.

Passaggi successivi