Configurare SCIM in Microsoft Entra ID

Importante: il provisioning SCIM si applica solo a Gemini Enterprise e Looker (Anteprima).

Questo documento descrive come configurare un tenant SCIM in un pool di identità della forza lavoro. Per saperne di più su SCIM, consulta Provisioning SCIM per la federazione delle identità per la forza lavoro.

Ogni pool di identità della forza lavoro supporta un solo tenant SCIM. Per configurare un nuovo tenant SCIM in un pool che ne ha già uno, devi prima eliminare definitivamente il tenant esistente.

Il flag --claim-mapping per un tenant SCIM può contenere solo espressioni Common Expression Language (CEL) specifiche. Per scoprire quali espressioni sono supportate, consulta Mappatura delle attestazioni.

Assicurati che il tuo IdP fornisca valori univoci e non vuoti per gli attributi mappati a google.subject e google.group. La sincronizzazione di valori duplicati non va a buon fine con un errore HTTP 409 Conflict, mentre i valori nulli o vuoti non vanno a buon fine con un errore HTTP 400 Bad Request. Per saperne di più, consulta Supporto SCIM.

Per configurare System for Cross-domain Identity Management (SCIM), segui questi passaggi:

1. Configura un tenant e un token SCIM in Google Cloud
2. Configura SCIM in Microsoft Entra ID
3. Aggiorna il provider per abilitare SCIM
4. Verifica la sincronizzazione SCIM

Configura un tenant e un token SCIM in Google Cloud

Per configurare un tenant SCIM in Google Cloud, segui questi passaggi:

1. Crea un tenant SCIM.

       gcloud iam workforce-pools providers scim-tenants create SCIM_TENANT_ID \
           --workforce-pool="WORKFORCE_POOL_ID" \
           --provider="PROVIDER_ID" \
           --display-name="SCIM_TENANT_DISPLAY_NAME" \
           --description="SCIM_TENANT_DESCRIPTION" \
           --claim-mapping="CLAIM_MAPPING" \
           --location="global"
       

   Sostituisci quanto segue:

   • SCIM_TENANT_ID: un ID per il tenant SCIM.
   • WORKFORCE_POOL_ID: l'ID del pool di forza lavoro che hai creato in precedenza in questo documento.
   • PROVIDER_ID: l'ID del provider del pool di identità della forza lavoro che hai creato in precedenza in questo documento.
   • SCIM_TENANT_DISPLAY_NAME: un nome visualizzato per il tenant SCIM.
   • SCIM_TENANT_DESCRIPTION: una descrizione del tenant SCIM.
   • CLAIM_MAPPING: un elenco separato da virgole di mappature degli attributi. Per l'elenco esteso degli attributi di mappatura, consulta Mappatura delle attestazioni. Per Gemini Enterprise è consigliata la seguente mappatura:

     google.subject=user.emails[0].value.lowerAscii(),google.group=group.externalId

     L'attributo google.subject che mappi nel tenant SCIM deve fare riferimento in modo univoco alle stesse identità mappate nell'attributo google.subject nel provider del pool di identità per la forza lavoro utilizzando il flag --attribute-mapping. Dopo aver creato il tenant SCIM, non puoi aggiornare la mappatura delle attestazioni. Per sostituirlo, puoi eliminare definitivamente il tenant SCIM e crearne immediatamente uno nuovo. Per saperne di più sulle considerazioni relative all'utilizzo di SCIM, consulta Supporto di SCIM.

2. Al termine del comando, segui questi passaggi:

   1. Nel campo baseUri dell'output, salva l'intero URI, che ha il formato https://iamscim.googleapis.com/v1alpha1/tenants/SCIM_TENANT_UID. Devi fornire questo URI al tuo IdP.
   2. Inoltre, dall'URI, salva solo SCIM_TENANT_UID. Questo UID è necessario per impostare una policy di autorizzazione IAM sul tenant SCIM più avanti in questo documento.

3. Crea un token SCIM:

       gcloud iam workforce-pools providers scim-tenants tokens create SCIM_TOKEN_ID \
           --display-name DISPLAY_NAME \
           --scim-tenant SCIM_TENANT_ID \
           --workforce-pool WORKFORCE_POOL_ID \
           --provider PROVIDER_ID \
           --location global
       

   Sostituisci quanto segue:

   • SCIM_TOKEN_ID: un ID per il token SCIM
   • DISPLAY_NAME: il nome visualizzato del token SCIM
   • WORKFORCE_POOL_ID: l'ID del pool di forza lavoro
   • SCIM_TENANT_ID: l'ID del tenant SCIM
   • PROVIDER_ID: l'ID del provider del pool di identità della forza lavoro

4. Al termine del comando gcloud iam workforce-pools providers scim-tenants tokens create, segui questi passaggi:

   1. Nell'output, salva il valore di SCIM_TOKEN nel campo securityToken. Devi fornire questo token di sicurezza al tuo IdP. Il token di sicurezza viene visualizzato solo in questo output e, se viene perso, devi creare un nuovo token SCIM.

   2. Per verificare se SCIM_TOKEN è rifiutato dalla policy dell'organizzazione, esegui questo comando:

      curl -v -H "Authorization: Bearer SCIM_TOKEN"  https://iamscim.googleapis.com/v1alpha1/tenants/SCIM_TENANT_UID/Users

      Se il comando non va a buon fine con un errore relativo alle autorizzazioni, esegui gcloud organizations add-iam-policy-binding, descritto in un passaggio successivo. Se il comando va a buon fine, puoi saltare questo passaggio.

5. Imposta una policy di autorizzazione IAM sul tenant e sul token SCIM. Se il comando curl in un passaggio precedente non è andato a buon fine con un errore relativo alle autorizzazioni, devi eseguire il seguente comando:

       gcloud organizations add-iam-policy-binding ORGANIZATION_ID \
           --member=serviceAccount:SERVICE_AGENT_EMAIL \
           --role roles/iam.scimSyncer
       

   Sostituisci quanto segue:

   • ORGANIZATION_ID: l'ID dell'organizzazione.
   • SERVICE_AGENT_EMAIL: l'indirizzo email dell'agente di servizio. L'indirizzo email è nel seguente formato: [e-mail]. SCIM_TENANT_UID viene restituito quando crei il tenant SCIM.

Quando esegui il provisioning dei gruppi nel tuo IdP, assicurati che il nome visualizzato di ogni gruppo, come fornito nel campo displayName, sia univoco all'interno di un tenant SCIM. Per scoprire di più sui gruppi e su SCIM in Microsoft Entra ID, consulta Gruppi.

Configura SCIM in Microsoft Entra ID

Per configurare SCIM in Microsoft Entra ID, segui questi passaggi:

1. Apri il portale Azure e accedi come utente con privilegi amministrativi globali.
2. Seleziona Microsoft Entra ID > Enterprise Apps (App aziendali).
3. Fai clic su Nuova applicazione.
4. In Browse Microsoft Entra App gallery (Sfoglia la galleria di app Microsoft Entra), fai clic su Create your own application (Crea la tua applicazione).
5. Nel riquadro Crea la tua applicazione visualizzato, segui questi passaggi:
   1. In Qual è il nome della tua app, inserisci il nome della tua app.
   2. Seleziona Integra qualsiasi altra applicazione non presente nella galleria (non inclusa nella galleria).
   3. Per creare l'app, fai clic su Crea.
6. Nella tua applicazione, segui questi passaggi:
   1. Nella sezione Manage (Gestisci), fai clic su Provisioning.
   2. Nel riquadro a destra, fai clic su Nuova configurazione.

   3. In Admin Credentials (Credenziali amministratore), in Tenant URL (URL tenant), inserisci l'URL SCIM ottenuto al momento della creazione del tenant SCIM, seguito da ?aadOptscim062020. Devi aggiungere ?aadOptscim062020 alla fine dell'URI di base.

      Questo parametro di query è richiesto da Microsoft Entra ID per garantire che le richieste SCIM PATCH siano conformi agli standard RFC SCIM. Per maggiori dettagli, consulta la documentazione di Microsoft.

      L'URL tenant finale in Microsoft Entra ID deve avere il seguente formato:

      https://iamscim.googleapis.com/v1alpha1/tenants/SCIM_TENANT_UID?aadOptscim062020

      Sostituisci SCIM_TENANT_UID con l'UID del tenant SCIM.

   4. In Secret token (Token secret), inserisci il token secret che hai ottenuto quando hai creato il token SCIM.
   5. Per testare la configurazione SCIM con la federazione delle identità per la forza lavoro, fai clic su Prova connessione.
   6. Per salvare la configurazione, fai clic su Crea.
7. Nella sezione Gestisci, segui questi passaggi:
   1. Fai clic su Mappatura attributi.
   2. Fai clic su Provision Microsoft Entra ID Users (Esegui il provisioning degli utenti di Microsoft Entra ID).
   3. Nella pagina Mappatura attributi, segui questi passaggi:
      1. Nella tabella Mappature attributi, individua la riga per externalId e fai clic su Modifica in quella riga. Nella pagina Modifica attributi, segui questi passaggi:
         1. Nell'elenco a discesa Attributo di origine, seleziona objectId.
         2. Fai clic su Ok.
      2. Per salvare la mappatura degli attributi, fai clic su Salva.

Aggiorna il provider per abilitare SCIM

Per abilitare SCIM per un provider, imposta il flag --scim-usage in base al target del prodotto:

• Attivato per i gruppi (enabled-for-groups): utilizzato per Gemini Enterprise. Utilizza i gruppi sincronizzati con SCIM per l'autorizzazione IAM e la valutazione delle policy. Gli attributi utente continuano a essere ricavati dai token di accesso IdP.
• Abilitato per utenti e gruppi (enabled-for-users-groups): utilizzato per Looker (Anteprima). Utilizza i dati di utenti e gruppi sincronizzati con SCIM come origine principale delle rivendicazioni per i workflow di autorizzazione IAM e di accesso OAuth.

Abilita SCIM per i gruppi (Gemini Enterprise)

OIDC

      gcloud iam workforce-pools providers update-oidc PROVIDER_ID \
          --workforce-pool=WORKFORCE_POOL_ID \
          --location=global \
          --scim-usage=enabled-for-groups
    

Sostituisci quanto segue:

• PROVIDER_ID: l'ID del provider del pool di identità della forza lavoro
• WORKFORCE_POOL_ID: l'ID del pool di forza lavoro

SAML

      gcloud iam workforce-pools providers update-saml PROVIDER_ID \
          --workforce-pool=WORKFORCE_POOL_ID \
          --location=global \
          --scim-usage=enabled-for-groups
    

Sostituisci quanto segue:

• PROVIDER_ID: l'ID del provider del pool di identità della forza lavoro
• WORKFORCE_POOL_ID: l'ID del pool di forza lavoro

Abilita SCIM per utenti e gruppi (Looker) (anteprima)

OIDC

      gcloud iam workforce-pools providers update-oidc PROVIDER_ID \
          --workforce-pool=WORKFORCE_POOL_ID \
          --location=global \
          --scim-usage=enabled-for-users-groups
    

Sostituisci quanto segue:

• PROVIDER_ID: l'ID del provider del pool di identità della forza lavoro
• WORKFORCE_POOL_ID: l'ID del pool di forza lavoro

SAML

      gcloud iam workforce-pools providers update-saml PROVIDER_ID \
          --workforce-pool=WORKFORCE_POOL_ID \
          --location=global \
          --scim-usage=enabled-for-users-groups
    

Sostituisci quanto segue:

• PROVIDER_ID: l'ID del provider del pool di identità della forza lavoro
• WORKFORCE_POOL_ID: l'ID del pool di forza lavoro

Per verificare la sincronizzazione SCIM, consulta Verifica la sincronizzazione SCIM.

Mappatura delle attestazioni

Quando configuri SCIM, definisci le mappature delle attestazioni (--claim-mapping) nel tenant SCIM per mappare gli attributi di utenti e gruppi SCIM agli attributi Google.

Attributi Google Cloud supportati per la mappatura delle attestazioni

La tabella seguente elenca gli attributi Google Cloud che puoi mappare nel tuo tenant SCIM (--claim-mapping) utilizzando il Common Expression Language (CEL):

AttributoGoogle Cloud	Requisito	Descrizione	Espressioni e limiti supportati
google.subject	Obbligatorio	Identificatore univoco dell'utente che esegue l'autenticazione. L'attributo IdP sottostante utilizzato per compilare google.subject deve essere identico sia nella mappatura del provider (--attribute-mapping) sia nel tenant SCIM (--claim-mapping). Se queste mappature non sono coerenti, gli utenti potrebbero essere in grado di accedere, ma non verranno riconosciuti come membri dei gruppi di cui è stato eseguito il provisioning SCIM.	Limitato alle seguenti espressioni di base (o con .lowerAscii()): user.externalId user.userName user.emails[0].value Lunghezza massima: 127 byte. Nota: questa mappatura è immutabile una volta creato il tenant SCIM. Per aggiornarla, devi eliminare definitivamente e ricreare il tenant SCIM.
google.group	Obbligatorio per i gruppi SCIM	Identificatore univoco per l'appartenenza al gruppo sincronizzata utilizzando SCIM.	Limitato alle seguenti espressioni di base (o con .lowerAscii()): group.externalId group.displayName Nota: questa mappatura è immutabile una volta creato il tenant SCIM. Per aggiornarla, devi eliminare definitivamente e ricreare il tenant SCIM.
google.display_name	Facoltativo	Un attributo che imposta il nome dell'utente che ha eseguito l'accesso nella console Google Cloud . Non può essere utilizzato nelle policy di autorizzazione IAM.	Viene mappato a un attributo stringa (ad esempio user.displayName o user.name.formatted). Lunghezza massima: 100 byte.
google.profile_photo	Facoltativo	Un URL della foto in miniatura dell'utente, visibile come immagine del profilo nella console Google Cloud . Non può essere utilizzato nelle policy di autorizzazione IAM.	Deve restituire una stringa URL valida (ad esempio user.photos.filter(p, p.type == 'thumbnail')[0].value o user.photos[0].value).
google.email	Facoltativo	Un attributo utilizzato per mappare gli indirizzi email dall'IdP ai prodotti integrati utilizzando l'integrazione del client OAuth della federazione delle identità per la forza lavoro. Non può essere utilizzato nelle policy di autorizzazione IAM.	Mappa a un attributo email (ad esempio user.emails.filter(e, e.type == 'work')[0].value o user.emails[0].value).
google.posix_username	Facoltativo	Una stringa del nome utente conforme a POSIX univoca utilizzata per SSH nel browser e OS Login con la federazione delle identità per la forza lavoro. Questo attributo non può essere utilizzato nelle policy di autorizzazione IAM.	La lunghezza massima è di 32 caratteri.
attribute.KEY	Facoltativo	Attributi personalizzati del tuo IdP che puoi utilizzare per definire la tua strategia di autorizzazione in una policy di autorizzazione IAM. Sostituisci KEY con il nome dell'attributo che vuoi utilizzare. Ad esempio, puoi definire un attributo personalizzato come costcenter = "1234" e farvi riferimento utilizzando principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workforcePools/WORKFORCE_POOL_ID/attribute.costcenter/1234. La concessione dell'accesso a questo identificatore dell'entità consente l'accesso a tutte le identità configurate nell'IdP con quel centro di costo.	Fino a 50 regole di mappatura degli attributi personalizzati. Dimensione massima per regola: 256 caratteri.

Esempi di mappature per la coerenza dei soggetti

Come descritto in Attributi supportati per la mappatura delle attestazioni, l'attributo IdP sottostante utilizzato per compilare google.subject deve essere identico sia nella mappatura del provider (--attribute-mapping) sia nel tenant SCIM (--claim-mapping). La tabella seguente mostra esempi di riferimento per Microsoft Entra ID:

Attributo Google	Mappatura del provider di pool di identità della forza lavoro	Mappatura dei tenant SCIM
google.subject	assertion.oid	user.externalId
google.subject	assertion.attributes['http://schemas.microsoft.com/identity/claims/objectidentifier'][0]	user.externalId
google.subject	assertion.email	user.emails[0].value
google.subject	assertion.attributes['http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress'][0]	user.emails[0].value
google.subject	assertion.email.lowerAscii()	user.emails[0].value.lowerAscii()
google.subject	assertion.attributes['http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress'][0].lowerAscii()	user.emails[0].value.lowerAscii()
google.subject	assertion.preferred_username	user.userName
google.subject	assertion.attributes['http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name'][0]	user.userName
google.subject	assertion.preferred_username.lowerAscii()	user.userName.lowerAscii()
google.subject	assertion.attributes['http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name'][0].lowerAscii()	user.userName.lowerAscii()

Verifica la sincronizzazione SCIM

Importante: poiché SCIM è basato su push dal tuo IdP, Google Cloud non estrae attivamente i dati né controlla lo stato della connessione. Se la connessione tra il tuo IdP e Google Cloud si interrompe senza preavviso, i dati di identità possono diventare obsoleti.

Nei workflow con durata della sessione estesa (ESL) che durano fino a 90 giorni, un utente disattivato potrebbe mantenere l'accesso fino alla sincronizzazione successiva o alla scadenza della sessione. Per impedire l'accesso non autorizzato, monitora e controlla continuamente lo stato della sincronizzazione SCIM.

Dopo aver configurato SCIM, puoi utilizzare curl per eseguire query sull'endpoint del servizio SCIM IAM (iamscim.googleapis.com) e verificare che gli utenti e i gruppi vengano sincronizzati con Google Cloud. Questi comandi richiedono un token SCIM valido e l'UID del tenant SCIM. Il servizio iamscim.googleapis.com implementa il protocollo SCIM 2.0 (RFC 7644). Per informazioni dettagliate sugli endpoint supportati, sui filtri delle query e sulle limitazioni, consulta Endpoint supportati e non supportati e Limitazioni delle funzionalità del protocollo.

Verifica la sincronizzazione degli utenti

Per verificare che un utente sia stato sincronizzato correttamente, cerca il suo userName utilizzando il seguente filtro:

curl -H "Authorization: Bearer SCIM_TOKEN" \
  "https://iamscim.googleapis.com/v1alpha1/tenants/SCIM_TENANT_UID/Users?filter=userName%20eq%20%22USER_NAME%22"

Esempio di risposta:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults": 1,
  "Resources": [
    {
      "id": "USER_ID",
      "userName": "USER_NAME",
      ...
    }
  ]
}

Verifica la sincronizzazione dei gruppi

Per verificare che un gruppo sia stato sincronizzato correttamente, cerca il displayName del gruppo utilizzando il seguente filtro:

curl -H "Authorization: Bearer SCIM_TOKEN" \
  "https://iamscim.googleapis.com/v1alpha1/tenants/SCIM_TENANT_UID/Groups?filter=displayName%20eq%20%22GROUP_NAME%22"

Esempio di risposta:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults": 1,
  "Resources": [
    {
      "id": "GROUP_ID",
      "displayName": "GROUP_NAME",
      ...
    }
  ]
}

Verifica l'iscrizione al gruppo

Per verificare se un utente specifico è membro di un gruppo, utilizza un filtro che specifichi sia l'ID gruppo sia l'ID utente.

curl -H "Authorization: Bearer SCIM_TOKEN" \
  "https://iamscim.googleapis.com/v1alpha1/tenants/SCIM_TENANT_UID/Groups?filter=id%20eq%20%22GROUP_ID%22%20and%20members%20eq%20%22USER_ID%22"

Esempio di risposta se l'utente è un abbonato:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults": 1,
  "Resources": [
    {
      "id": "GROUP_ID",
      "displayName": "GROUP_NAME",
      ...
    }
  ]
}

Esempio di risposta se l'utente non è un abbonato:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults": 0,
  "Resources": []
}

Nota: per ottenere GROUP_ID e USER_ID, trova prima il gruppo e l'utente utilizzando i filtri displayName e userName. Gli ID vengono restituiti nel campo id della risposta. Sostituisci SCIM_TOKEN, SCIM_TENANT_UID, USER_NAME, GROUP_NAME, GROUP_ID e USER_ID con i tuoi valori effettivi.

Forza l'eliminazione di un tenant SCIM

Per forzare l'eliminazione di un tenant SCIM, segui questi passaggi:

1. Se per il tuo provider è impostato --scim-usage=enabled-for-groups o --scim-usage=enabled-for-users-groups, disattivalo dalla configurazione del provider:

   OIDC

   gcloud iam workforce-pools providers update-oidc PROVIDER_ID \
       --workforce-pool=WORKFORCE_POOL_ID \
       --location=global \
       --scim-usage=SCIM_USAGE_UNSPECIFIED
   

   Sostituisci quanto segue:

   • PROVIDER_ID: l'ID del provider del pool di identità della forza lavoro
   • WORKFORCE_POOL_ID: l'ID del pool di forza lavoro

   SAML

   gcloud iam workforce-pools providers update-saml PROVIDER_ID \
       --workforce-pool=WORKFORCE_POOL_ID \
       --location=global \
       --scim-usage=SCIM_USAGE_UNSPECIFIED
   

   Sostituisci quanto segue:

   • PROVIDER_ID: l'ID del provider del pool di identità della forza lavoro
   • WORKFORCE_POOL_ID: l'ID del pool di forza lavoro

2. Elimina il tenant SCIM:

   gcloud iam workforce-pools providers scim-tenants delete SCIM_TENANT_ID \
       --workforce-pool=WORKFORCE_POOL_ID \
       --provider=PROVIDER_ID \
       --hard-delete \
       --location=global
   

   Sostituisci quanto segue:

   • SCIM_TENANT_ID: l'ID del tenant SCIM da eliminare
   • WORKFORCE_POOL_ID: l'ID del pool di forza lavoro
   • PROVIDER_ID: l'ID del provider del pool di identità della forza lavoro
   Per scoprire di più su SCIM, inclusa l'eliminazione dei tenant SCIM, consulta Supporto SCIM.

Passaggi successivi

• Risolvi i problemi relativi al provisioning SCIM
• Elimina gli utenti della federazione delle identità per la forza lavoro e i relativi dati
• Revoca le sessioni utente della federazione delle identità per la forza lavoro
• Scopri quali prodotti Google Cloud supportano la federazione delle identità per la forza lavoro
• Configura l'accesso degli utenti alla console (federato)