Provisioning SCIM per la federazione delle identità per la forza lavoro

Se il tuo provider di identità (IdP) supporta System for Cross-domain Identity Management (SCIM), puoi configurarlo per eseguire il provisioning e gestire utenti e gruppi in Google Cloud.

Funzionalità

Il supporto SCIM della federazione delle identità per la forza lavoro offre le seguenti funzionalità:

  • Sincronizzazione delle identità: sincronizza utenti e gruppi dal tuo IdP esterno a Google Cloud per mantenere una visione olistica delle identità della forza lavoro.
  • Origine principale per le rivendicazioni: quando SCIM è abilitato per un provider di forza lavoro, Google Cloud utilizza gli utenti e i gruppi SCIM sincronizzati come fonte di verità sia per gli attributi utente che per le appartenenze ai gruppi per la valutazione delle policy IAM.
  • Completamento automatico dell'identità: abilita il completamento automatico di utenti e gruppi quando concedi l'accesso e condividi risorse (come Notebooks e agenti) in Gemini Enterprise.

Considerazioni

Quando utilizzi il supporto SCIM della federazione delle identità per la forza lavoro, tieni presente quanto segue:

  • Prima di configurare un tenant SCIM, devi configurare un pool di identità della forza lavoro e un provider.
  • Ogni pool di identità della forza lavoro supporta un solo tenant SCIM, collegato a un singolo provider. Non puoi abilitare l'utilizzo di SCIM (--scim-usage) su nessun altro provider nello stesso pool. Per configurare un nuovo tenant SCIM nello stesso pool di identità della forza lavoro, devi prima eliminare quello esistente. Per eliminare un tenant SCIM, utilizza uno dei seguenti metodi:
    • Eliminazione temporanea (impostazione predefinita): l'eliminazione di un tenant SCIM avvia un periodo di eliminazione temporanea di 30 giorni. Durante questo periodo, il tenant è nascosto e non può essere utilizzato. Inoltre, non puoi creare un nuovo tenant SCIM nello stesso pool di identità della forza lavoro.
    • Eliminazione definitiva: per eliminare definitivamente e immediatamente un tenant SCIM, utilizza il flag --hard-delete con il comando delete. Questa azione è irreversibile e ti consente di creare immediatamente un nuovo tenant SCIM nello stesso pool di identità per la forza lavoro senza attendere il periodo di conservazione di 30 giorni. In alternativa, puoi creare un nuovo pool di identità per la forza lavoro e un nuovo tenant SCIM o utilizzare un pool di identità per la forza lavoro che non è stato configurato in precedenza con un tenant SCIM.
  • Modalità di utilizzo di SCIM (--scim-usage):
    • enabled-for-groups (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. Vengono valutate solo le mappature google.subject e google.group.
    • enabled-for-users-groups (Gemini Enterprise e Looker): utilizza i dati di utenti e gruppi sincronizzati con SCIM come origine delle rivendicazioni per l'autorizzazione IAM nei workflow di accesso web e OAuth. Valuta google.subject, google.group e tutte le attestazioni utente configurate (come google.display_name, google.profile_photo, google.email, google.posix_username e attribute.<var>KEY</var> personalizzate).
  • Esclusività reciproca: l'impostazione --scim-usage=enabled-for-users-groups si esclude a vicenda con gli attributi aggiuntivi (extra_attributes_oauth2_client) e gli attributi estesi (extended_attributes_oauth2_client).
  • Quando utilizzi SCIM, mappi gli attributi sia nel provider del pool di identità per la forza lavoro sia nel tenant SCIM. L'attributo google.subject deve fare riferimento in modo univoco alle stesse identità. Specifica google.subject nel provider del pool di identità per la forza lavoro utilizzando il flag --attribute-mapping e nel tenant SCIM utilizzando il flag --claim-mapping. La mappatura di valori di identità non univoci può far sì che Google Cloud tratti identità IdP diverse come la stessa identità. Di conseguenza, l'accesso concesso a un'identità utente o gruppo può estendersi ad altri, ma la revoca dell'accesso da un'identità potrebbe non rimuoverlo da tutte.
  • Se abiliti l'utilizzo di SCIM su un provider senza un tenant SCIM collegato, i tentativi di accesso non vanno a buon fine perché Google Cloud non riesce a trovare un tenant SCIM per quel provider.
  • Applicazione dell'univocità: Google Cloud convalida e applica l'univocità agli attributi mappati a google.subject (utenti) e google.group (gruppi) in un tenant SCIM. Se gli attributi mappati di cui il tuo IdP esegue il provisioning generano valori duplicati per google.subject o google.group durante la sincronizzazione, il provisioning non va a buon fine e viene visualizzato un errore HTTP 409 Conflict. Se un attributo mappato restituisce un valore nullo o vuoto, il provisioning non va a buon fine e viene visualizzato un errore HTTP 400 Bad Request.
  • Limiti di dimensione degli attributi: la dimensione massima degli attributi utente mappati serializzati (escluso google.group) è 16 kB. Se gli attributi mappati superano questo limite, i tentativi di accesso non vanno a buon fine.
  • Limite di token SCIM: ogni tenant SCIM supporta un massimo di due token SCIM (ad esempio, per supportare la rotazione dei token senza tempi di inattività). Se hai due token, elimina un token esistente prima di crearne uno nuovo.
  • L'API SCIM (iamscim.googleapis.com) è soggetta a quote di frequenza diverse dalle quote API delle risorse IAM standard. Per impostazione predefinita, le richieste di scrittura e lettura sono limitate a 3000 richieste per tenant SCIM per organizzazione al minuto. Per saperne di più, consulta Quote e limiti.

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 linguaggio CEL (Common Expression Language):

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 univoca conforme a POSIX 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 di 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.

Comportamento basato sull'utilizzo di SCIM del provider (--scim-usage)

La valutazione delle mappature delle attestazioni SCIM dipende dalla modalità --scim-usage configurata sul provider del pool di identità della forza lavoro:

  • enabled-for-groups (Gemini Enterprise): vengono valutate solo le mappature google.subject e google.group. Eventuali mappature delle attestazioni utente aggiuntive in --claim-mapping vengono ignorate.
  • enabled-for-users-groups (Gemini Enterprise e Looker): valuta google.subject, google.group e tutte le attestazioni utente configurate (come google.display_name, google.profile_photo, google.email, google.posix_username e attribute.<var>KEY</var> personalizzate). Google Cloud utilizza le attestazioni SCIM nei seguenti workflow di accesso:
    • Accesso web: quando gli utenti accedono a Gemini Enterprise, Google Cloud utilizza le attestazioni di utenti e gruppi sincronizzati con SCIM. Quando gli utenti accedono ad altri prodotti, come la console Google Cloud , Google Cloud utilizza gli attributi mappati dal token IdP dal flag --attribute-mapping del provider.
    • Accesso OAuth: quando gli utenti accedono alle applicazioni Gemini Enterprise e Looker che utilizzano il flusso OAuth della federazione delle identità per la forza lavoro, Google Cloud utilizza le attestazioni di utenti e gruppi sincronizzati con SCIM. Quando gli utenti accedono ad altre applicazioni, Google Cloud utilizza gli attributi mappati dal token IdP dal flag --attribute-mapping del provider.

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:

Attributo Google Mappatura del provider di pool di identità della forza lavoro Mappatura dei tenant SCIM (SCIM)
google.subject assertion.oid (Entra ID) user.externalId
google.subject assertion.sub (Okta) user.externalId
google.subject assertion.preferred_username user.userName
google.subject assertion.preferred_username.lowerAscii() user.userName.lowerAscii()
google.subject assertion.email user.emails[0].value
google.subject assertion.email.lowerAscii() user.emails[0].value.lowerAscii()

Endpoint supportati e non supportati

Il servizio IAM SCIM (iamscim.googleapis.com) implementa il protocollo SCIM 2.0 (RFC 7644) e gestisce le richieste all'indirizzo baseUri del tuo tenant SCIM:

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

In questo URI, SCIM_TENANT_UID è l'identificatore univoco del tuo tenant SCIM.

Il servizio IAM SCIM supporta i seguenti endpoint del protocollo SCIM standard relativi al tenant baseUri:

  • /Users: gestisci le risorse utente. Operazioni supportate: Create, Get, Update, Delete, Patch e Put.

  • /Groups: gestisci le risorse del gruppo. Operazioni supportate: Create, Get, Update, Delete e Patch. Il metodo PUT non è supportato per i gruppi.

  • /Schemas: recupera le informazioni sullo schema.

  • /ServiceProviderConfig: recupera la configurazione del fornitore di servizi.

I seguenti endpoint del protocollo SCIM non sono supportati:

  • /Me

  • /Bulk

  • /Search

  • /ResourceTypes

Limitazioni

Le sezioni seguenti descrivono le limitazioni e le deviazioni dell'implementazione SCIM della federazione delle identità per la forza lavoro rispetto alle specifiche SCIM (RFC 7643 e 7644).

Limitazioni delle funzionalità del protocollo

  • Supporto dei filtri: quando elenchi utenti o gruppi utilizzando gli endpoint /Users o /Groups, le espressioni di filtro supportano solo l'operatore eq (uguale). Puoi combinare più filtri eq con and. Altri operatori di filtro SCIM, come co (contiene) o sw (inizia con), non sono supportati.

  • Paginazione: l'API SCIM IAM non supporta la paginazione standard per l'elenco di utenti o gruppi.

    • startIndex: questo parametro è sempre 1. L'API restituisce fino a 100 risultati, indipendentemente dal valore fornito per startIndex.

    • itemsPerPage: il numero massimo di risorse restituite in una singola risposta è 100.

    • totalResults: l'API non restituisce il conteggio totale effettivo delle risorse corrispondenti. Il campo totalResults nella risposta è sempre uguale al numero di elementi restituiti nella risposta, con un massimo di 100.

  • Recupero di un gruppo ed elenco dei gruppi senza filtro: le API GetGroup e ListGroups restituiscono un elenco di membri vuoto. Per recuperare i membri di un gruppo specifico, utilizza l'API ListGroups con un filtro dei membri.

  • Risposta JSON non conforme con token non validi: le richieste che contengono un token API non valido restituiscono un codice di stato HTTP 401 da Google Cloud. La risposta non è un JSON valido come richiesto dalla specifica SCIM.

Limitazioni del comportamento SCIM

  • Identificatori immutabili: i valori degli attributi SCIM mappati a google.subject o google.group vengono trattati come identificatori immutabili all'interno di Google Cloud. Se devi modificare questi valori, devi eliminare definitivamente l'utente o il gruppo dal tuo IdP e poi ricrearlo con il nuovo valore.

  • Identificatori univoci e non vuoti: Google Cloud impone l'univocità dei valori mappati a google.subject e google.group in un tenant SCIM. La sincronizzazione degli attributi mappati che generano valori duplicati per google.subject o google.group non va a buon fine e restituisce un errore HTTP 409 Conflict. Gli attributi mappati che restituiscono un valore nullo o vuoto non vanno a buon fine con un errore HTTP 400 Bad Request.

  • Requisito di un singolo indirizzo email: per una sincronizzazione SCIM corretta, ogni utente deve avere esattamente un indirizzo email di tipo work. Il provisioning o gli aggiornamenti non andranno a buon fine se l'IdP invia più email o se l'unica email fornita non è di tipo work.

  • Trasformazioni senza distinzione tra maiuscole e minuscole: per le mappature delle attestazioni SCIM sono supportate trasformazioni limitate del Common Expression Language (CEL). Per i confronti senza distinzione tra maiuscole e minuscole per user.userName e user.emails[0].value è supportato solo .lowerAscii().

Limitazioni degli attributi

Le sezioni seguenti descrivono il supporto degli attributi per utenti, gruppi ed estensione dello schema utente aziendale.

Attributi utente

La tabella seguente elenca gli attributi utente e la loro disponibilità nelle attestazioni della federazione delle identità per la forza lavoro:

Attributo Attributi secondari Supportato nel provisioning SCIM Limitazioni Supportata in --claim-mapping
userName N/D Sì N/D Sì
name formatted, familyName, givenName, middleName, honorificPrefix, honorificSuffix Sì N/D Sì
displayName N/D Sì N/D Sì
nickName N/D Sì N/D Sì
profileUrl N/D Sì N/D Sì
title N/D Sì N/D Sì
userType N/D Sì N/D Sì
preferredLanguage N/D Sì N/D Sì
locale N/D Sì N/D Sì
timezone N/D Sì N/D Sì
active N/D Sì N/D Sì
password N/D No N/D No
emails display, type, value, primary Sì È supportato solo il tipo di email work. Sì
phoneNumbers display, type, value, primary Sì N/D Sì
ims display, type, value Sì N/D Sì
photos display, type, value Sì N/D Sì
addresses formatted, streetAddress, locality, region, postalCode, country Sì N/D Sì
groups N/D No N/D No
entitlements display, type, value Sì N/D Sì
roles type, value Sì display non è supportato. Sì
x509Certificates type, value Sì display non è supportato. No

Attributi del gruppo

La tabella seguente elenca gli attributi di gruppo e la loro disponibilità nelle rivendicazioni della federazione delle identità per la forza lavoro:

Attributo Attributi secondari supportati Supportata in --claim-mapping
displayName N/D Sì
externalId N/D Sì
members value, type, $ref, display No

Attributi di estensione dello schema utente aziendale

La tabella seguente descrive in dettaglio il supporto per l'estensione dello schema utente aziendale:

Attributo Attributi secondari supportati Supportata in --claim-mapping
employeeNumber N/D Sì
costCenter N/D Sì
organization N/D Sì
division N/D Sì
department N/D Sì
manager value, $ref, displayName Sì ($ref è supportato solo nel provisioning SCIM, non in --claim-mapping)

Passaggi successivi