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

Questa pagina mostra come risolvere i problemi comuni relativi alla federazione delle identità per la forza lavoro.

Esaminare la risposta dell'IdP

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

Accesso basato su browser

Per esaminare la risposta restituita dall'IdP, genera un file HAR utilizzando uno strumento a 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, procedi nel seguente modo:

  1. Individua il valore del parametro della richiesta SAMLResponse nel file HAR registrato rispetto all'URL con il percorso /signin-callback.
  2. Decodificalo utilizzando uno strumento a tua scelta. Ad esempio, puoi utilizzare Encode/Decode degli Strumenti amministrativi Google.

OIDC

Per esaminare la risposta dell'IdP OIDC, procedi nel seguente modo. Questo approccio non funziona con il flusso di codice.

  1. Cerca il parametro della richiesta id_token nel file HAR registrato rispetto a un URL con il percorso /signin-callback.
  2. Decodificalo utilizzando uno strumento di debug JWT a 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 quando esegui il comando gcloud iam workforce-pools create-cred-config, quindi procedi nel seguente modo:

SAML

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

OIDC

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

Esaminare i log

Per determinare se Google Cloud sta comunicando con il tuo IdP e esaminare le informazioni sulle transazioni, puoi esaminare i log di Cloud Audit Logs.

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

Errori di gestione di pool e provider 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 del pool di identità per la forza lavoro, procedi nel seguente modo:

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

    1. Assicurati di avere il 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 dell'IdP.

    3. Nella Google Cloud console, 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 del 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 in che modo gli attributi Google, come 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 dell'attributo mostra il risultato booleano della 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 dell'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 modifiche necessarie.
    3. Per avviare un nuovo test e visualizzare i risultati aggiornati, fai clic su Salva e recupera di nuovo il token.

  • Esamina i token generati dall'IdP. Per scoprire come generare un token dall'IdP, consulta la documentazione dell'IdP.

  • Esamina la registrazione di controllo dettagliata della federazione delle identità per la forza lavoro in Cloud Audit Logs.

La registrazione di controllo dettagliata registra gli errori di autenticazione e autorizzazione insieme alle attestazioni ricevute dalla federazione delle identità per la forza lavoro.

Puoi attivare la registrazione di controllo dettagliata quando crei il provider del pool di identità per la forza lavoro. Per attivare la registrazione di controllo dettagliata, aggiungi il flag --detailed-audit-logging quando crei il provider del pool di identità per la forza lavoro.

Autorizzazione negata

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

INVALID_ARGUMENT: Missing OIDC web single sign-on config

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 del pool di identità per la 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 Creare un provider per impostare i campi in modo appropriato quando crei il provider del pool di identità per la forza lavoro OIDC.

Limite di frequenza superato. Riprova più tardi

Questo errore si verifica quando hai raggiunto il limite di quota per le risorse del pool di forza lavoro. Contatta il tuo Google Cloud rappresentante dell'account per richiedere un aumento della quota.

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 fornita viene rifiutata dalla condizione dell'attributo

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

Considera ad esempio la seguente condizione dell'attributo:

SAML

'gcp-users' in assertion.attributes.groups

OIDC

'gcp-users' in assertion.groups

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

Per risolvere questo errore, procedi nel seguente modo:

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

  2. Segui i passaggi descritti in Esaminare la risposta dell'IdP per visualizzare gli attributi restituiti dall'IdP e verificare se la condizione dell'attributo è ben formata e accurata.

  3. Accedi alla console di amministrazione dell'IdP e verifica se gli attributi IdP a cui viene fatto riferimento nella condizione dell'attributo sono configurati correttamente. Se necessario, consulta la documentazione dell'IdP.

L'attributo mappato deve essere di tipo STRING

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

Ad esempio, considera un provider del pool di identità per la 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, procedi nel seguente modo:

  1. Descrivi il provider utilizzato per l'accesso 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 viene mappato all'attributo role e l'attributo role viene visualizzato nell'esempio di errore riportato sopra.

  2. Segui le indicazioni riportate di seguito per aggiornare la mappatura degli attributi:

    • Se l'attributo che causa l'errore è un elenco di valori, identifica un attributo alternativo, stabile e con valori 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 sarà:

      attribute.role=assertion.attributes.myRole[0]

    • In alternativa, se l'attributo è noto per essere a valore singolo, aggiorna la mappatura degli attributi per utilizzare 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 a valore singolo dall'elenco, consulta la definizione del linguaggio e aggiorna di conseguenza la mappatura degli attributi.

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

Could not obtain a value for google.subject from the given credential

Questo errore si verifica quando l'attestazione obbligatoria google.subject non è stata mappata utilizzando la mappatura degli attributi impostata nella configurazione del provider del pool di identità per la forza lavoro.

Per risolvere questo errore, procedi nel seguente modo:

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

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

    Se il valore è vuoto o non corretto, accedi alla console di amministrazione dell'IdP ed esamina gli attributi configurati. Per gli attributi, verifica se l'utente interessato ha dati corrispondenti nel tuo IdP. Aggiorna la configurazione dell'IdP per correggere di conseguenza gli attributi o le informazioni utente.

  3. Riprova ad accedere.

Size of mapped attributes exceeds the limit

Si è verificato il seguente errore quando un utente federato tenta di accedere:

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 la federazione degli utenti Google Cloud. Per saperne di più sui limiti di mappatura degli attributi, consulta Mappature degli attributi.

Ad esempio, se l'IdP emette un numero elevato di google.groups che sono attributi mappati nel provider del pool di identità per la forza lavoro, un tentativo di accesso può non riuscire. Chiedi all'amministratore di limitare il numero di gruppi emessi dall'IdP.

Count of groups exceeds the limit

Si è verificato il seguente errore quando un utente federato tenta di accedere:

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 conteggio dei gruppi emessi dall'IdP

  • GROUPS_COUNT_LIMIT:il limite di conteggio dei gruppi di Google Cloud

Questo errore si è verificato quando il numero di gruppi emessi dall'IdP supera Google Cloud's limite. 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 la federazione degli utenti Google Cloud. Scopri di più sui limiti relativi ai gruppi in Mappature degli attributi.

SCIM tenant couldn't be found

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

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

There was an issue signing in with your identity provider.

Per risolvere questo errore:

  1. Configura un tenant SCIM e un token su Google Cloud.
  2. Collega il provider a un tenant SCIM.

400. That's an error

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

Per risolvere questo errore, procedi nel seguente modo:

  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à per la forza lavoro con la configurazione dell'IdP.

Errori di accesso degli attributi aggiuntivi

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

Login fails when extra attributes are configured

Se hai configurato attributi aggiuntivi, qualsiasi problema di configurazione, come un ID client, un client secret o un URI dell'emittente non corretti, causa il tentativo di accesso non riuscito.

Per risolvere questo errore, procedi nel seguente modo:

  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 scaduto.
  3. Nell'IdP, verifica che l'applicazione disponga delle autorizzazioni richieste.

Groups from SAML or OIDC assertion are ignored

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

Se gli utenti non visualizzano i gruppi previsti, assicurati che i gruppi vengano recuperati correttamente utilizzando il canale secondario 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.

Error connecting to the given credential's issuer

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

Per risolvere questo errore, procedi nel seguente modo:

  1. Descrivi il provider, ed esamina issuerUri configurato. Crea l'URL del documento di rilevamento aggiungendo /.well-known/openid-configuration all'URI dell'emittente. Ad esempio, se 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 documentazione dell'IdP per eseguirne il provisioning per l'accesso a internet.

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

      1. Verifica che l'URL non venga reindirizzato troppe volte prima di pubblicare il documento di rilevamento. In caso contrario, rivolgiti all'amministratore dell'IdP per risolvere il problema.
      2. Controlla il tempo di risposta dell'IdP. Rivolgiti all'amministratore dell'IdP per ridurre la latenza della risposta.
      3. Il documento di rilevamento aperto deve essere in formato JSON.

      4. Cerca un campo jwks_uri nel 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.

Failed to verify the signature in SAMLResponse

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

Per risolvere questo errore, procedi nel seguente modo:

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

  2. Accedi alla console di amministrazione dell'IdP e scarica il file XML dei metadati più recente.

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

  4. Riprova ad accedere.

Recipient in SAML assertion is not set to the correct ACS URL

Questo errore si verifica per un provider del pool di identità per la 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 Configurare gli URL di reindirizzamento nell'IdP, e riprova ad accedere.

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

Ad esempio, per il provider del pool di identità per la forza lavoro locations/global/workforcePools/example-pool/providers/example-provider, il campo Recipient contenente l'URL di reindirizzamento viene visualizzato nella risposta SAML dell'IdP nel seguente modo:

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

SAMLResponse destination does not match RP callback URL

Questo errore si verifica per un provider del pool di identità per la 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 Configurare gli URL di reindirizzamento nell'IdP.

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

Ad esempio, per un provider del pool di identità per la forza lavoro locations/global/workforcePools/example-pool/providers/example-provider, il campo Destination contenente l'URL di reindirizzamento viene visualizzato nella risposta SAML dell'IdP nel seguente modo:

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

Invalid assertion: missing or empty NameID

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

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

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

All <AudienceRestriction>s should contain the SAML RP entity ID

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

Per risolvere questo errore, procedi nel seguente modo:

  1. Consulta la documentazione dell'IdP per scoprire come configurare il pubblico nei tag AudienceRestriction che invia nella risposta SAML. In genere, il pubblico viene configurato impostando il campo Entity ID o Audience nella configurazione dell'IdP. Consulta la sezione SAML del provider del 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 Esaminare la risposta dell'IdP per visualizzare la risposta restituita dall'IdP e i AudienceRestriction impostati.