Risolvere i problemi relativi alla federazione delle identità per la forza lavoro

Per diagnosticare e risolvere gli errori di autenticazione e provisioning nella federazione delle identità per la forza lavoro, esamina le risposte del provider di identità (IdP) e Cloud Audit Logs. Questi controlli ti aiutano a identificare le mancate corrispondenze di configurazione e a ripristinare l'accesso degli utenti.

Esamina la risposta dell'IdP

Questa sezione mostra come esaminare la risposta del tuo provider di identità (IdP) per risolvere i problemi elencati in questo documento.

Accesso basato su browser

Per esaminare la risposta restituita dal tuo IdP, genera un file HAR utilizzando uno strumento di tua scelta. Ad esempio, puoi utilizzare lo Strumento di analisi HAR degli Strumenti amministrativi Google, che fornisce istruzioni per generare un file HAR e gli strumenti per caricarlo e analizzarlo.

SAML

Per esaminare la risposta dell'IdP SAML, segui questi passaggi:

  1. Individua il valore del parametro di richiesta SAMLResponse nel file HAR registrato per l'URL con percorso /signin-callback.
  2. Decodificalo utilizzando uno strumento di tua scelta, ad esempio Encode/Decode di Strumenti amministrativi Google.

OIDC

Per esaminare la risposta dell'IdP OIDC, segui questi passaggi. Questo approccio non funziona con il flusso di codice.

  1. Cerca il parametro di richiesta id_token nel file HAR registrato per un URL con il percorso /signin-callback.
  2. Decodificalo utilizzando uno strumento di debug JWT di tua scelta.

gcloud CLI

Per esaminare la risposta dell'IdP quando utilizzi gcloud CLI, copia i contenuti del file che hai passato nel flag --credential-source-file durante l'esecuzione del comando gcloud iam workforce-pools create-cred-config, quindi segui questi passaggi:

SAML

Decodifica la risposta dell'IdP SAML utilizzando uno strumento a tua scelta, ad esempio puoi utilizzare Encode/Decode di Strumenti amministrativi Google.

OIDC

Decodifica la risposta dell'IdP OIDC utilizzando uno strumento di debug JWT di tua scelta.

Esamina i log

Per determinare se Google Cloud comunica con il tuo IdP ed esaminare le informazioni sulle transazioni, puoi ispezionare i log di Cloud Audit Logs.

Per visualizzare esempi di log, consulta Esempi di audit log.

Errori di gestione dei provider e dei pool di forza lavoro

Questa sezione fornisce suggerimenti per correggere gli errori comuni che potresti riscontrare durante la gestione di pool e provider.

Errori generali di mappatura degli attributi

Per risolvere i problemi di mappatura degli attributi del provider di pool di identità della forza lavoro, procedi nel seguente modo:

  • Esamina gli attributi, altrimenti noti come attestazioni, nella configurazione dell'IdP. Verifica come le mappature degli attributi convertono gli attributi IdP in attributi Google Cloud e come le condizioni valutano questi attributi per consentire o negare l'accesso nella console Google Cloud .

    1. Assicurati di disporre del ruolo IAM Workforce Pool Editor (roles/iam.workforcePoolEditor).
    2. Per attivare il flusso di accesso basato su browser per la federazione delle identità per la forza lavoro, aggiungi https://auth.cloud.google/signin-callback/locations/global/workforcePools/POOL_ID/providers/PROVIDER_ID all'elenco degli URI di reindirizzamento consentiti del tuo IdP.
    3. Nella console Google Cloud , vai a Pool di identità per la forza lavoro.

      Vai a Pool di identità per la forza lavoro
    4. Nell'elenco dei pool, fai clic sul nome del pool che vuoi verificare.
    5. Nella pagina Dettagli del pool di forza lavoro, fai clic sul nome dell'IdP che vuoi verificare.
    6. Nella pagina Dettagli provider, fai clic su Esegui il debug del token IdP.
    7. Nella finestra di dialogo Accedi, accedi al tuo IdP come utente di test.

    La pagina Convalida gli attributi del provider mostra gli attributi mappati e il risultato della condizione dell'attributo.

    La sezione Attributi mappati dal token IdP mostra come gli attributi Google, ad esempio google.subject, vengono compilati dal token dell'IdP in base alla configurazione della mappatura. Se una mappatura non è corretta, viene visualizzata un'icona di errore.

    La sezione Condizione attributo mostra il risultato booleano della tua condizione. Se la condizione restituisce false, l'accesso viene bloccato.

    Per visualizzare il token di asserzione completo, fai clic su Visualizza token completo. Viene visualizzato l'oggetto JSON non elaborato del tuo IdP. Fai riferimento a una proprietà di primo livello nelle mappature utilizzando il formato assertion.PROPERTY_NAME.

    Per correggere eventuali errori, puoi modificare la configurazione:

    1. Nella pagina Convalida gli attributi del provider, fai clic su Modifica.
    2. Apporta le necessarie modifiche.
    3. Per avviare un nuovo test e visualizzare i risultati aggiornati, fai clic su Salva e recupera di nuovo il token.

  • Ispezionare i token generati dal tuo IdP. Per scoprire come generare un token dal tuo IdP, consulta la documentazione dell'IdP.

  • Esamina l'audit logging dettagliato della federazione delle identità per la forza lavoro in Cloud Audit Logs.

L'audit logging dettagliato registra gli errori di autenticazione e autorizzazione insieme alle attestazioni ricevute dalla federazione delle identità per la forza lavoro.

Puoi abilitare l'audit log dettagliato quando crei il provider del pool di identità della forza lavoro. Per attivare l'audit logging dettagliato, aggiungi il flag --detailed-audit-logging quando crei il provider del pool di identità della forza lavoro.

Autorizzazione negata

Questo errore si verifica quando l'utente che tenta di configurare la federazione delle identità per la forza lavoro non dispone del ruolo Amministratore pool di forza lavoro IAM (roles/iam.workforcePoolAdmin).

INVALID_ARGUMENT: configurazione SSO web OIDC mancante

Il seguente errore si verifica quando i campi web-sso-response-type e web-sso-assertion-claims-behavior non sono impostati durante la creazione di un provider di pool di identità della forza lavoro OIDC:

ERROR: (gcloud.iam.workforce-pools.providers.create-oidc) INVALID_ARGUMENT: Missing OIDC web single sign-on config.

Per risolvere questo errore, segui i passaggi descritti nella sezione Crea un provider per impostare i campi in modo appropriato quando crei il provider del pool di identità della forza lavoro OIDC.

Limite di frequenza superato (HTTP 429)

Questo errore si verifica quando la tua organizzazione ha esaurito la quota per lo scambio di token del pool di forza lavoro (sts.googleapis.com/workforce_requests).

Questa quota viene applicata per ogni organizzazione e il valore predefinito è 1000 richieste al minuto. Poiché questa quota è condivisa tra tutti i pool di forza lavoro, i provider, gli utenti e i workload automatizzati della tua organizzazione, un singolo client ad alta frequenza può causare errori HTTP 429 in tutta l'organizzazione, anche per gli amministratori. Per saperne di più, consulta Quote e limiti.

Prima di iniziare

Se hai eseguito l'accesso tramite la federazione delle identità per la forza lavoro, i comandi di Google Cloud CLI e le nuove sessioni di accesso alla console Google Cloud potrebbero essere limitati. Per eseguire questi passaggi quando la quota viene superata, utilizza un account amministratore che non esegue l'autenticazione tramite la federazione delle identità per la forza lavoro, ad esempio un account super amministratore Cloud Identity con accesso di emergenza.

Passaggio 1: verifica che la quota sia esaurita

Nella console Google Cloud , vai a IAM e amministrazione > Quote, imposta il selettore delle risorse sulla tua organizzazione (non su un progetto) e seleziona Richieste di scambio di token del pool di forza lavoro.

Vai a IAM e amministrazione > Quote

Passaggio 2: identifica l'origine del traffico

Gli scambi di token limitati vengono rifiutati prima della convalida delle credenziali, pertanto non vengono visualizzati in Cloud Audit Logs. Per identificare l'origine del traffico, utilizza uno dei seguenti metodi:

  • Esamina i log di accesso dell'IdP: nel tuo provider di identità, ad esempio il log di sistema di Okta o i log di accesso di Microsoft Entra ID, verifica se un'applicazione, un service principal o un account utente specifico emette token a una frequenza insolitamente elevata.
  • Esamina le configurazioni dei workload: controlla i job automatizzati, le pipeline CI/CD, gli agenti daemon e i workload GKE configurati con un file di configurazione delle credenziali della forza lavoro.

Passaggio 3: limita il traffico

Scegli l'opzione che risolve il traffico con il minor numero di interruzioni per la tua forza lavoro:

AzioneEffetti sui tuoi utenti
Arresta il workload (scala il deployment a zero, elimina il job o revoca il client nel tuo IdP) Nessuno. Opzione consigliata quando puoi identificare il workload specifico.
Disattiva l'accesso programmatico nel pool di forza lavoro Blocca tutti gli scambi di token programmatici per il pool, inclusi gcloud e kubectl per gli utenti umani. Google Cloud l'accesso alla console continua a funzionare.

Consigliato quando non riesci a individuare immediatamente il workload.
Disattiva il pool o il provider Blocca l'autenticazione per l'intero pool o provider di forza lavoro.

Per disattivare l'accesso programmatico:

gcloud iam workforce-pools update WORKFORCE_POOL_ID \
    --location=global \
    --disable-programmatic-signin

Dopo aver interrotto il workload problematico, riattiva l'accesso programmatico eseguendo il comando con il flag --no-disable-programmatic-signin.

Passaggio 4: evita che il problema si ripeta

  • Esegui la migrazione dei workload automatizzati alla federazione delle identità per i workload.
  • Riprova le richieste limitate con backoff esponenziale e jitter. I loop di ripetizione ravvicinati aumentano la saturazione ed estendono l'interruzione.
  • Avviso all'80% della quota per ricevere un avviso prima della saturazione.
  • Se la tua domanda in stato stabile supera regolarmente il limite, ti consigliamo di richiedere un aumento della quota tramite l'assistenza clienti Google Cloud prima che sia necessario.

Errori di accesso

Questa sezione fornisce suggerimenti per correggere gli errori comuni che un utente della federazione delle identità per la forza lavoro potrebbe riscontrare durante l'accesso.

Errori di accesso comuni

La credenziale specificata è stata rifiutata dalla condizione dell'attributo

Questo errore si verifica quando la condizione dell'attributo impostata sul provider del pool di identità della forza lavoro non è stata soddisfatta.

Ad esempio, considera la seguente condizione dell'attributo:

SAML

'gcp-users' in assertion.attributes.groups

OIDC

'gcp-users' in assertion.groups

In questo caso, l'errore viene visualizzato se l'elenco dei gruppi inviati nell'attributo groups dal tuo IdP non contiene gcp-users.

Per risolvere questo errore, segui questi passaggi:

  1. Descrivi il provider utilizzato per accedere e verifica che il attributeCondition sia corretto. Per informazioni sulle operazioni supportate nelle condizioni, consulta la definizione del linguaggio.

  2. Segui i passaggi descritti in Esamina la risposta dell'IdP per visualizzare gli attributi restituiti dall'IdP e verifica se la condizione dell'attributo è corretta e accurata.

  3. Accedi alla console di amministrazione del tuo IdP e controlla se gli attributi IdP a cui fa riferimento la condizione dell'attributo sono configurati correttamente. Se necessario, consulta la documentazione del tuo IdP.

L'attributo mappato deve essere di tipo STRING

Questo errore si verifica per un provider di pool di identità della forza lavoro SAML quando l'attributo specificato nel messaggio di errore dovrebbe essere una STRINGA con un singolo valore, ma è mappato a un elenco nella mappatura degli attributi.

Ad esempio, considera un provider di pool di identità della forza lavoro SAML con la mappatura degli attributi attribute.role=assertion.attributes.userRole. In un'asserzione SAML, un Attribute può avere più tag AttributeValue, come mostrato nell'esempio seguente. Pertanto, tutti gli attributi SAML sono considerati elenchi, quindi assertion.attributes.userRole è un elenco.

<saml:Attribute Name="userRole">
    <saml:AttributeValue>
      security-admin
    </saml:AttributeValue>
    <saml:AttributeValue>
      user
    </saml:AttributeValue>
</saml:Attribute>

In questo esempio, potresti visualizzare il seguente errore:

The mapped attribute 'attribute.role' must be of type STRING

Per risolvere il problema, segui questi passaggi:

  1. Descrivi il provider utilizzato per accedere e identifica l'attributo IdP impostato in attributeMapping. Confronta l'attributo con quello presentato nel messaggio di errore. Nell'esempio precedente, un attributo IdP denominato userRole è mappato all'attributo role e l'attributo role viene visualizzato nell'esempio di errore.

  2. Quando aggiorni la mappatura degli attributi, tieni presente quanto segue:

    • Se l'attributo che causa l'errore è un attributo con valore di elenco, identifica un attributo alternativo, stabile e con valore di stringa. Quindi, aggiorna la mappatura degli attributi per utilizzarlo facendo riferimento al primo elemento. Per l'esempio precedente, se myRole è stato identificato come attributo IdP alternativo a valore singolo, la mappatura degli attributi è la seguente:

      attribute.role=assertion.attributes.myRole[0]
      
    • In alternativa, se l'attributo è noto per avere un solo valore, aggiorna la mappatura degli attributi in modo che utilizzi il primo elemento dell'elenco. Per l'esempio precedente, se userRole contiene un solo ruolo, puoi utilizzare la seguente mappatura:

      attribute.role=assertion.attributes.userRole[0]
      
    • Per ricavare un identificatore stabile con un singolo valore dall'elenco, consulta Definizione del linguaggio e aggiorna la mappatura degli attributi di conseguenza.

Consulta la sezione Esamina la risposta dell'IdP per visualizzare la risposta restituita dall'IdP.

Impossibile ottenere un valore per google.subject dalla credenziale fornita

Questo errore si verifica quando non è stato possibile mappare l'attestazione richiesta google.subject utilizzando la mappatura degli attributi che hai impostato nella configurazione del provider del pool di identità della forza lavoro.

Per risolvere questo errore, segui questi passaggi:

  1. Descrivi il provider e ispeziona il attributeMapping. Identifica la mappatura configurata per google.subject. Se la mappatura non è corretta, aggiorna il provider del pool di identità della forza lavoro.

  2. Consulta la sezione Esamina la risposta dell'IdP per visualizzare la risposta restituita dall'IdP. Controlla il valore dell'attributo dalla risposta IdP mappato a google.subject nelle mappature degli attributi.

    Se il valore è vuoto o errato, accedi alla console di amministrazione dell'IdP e controlla gli attributi configurati. Per gli attributi, controlla se l'utente interessato dispone di dati corrispondenti nel tuo IdP. Aggiorna la configurazione dell'IdP per correggere gli attributi o le informazioni utente di conseguenza.

  3. Riprova ad accedere.

Le dimensioni degli attributi mappati superano il limite

Quando un utente federato tenta di accedere, si verifica il seguente errore:

The size of the entire mapped attributes exceeds the 16 KB limit.

Per risolvere il problema, chiedi all'amministratore dell'IdP di ridurre il numero di attributi emessi dall'IdP. L'IdP deve emettere solo gli attributi necessari per federare gli utenti con Google Cloud. Per scoprire di più sui limiti di mappatura degli attributi, consulta Mappature degli attributi.

Ad esempio, se il tuo IdP genera un numero elevato di google.groups che sono attributi mappati nel provider del pool di identità della forza lavoro, un tentativo di accesso potrebbe non riuscire. Chiedi all'amministratore di limitare il numero di gruppi emessi dall'IdP.

Il numero di gruppi supera il limite

Quando un utente federato tenta di accedere, si verifica il seguente errore:

The current count of GROUPS_COUNT mapped attribute google.groups exceeds the GROUPS_COUNT_LIMIT count limit. Either modify your attribute mapping or the incoming assertion to produce a mapped attribute that has fewer than GROUPS_COUNT_LIMIT groups.

Questo errore include i seguenti valori:

  • GROUPS_COUNT: il numero di gruppi emessi dall'IdP

  • GROUPS_COUNT_LIMIT: limite di conteggio di Google Cloudper i gruppi

Questo errore si verifica quando il numero di gruppi emessi dall'IdP supera il limite diGoogle Cloud. I gruppi vengono mappati a Google Cloud utilizzando l'attributo google.groups.

Per risolvere il problema, chiedi all'amministratore di ridurre il numero di gruppi emessi dall'IdP. L'IdP deve emettere solo i gruppi utilizzati per federare gli utenti in Google Cloud. Scopri di più sui limiti relativi ai gruppi nelle mappature degli attributi.

400. Errore

Questo errore si verifica quando la richiesta non è stata ricevuta come previsto o non è corretta.

Per risolvere questo errore, segui questi passaggi:

  1. Segui i passaggi descritti nella sezione Informare gli utenti su come accedere per verificare se stai seguendo i passaggi corretti per accedere.

  2. Confronta la configurazione del provider del pool di identità della forza lavoro con la configurazione dell'IdP.

Errori di accesso agli attributi aggiuntivi

Questa sezione fornisce suggerimenti per correggere gli errori durante l'utilizzo di attributi aggiuntivi.

L'accesso non riesce quando sono configurati attributi aggiuntivi

Se hai configurato attributi aggiuntivi, qualsiasi problema di configurazione, ad esempio un ID client, un client secret o un URI emittente errato, causa l'esito negativo del tentativo di accesso.

Per risolvere questo errore, segui questi passaggi:

  1. Descrivi il provider e verifica che l'ID client e l'URI dell'emittente siano corretti.
  2. Verifica che il client secret sia valido e non sia scaduto.
  3. Nel tuo IdP, verifica che l'applicazione disponga delle autorizzazioni richieste.

I gruppi dell'asserzione SAML o OIDC vengono ignorati

Quando vengono configurati attributi aggiuntivi, la federazione delle identità per la forza lavoro ignora le informazioni sui gruppi fornite direttamente nelle rivendicazioni SAML o OIDC. Utilizza invece solo i gruppi recuperati tramite il backchannel (ad esempio, utilizzando l'API Microsoft Graph).

Se i tuoi utenti non vedono i gruppi previsti, assicurati che i gruppi vengano recuperati correttamente utilizzando il backchannel e che tutti i filtri degli attributi siano configurati correttamente.

Errori di accesso OIDC

Questa sezione fornisce suggerimenti per correggere gli errori specifici di OIDC che un utente della federazione delle identità per la forza lavoro potrebbe riscontrare durante l'accesso.

Errore durante la connessione all'emittente della credenziale specificata

Questo errore si verifica quando un provider di pool di identità della forza lavoro OIDC non riesce a raggiungere il documento di rilevamento OIDC o l'URI JWKS.

Per risolvere questo errore, segui questi passaggi:

  1. Descrivi il provider e ispeziona il issuerUri configurato. Crea il documento di rilevamento URL aggiungendo /.well-known/openid-configuration all'URI dell'emittente. Ad esempio, se il tuo issuerUri è https://example.com, l'URL del documento di rilevamento sarà https://example.com/.well-known/openid-configuration.

  2. Apri l'URL del documento di rilevamento in una finestra di navigazione in incognito.

    1. Se l'URL non si apre o il browser visualizza un errore 404, consulta la documentazione dell'IdP per identificare l'URI dell'emittente corretto. Se necessario, aggiorna issuerUri nel provider del pool di identità per la forza lavoro.

      Se l'IdP è in esecuzione on-premise, consulta la relativa documentazione per eseguirne il provisioning per l'accesso tramite internet.

    2. Se l'URL si apre, verifica le seguenti condizioni:

      1. Verifica che l'URL non reindirizzi troppe volte prima di pubblicare il documento di rilevamento. In questo caso, consulta l'amministratore dell'IdP per risolvere il problema.
      2. Controlla il tempo di risposta dell'IdP. Rivolgiti all'amministratore dell'IdP per ridurre la latenza di risposta.
      3. Il documento di rilevamento aperto deve essere in formato JSON.
      4. Cerca un campo jwks_uri nel file JSON.

        1. Verifica che si apra anche il valore dell'URL associato.
        2. Verifica che l'URL soddisfi le condizioni descritte in precedenza in questa guida.
    3. Riprova ad accedere.

Errori di accesso SAML

Questa sezione fornisce suggerimenti per correggere gli errori specifici di SAML che un utente della federazione delle identità per la forza lavoro potrebbe riscontrare durante l'accesso.

Impossibile verificare la firma in SAMLResponse

Questo errore si verifica per un provider di pool di identità della forza lavoro SAML quando la firma nella risposta dell'IdP non può essere verificata utilizzando uno dei certificati X.509 forniti nel file XML dei metadati dell'IdP configurato nel provider di pool di identità della forza lavoro. Una causa comune di questo errore è che il certificato di verifica sul tuo IdP è stato ruotato, ma non hai aggiornato la configurazione del provider del pool di identità della forza lavoro con il file XML dei metadati dell'IdP più recente.

Per risolvere questo errore, segui questi passaggi:

  1. (Facoltativo) Segui i passaggi descritti in Ispeziona la risposta dell'IdP per visualizzare la risposta restituita dall'IdP e individuare il campo X509Certificate al suo interno. Descrivi il provider che hai utilizzato per accedere e controlla il campo X509Certificate presente nel valore idpMetadataXml impostato sul provider del pool di identità della forza lavoro. Confronta il certificato con quello visualizzato nella risposta restituita dal tuo IdP. I certificati devono corrispondere.

  2. Accedi alla console di amministrazione del tuo IdP e scarica l'XML dei metadati più recente.

  3. Aggiorna il provider di pool di identità per la forza lavoro con l'XML dei metadati IdP scaricato.

  4. Riprova ad accedere.

Il destinatario nell'asserzione SAML non è impostato sull'URL ACS corretto

Questo errore si verifica per un provider di pool di identità della forza lavoro SAML quando la risposta dell'IdP contiene un valore errato per il campo Recipient nel tag SubjectConfirmationData.

Per risolvere questo errore, aggiorna il campo Recipient URL/Redirect URL o il campo equivalente nella configurazione dell'IdP in modo da utilizzare l'URL di reindirizzamento descritto in Configura gli URL di reindirizzamento nell'IdP e riprova ad accedere.

Segui i passaggi descritti in Esamina la risposta dell'IdP per visualizzare la risposta restituita dall'IdP e verifica che il campo Recipient sia corretto.

Ad esempio, per il provider di pool di identità della forza lavoro locations/global/workforcePools/example-pool/providers/example-provider, il Recipient contenente l'URL di reindirizzamento viene visualizzato nella risposta SAML dell'IdP come segue:

<SubjectConfirmationData Recipient="https://auth.cloud.google/signin-callback/locations/global/workforcePools/example-pool/providers/example-provider"

La destinazione SAMLResponse non corrisponde all'URL di callback RP

Questo errore si verifica per un provider di pool di identità della forza lavoro SAML quando la risposta dell'IdP contiene un valore errato per il campo Destination nel tag Response.

Per risolvere questo errore, aggiorna il campo Destination URL/Redirect URL o il campo equivalente nella configurazione dell'IdP in modo da utilizzare l'URL di reindirizzamento descritto in Configura gli URL di reindirizzamento nell'IdP.

Segui i passaggi descritti in Esamina la risposta dell'IdP per visualizzare la risposta restituita dall'IdP e verificare che il campo Destination sia corretto.

Ad esempio, per un provider di pool di identità per la forza lavoro locations/global/workforcePools/example-pool/providers/example-provider, l'elemento Destination contenente l'URL di reindirizzamento viene visualizzato nella risposta SAML dell'IdP come segue:

<Response Destination="https://auth.cloud.google/signin-callback/locations/global/workforcePools/example-pool/providers/example-provider"

Asserzione non valida: NameID mancante o vuoto

Questo errore si verifica quando la risposta SAML ricevuta dal tuo IdP non contiene il campo NameId o ha un valore vuoto.

Per risolvere questo errore, consulta la documentazione dell'IdP per configurarlo in modo che invii NameID, che è l'oggetto di un'asserzione SAML, in genere l'utente che viene autenticato.

Segui i passaggi descritti in Esamina la risposta dell'IdP per visualizzare la risposta restituita dall'IdP e il valore NameID impostato.

Tutti i <AudienceRestriction> devono contenere l'ID entità della parte soggetta a limitazioni SAML

Questo errore si verifica quando i tag AudienceRestriction nella risposta SAML del tuo IdP non impostano un tag Audience con un valore che rappresenta l'ID entità del provider del pool di identità della forza lavoro.

Per risolvere questo errore, segui questi passaggi:

  1. Consulta la documentazione dell'IdP per scoprire come configurare il segmento di pubblico nei tag AudienceRestriction che invia nella risposta SAML. In genere, il segmento di pubblico viene configurato impostando il campo Entity ID o Audience nella configurazione dell'IdP. Consulta la sezione SAML di Crea un provider di pool di identità per la forza lavoro per visualizzare il valore SP Entity ID da impostare.

  2. Dopo aver aggiornato la configurazione dell'IdP, riprova ad accedere.

Segui i passaggi descritti in Esamina la risposta dell'IdP per visualizzare la risposta restituita dall'IdP e i AudienceRestriction impostati.

Errori di accesso SCIM

Questa sezione descrive come risolvere gli errori specifici di SCIM che un utente della federazione delle identità per la forza lavoro potrebbe riscontrare durante l'accesso.

Impossibile trovare il tenant SCIM

Questo errore si verifica quando un utente tenta di accedere utilizzando un provider di pool di identità per la forza lavoro configurato per l'utilizzo di SCIM, ma non è configurato alcun tenant SCIM per quel provider.

In questo caso, gli utenti ricevono il seguente errore quando tentano di accedere:

There was an issue signing in with your identity provider.

Per risolvere questo errore, segui questi passaggi per il tuo provider di identità:

  1. Configura un tenant e un token SCIM su Google Cloud (Microsoft Entra ID | Okta).
  2. Collega il provider a un tenant SCIM (Microsoft Entra ID | Okta).

L'accesso non riesce quando l'utilizzo di SCIM è abilitato per utenti e gruppi

Quando --scim-usage è impostato su enabled-for-users-groups, i tentativi di accesso web e OAuth potrebbero non riuscire con i seguenti messaggi di errore:

  • Utente SCIM non trovato o non attivo:

    • Errore: The workforce identity pool provider is configured to use identity information that is provided using SCIM, but a SCIM User could not be associated with the google.subject from the given credential. o ... the SCIM User associated with the google.subject from the given credential is not active.
    • Causa: l'utente non è stato sincronizzato con Google Cloud tramite SCIM, l'attributo google.subject mappato nel provider non corrisponde alla mappatura utente SCIM o l'utente è contrassegnato come active: false nell'IdP.
    • Risoluzione: nel tuo IdP, verifica che l'utente sia stato sottoposto a provisioning utilizzando SCIM, assicurati che il suo stato sia attivo e verifica che la mappatura degli attributi del provider e la mappatura delle attestazioni del tenant SCIM per google.subject facciano riferimento alla stessa identità.
    • Errore: Failed to map attributes from the given credential with SCIM Tenant config.
    • Causa: un'espressione CEL in --claim-mapping non è valida o non è riuscita durante la valutazione.
    • Risoluzione: esamina le espressioni --claim-mapping del tenant SCIM per assicurarti che la sintassi CEL sia valida e che i nomi degli attributi siano supportati.
  • Limiti di dimensione degli attributi mappati superati:

    • Errore: The size of SCIM mapped attribute google.display_name exceeds the 100 bytes limit. o The size of entire SCIM mapped attributes exceeds the 16 kB limit.
    • Causa: un singolo attributo mappato ha superato il limite di dimensioni (ad esempio, 100 byte per google.display_name, 32 byte per google.posix_username, 127 byte per google.subject) o il totale delle rivendicazioni mappate serializzate ha superato i 16 kB.
    • Risoluzione: modifica le mappature delle attestazioni del tenant SCIM o aggiorna i valori degli attributi IdP per rimanere entro i limiti consentiti.

Errori di provisioning e sincronizzazione SCIM

Questa sezione descrive come risolvere i problemi relativi al provisioning e alla sincronizzazione SCIM nella federazione delle identità per la forza lavoro.

Errore di autenticazione del token SCIM (HTTP 401 o 403)

Questo errore si verifica quando i log del provider di identità (IdP) segnalano errori di autenticazione (HTTP 401 Unauthorized o HTTP 403 Forbidden). Le cause più comuni includono:

  • Il token SCIM è mancante, non valido o scaduto.
  • Il token SCIM contiene spazi aggiuntivi.
  • La richiesta non contiene l'intestazione Authorization: Bearer <TOKEN>.
  • Il token SCIM non dispone di autorizzazioni sufficienti.

Per risolvere il problema, segui questi passaggi:

  1. Nella configurazione del provisioning dell'IdP, verifica che il token SCIM corrisponda al token secret generato in Google Cloud senza spazi vuoti aggiuntivi.
  2. Se il token viene perso o non è valido, genera un nuovo token SCIM:

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

    Sostituisci quanto segue:

    • SCIM_TOKEN_ID: un ID per il nuovo token SCIM.
    • WORKFORCE_POOL_ID: l'ID del pool di identità della forza lavoro.
    • PROVIDER_ID: l'ID del provider del pool di forza lavoro.
    • SCIM_TENANT_ID: l'ID del tenant SCIM.
  3. Aggiorna il token secret nella configurazione dell'IdP.

Limite di frequenza superato (HTTP 429 Troppe richieste)

Questo errore si verifica quando i tassi di richieste dell'IdP superano la quota del tenant SCIM. Per impostazione predefinita, le richieste di scrittura e lettura sono limitate a 3000 richieste per tenant SCIM per organizzazione al minuto, il che equivale a 50 query al secondo (QPS). Per saperne di più, consulta Quote e limiti.

Per risolvere il problema, segui questi passaggi:

  1. Verifica che il tasso di richieste di sincronizzazione dell'IdP rientri nei limiti di quota.
  2. Nella console Google Cloud , vai a IAM e amministrazione > Quote e filtra per iamscim.googleapis.com per monitorare l'utilizzo delle quote.
  3. Se hai bisogno di un throughput più elevato, richiedi un aumento della quota nella console Google Cloud .

La creazione del tenant SCIM non riesce

Questo errore si verifica quando il comando gcloud iam workforce-pools providers scim-tenants create non va a buon fine.

Di seguito sono elencate alcune delle possibili cause:

  • Esiste già un tenant SCIM nel pool di forza lavoro. Ogni pool di forza lavoro supporta un solo tenant SCIM.
  • Un tenant SCIM eliminato di recente è ancora nel periodo di eliminazione temporanea di 30 giorni.
  • Non disponi del ruolo IAM Workforce Pool Admin (roles/iam.workforcePoolAdmin).
  • Il flag --claim-mapping contiene espressioni CEL (Common Expression Language) non supportate.

Per risolvere il problema, segui questi passaggi:

  1. Verifica di disporre del ruolo IAM Amministratore pool di forza lavoro (roles/iam.workforcePoolAdmin).
  2. Elenca i tenant SCIM esistenti per verificare se un tenant esiste già:

    gcloud iam workforce-pools providers scim-tenants list \
        --workforce-pool="WORKFORCE_POOL_ID" \
        --provider="PROVIDER_ID" \
        --location="global"
    

    Sostituisci quanto segue:

    • WORKFORCE_POOL_ID: l'ID del pool di identità della forza lavoro.
    • PROVIDER_ID: l'ID del provider del pool di forza lavoro.
  3. Se un tenant eliminato in precedenza è stato eliminato temporaneamente, eliminalo definitivamente utilizzando il flag --hard-delete:

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

    Sostituisci SCIM_TENANT_ID con l'ID del tenant SCIM.

  4. Assicurati che --claim-mapping utilizzi solo espressioni CEL supportate. Per saperne di più, consulta Mappatura delle attestazioni.

La creazione del token SCIM non riesce

Questo errore si verifica quando il comando gcloud iam workforce-pools providers scim-tenants tokens create non va a buon fine.

Di seguito sono elencate alcune delle possibili cause:

  • Il tenant SCIM ha già il numero massimo di due token SCIM.
  • Non disponi del ruolo IAM Workforce Pool Admin (roles/iam.workforcePoolAdmin).

Per risolvere il problema, segui questi passaggi:

  1. Verifica di disporre del ruolo IAM Amministratore pool di forza lavoro (roles/iam.workforcePoolAdmin).
  2. Elenca i token SCIM esistenti per verificare se è stato raggiunto il limite di due token:

    gcloud iam workforce-pools providers scim-tenants tokens list \
        --workforce-pool="WORKFORCE_POOL_ID" \
        --provider="PROVIDER_ID" \
        --scim-tenant="SCIM_TENANT_ID" \
        --location="global"
    

    Sostituisci quanto segue:

    • WORKFORCE_POOL_ID: l'ID del pool di identità della forza lavoro.
    • PROVIDER_ID: l'ID del provider del pool di forza lavoro.
    • SCIM_TENANT_ID: l'ID del tenant SCIM.
  3. Se il tenant SCIM ha già due token, elimina un token inutilizzato o non valido:

    gcloud iam workforce-pools providers scim-tenants tokens delete SCIM_TOKEN_ID \
        --workforce-pool="WORKFORCE_POOL_ID" \
        --provider="PROVIDER_ID" \
        --scim-tenant="SCIM_TENANT_ID" \
        --location="global"
    

    Sostituisci SCIM_TOKEN_ID con l'ID del token SCIM da eliminare.

  4. Dopo aver eliminato il token, riprova a creare il nuovo token SCIM.

Conflitto di mappatura di attributi duplicati (conflitto HTTP 409)

Questo errore si verifica quando i log del provider di identità (IdP) segnalano un HTTP 409 Conflict durante la sincronizzazione perché l'IdP invia valori duplicati per google.subject o google.group oppure valori userName o displayName non univoci.

Per risolvere il problema, segui questi passaggi:

  1. Nella console di amministrazione dell'IdP, verifica che gli attributi mappati a google.subject e google.group producano valori non sovrapposti.
  2. Assicurati che ogni utente abbia un userName univoco e che ogni gruppo abbia un displayName univoco.

Le richieste PATCH di Microsoft Entra ID non vanno a buon fine

Questo errore si verifica quando gli aggiornamenti degli utenti o le richieste PATCH da Microsoft Entra ID non vanno a buon fine perché nell'URL tenant manca il parametro di query ?aadOptscim062020, necessario per le richieste PATCH conformi a RFC.

Per risolvere il problema, segui questi passaggi:

  1. In Microsoft Entra ID, vai alla tua applicazione aziendale e seleziona Provisioning > Gestisci provisioning > Credenziali amministratore.
  2. Nel campo Tenant URL (URL tenant), aggiungi ?aadOptscim062020 all'URI di base:

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

    Sostituisci SCIM_TENANT_UID con l'ID univoco del tuo tenant SCIM.

  3. Fai clic su Test Connection (Verifica connessione) e poi salva la configurazione.

L'accesso o la condivisione basati su utenti o gruppi non funzionano

Questo problema si verifica quando gli utenti sincronizzati non possono accedere alle risorse Google Cloud o quando la condivisione dei notebook in Gemini Notebook per le aziende o degli agenti nell'app Gemini Enterprise non va a buon fine.

Di seguito sono elencate alcune delle possibili cause:

  • Errori o ritardi di sincronizzazione silenziosi da parte dell'IdP.
  • Mappature delle attestazioni incoerenti tra il provider (--attribute-mapping) e il tenant SCIM (--claim-mapping).
  • Modifiche nell'IdP agli attributi mappati a google.subject o google.group. Google Cloud si aspetta che i valori mappati a questi attributi siano immutabili.
  • L'utilizzo di SCIM non è abilitato per i gruppi sul provider.

Per risolvere il problema, segui questi passaggi:

  1. Verifica la sincronizzazione e l'appartenenza: verifica che gli utenti, i gruppi e le relative appartenenze siano stati sincronizzati correttamente con Google Cloud:

    • Verifica la sincronizzazione degli utenti:

      curl -G -H "Authorization: Bearer SCIM_TOKEN" \
        "https://iamscim.googleapis.com/v1alpha1/tenants/SCIM_TENANT_UID/Users" \
        --data-urlencode 'filter=userName eq "USER_NAME"'
      
    • Verifica la sincronizzazione dei gruppi:

      curl -G -H "Authorization: Bearer SCIM_TOKEN" \
        "https://iamscim.googleapis.com/v1alpha1/tenants/SCIM_TENANT_UID/Groups" \
        --data-urlencode 'filter=displayName eq "GROUP_NAME"'
      
    • Verifica l'appartenenza al gruppo: conferma che un utente è membro di un gruppo:

      curl -G -H "Authorization: Bearer SCIM_TOKEN" \
        "https://iamscim.googleapis.com/v1alpha1/tenants/SCIM_TENANT_UID/Groups" \
        --data-urlencode 'filter=id eq "GROUP_ID" and members eq "USER_ID"'
      

      Se l'utente è un membro del gruppo, la risposta restituisce totalResults: 1. Se l'utente non è un membro, la risposta restituisce totalResults: 0.

    Sostituisci quanto segue:

    • SCIM_TOKEN: il tuo token secret SCIM.
    • SCIM_TENANT_UID: l'ID univoco del tuo tenant SCIM.
    • USER_NAME: il nome utente dell'utente sincronizzato.
    • GROUP_NAME: il nome visualizzato del gruppo sincronizzato.
    • GROUP_ID: l'ID SCIM del gruppo sincronizzato, restituito nel campo id della risposta alla query del gruppo.
    • USER_ID: l'ID SCIM dell'utente sincronizzato, restituito nel campo id della risposta alla query dell'utente.
  2. Controlla le mappature delle attestazioni: assicurati che l'attributo mappato a google.subject nel provider (ad esempio google.subject=assertion.email.lowerAscii()) corrisponda all'identità mappata nel tenant SCIM (ad esempio google.subject=user.emails[0].value.lowerAscii()). Poiché le mappature delle attestazioni sono immutabili, se le mappature non sono coerenti, devi eliminare definitivamente il tenant SCIM e ricrearlo con la mappatura corretta.

  3. Garantisci l'immutabilità degli identificatori: verifica che gli attributi IdP mappati a google.subject e google.group non siano cambiati. Google Cloudtratta i valori mappati a questi attributi come identificatori immutabili. Se il valore di un attributo è cambiato nel tuo IdP, ripristina la modifica nell'IdP o elimina definitivamente l'utente o il gruppo interessato dall'IdP e ricrealo con il nuovo valore in modo che l'identificatore corrisponda a quello previsto da Google Cloud.

  4. Abilita l'utilizzo dei gruppi SCIM: aggiorna il provider per abilitare SCIM per i gruppi:

    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 forza lavoro.
    • WORKFORCE_POOL_ID: l'ID del pool di identità della forza lavoro.

Le modifiche apportate nell'IdP sono in ritardo o non vengono applicate

Questo problema si verifica quando gli aggiornamenti dell'IdP relativi a utenti, iscrizioni a gruppi o eliminazioni non vengono visualizzati immediatamente in Google Cloud.

Poiché SCIM è basato su push, gli aggiornamenti dipendono dalla pianificazione della sincronizzazione dell'IdP. Ad esempio, Microsoft Entra ID si sincronizza ogni 40 minuti circa.

Per risolvere il problema, segui questi passaggi:

  1. Attendi il ciclo di sincronizzazione pianificato successivo dall'IdP.
  2. Per applicare immediatamente le modifiche, attiva una sincronizzazione on demand nella console di amministrazione dell'IdP.

Il provisioning degli utenti non va a buon fine a causa del formato dell'email

Questo errore si verifica quando la sincronizzazione di utenti specifici con Google Cloudnon va a buon fine e i log del tuo provider di identità (IdP) segnalano un errore HTTP 400 Bad Request con un errore SCIM invalidValue.

Google Cloud SCIM richiede esattamente un indirizzo email di lavoro per utente. Il provisioning non va a buon fine se l'IdP invia più email o se l'email non è di tipo work.

Per risolvere il problema, configura la mappatura degli attributi dell'IdP in modo che invii solo l'indirizzo email di lavoro principale.

Gli aggiornamenti dei gruppi non vanno a buon fine (HTTP PUT non supportato)

Questo errore si verifica quando gli aggiornamenti dei gruppi non vanno a buon fine perché il client utilizza HTTP PUT, che non è supportato. L'API SCIM di Google Cloud supporta solo HTTP PATCH per gli aggiornamenti dei gruppi.

Per risolvere il problema, configura l'IdP o il client personalizzato in modo che utilizzi HTTP PATCH per gli aggiornamenti dei gruppi.

L'aggiornamento del provider non va a buon fine con configurazioni che si escludono a vicenda

Questo errore si verifica quando la creazione o l'aggiornamento del provider non va a buon fine con uno dei seguenti messaggi:

  • Select one of scim_usage - ENABLED_FOR_USERS_GROUPS or extra_attributes_oauth2_client, but not both.
  • Select one of scim_usage or extended_attributes_oauth2_client, but not both.

L'impostazione --scim-usage=enabled-for-users-groups si esclude a vicenda con Attributi aggiuntivi (extra_attributes_oauth2_client) e Attributi estesi (extended_attributes_oauth2_client).

Per risolvere il problema, rimuovi la configurazione degli attributi aggiuntivi o estesi in conflitto dal provider o modifica l'impostazione --scim-usage.

Errori di scambio di token dell'API Cloud OAuth

Quando una richiesta di scambio di token non va a buon fine, l'API Cloud OAuth restituisce uno stato HTTP 400 Bad Request o 401 Unauthorized con una risposta JSON di errore OAuth 2.0 (RFC 6749). Il campo error indica uno dei seguenti codici di errore:

Codice di errore Descrizione Azioni
invalid_request Nella richiesta manca un parametro obbligatorio, è incluso un valore parametro non valido, è incluso un parametro più di una volta o la richiesta è in un formato non valido. Verifica che siano stati forniti tutti i parametri con codifica URL richiesti (grant_type, code o refresh_token, redirect_uri).
invalid_client Autenticazione client non riuscita. Verifica che client_id e client_secret OAuth registrati corrispondano, che il client OAuth sia abilitato per il tuo pool di identità per la forza lavoro e che l'intestazione Authorization: Basic sia codificata correttamente in Base64.
invalid_grant Il codice di autorizzazione o il token di aggiornamento fornito non è valido, è scaduto, è stato revocato, non corrisponde all'URI di reindirizzamento utilizzato nella richiesta di autorizzazione o è stato emesso per un altro client. Assicurati che il codice o il token non siano scaduti o non siano stati scambiati in precedenza.
unauthorized_client Il client OAuth autenticato non è autorizzato a utilizzare l'elemento grant_type richiesto. Verifica che la registrazione del client OAuth consenta la concessione di codici di autorizzazione o token di aggiornamento.
unsupported_grant_type Il grant type di autorizzazione non è supportato dal server di autorizzazione. Imposta grant_type su authorization_code o refresh_token.
invalid_scope L'ambito richiesto non è valido, è sconosciuto, non è in un formato corretto o supera gli ambiti concessi dal proprietario della risorsa. Verifica che gli ambiti richiesti corrispondano a quelli configurati sul client OAuth e siano validi per la tua applicazione.
resource_exhausted La richiesta ha superato la quota di scambio di token dell'API Cloud OAuth. Controlla l'utilizzo dell'API nella console Google Cloud o richiedi un aumento della quota.

Errori relativi alle informazioni utente e ai gruppi di Cloud OAuth

Quando una richiesta all'endpoint /userinfo o /groups non va a buon fine, l'API Cloud OAuth restituisce uno stato HTTP 400 Bad Request, 401 Unauthorized o 403 Forbidden con una risposta di errore del token di connessione OAuth 2.0 (RFC 6750/OpenID Connect Core). Il campo error indica uno dei seguenti codici di errore:

Codice di errore Stato HTTP Descrizione Azioni
invalid_request 400 Bad Request/401 Unauthorized Nella richiesta manca l'intestazione Authorization obbligatoria o l'intestazione non è nel formato corretto (ad esempio, non inizia con Bearer). Verifica che l'intestazione Authorization: Bearer ACCESS_TOKEN sia formattata correttamente.
invalid_token 401 Unauthorized Il token di accesso fornito non è valido, è scaduto o è stato revocato. Aggiorna il token di accesso utilizzando l'autorizzazione refresh_token o ripeti il flusso del codice di autorizzazione.
insufficient_scope 403 Forbidden Il token di accesso non ha l'ambito openid richiesto o il tenant del token non corrisponde all'organizzazione specificata nell'URL dell'endpoint con ambito dell'organizzazione. Verifica che il token sia stato richiesto con l'ambito openid richiesto e che tu stia chiamando l'endpoint corretto.