Risoluzione dei problemi relativi alla federazione delle identità per la forza lavoro

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

Controlla la risposta dell'IdP

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

Accesso basato su browser

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

SAML

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

  1. Individua il valore del parametro di richiesta SAMLResponse nel file HAR che viene registrato in base all'URL con percorso /signin-callback.
  2. La decodifica utilizzando uno strumento a tua scelta, ad esempio, puoi utilizzare Codifica/Decodifica degli Strumenti amministrativi Google.

OIDC

Per ispezionare la risposta dell'IdP OIDC, segui questi passaggi:

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

Interfaccia a riga di comando gcloud

Per ispezionare la risposta del tuo IdP quando utilizzi gcloud CLI, copia il contenuto del file che hai passato nella --credential-source-file quando si esegue gcloud iam workforce-pools create-cred-config, quindi esegui il comando i passaggi seguenti:

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 e esaminare le informazioni sulle transazioni, puoi ispezionare i log di Cloud Audit Logs. Per esempi di log, consulta Esempi di audit log.

Errori di gestione del provider e del pool di forza lavoro

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

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 Workload Identity IAM (roles/iam.workforcePoolAdmin).

INVALID_text: Manca la configurazione Single Sign-On web OIDC

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à di 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à della forza lavoro OIDC.

Limite di frequenza superato. Riprova più tardi

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

Errori di accesso

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

Errori di accesso comuni

La credenziale specificata viene rifiutata dalla condizione dell'attributo

Questo errore si verifica quando condizione dell'attributo impostato sul provider del pool di identità della forza lavoro non è stato soddisfatto.

Ad esempio, considera la seguente condizione degli attributi:

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 dall'identity provider (IdP) non contiene gcp-users.

Per risolvere questo errore, procedi nel seguente modo:

  1. Descrivi il fornitore utilizzato per accedere e controlla che attributeCondition sia corretto. Per informazioni sulle operazioni supportate nelle condizioni, vedi il Definizione di lingua.

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

  3. Accedi alla Console di amministrazione dell'IdP e controlla se gli attributi dell'IdP a cui si fa riferimento nella 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 STRING a valore singolo, ma è mappato a un elenco nella mappatura degli attributi.

Ad esempio, considera un provider di pool di identità per la forza lavoro SAML che ha la mappatura degli attributi attribute.role=assertion.attributes.userRole. In un'affermazione 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 accedere e identifica l'attributo IdP impostato in attributeMapping. Confronta l'attributo con quello indicato nel messaggio di errore. Nell'esempio precedente, un attributo IdP denominato userRole è mappato agli attributi role e role 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 ha un valore di elenco, identifica una un attributo alternativo, stabile con valore stringa. Quindi, aggiorna l'attributo per utilizzarlo facendo riferimento al primo elemento. Per l'esempio precedente, se myRole è stato identificato come attributo IdP a valore singolo alternativo, la mappatura degli attributi sarebbe:

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

    • In alternativa, se è noto che l'attributo è a valore singolo, aggiorna la mappatura dell'attributo in modo da 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 un singolo valore dall'elenco, consulta Definizione di lingua e aggiorna la mappatura degli attributi di conseguenza.

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

Impossibile ottenere un valore per google.subject dalla credenziale specificata

Questo errore si verifica quando non è possibile mappare il claim obbligatorio google.subject utilizzando la mappatura degli attributi impostata nella configurazione del provider del pool di identità della forza lavoro.

Per risolvere questo errore, svolgi i seguenti passaggi:

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

  2. Consulta la sezione Esaminare la risposta dell'IDP per visualizzare la risposta restituita dall'IDP. Controlla 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 e e controllare gli attributi configurati. Per gli attributi, controlla se l'utente interessato ha dati corrispondenti nel tuo provider di identità. Aggiorna la configurazione dell'IDP per correggere di conseguenza gli attributi o le informazioni utente.

  3. Riprova ad accedere.

400. Errore

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

Per risolvere questo errore, svolgi i seguenti passaggi:

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

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

Errori di accesso OIDC

Questa sezione fornisce suggerimenti per correggere errori specifici 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à per la forza lavoro OIDC non è in grado di raggiungere il documento di rilevamento OIDC o l'URI JWKS.

Per risolvere questo errore, procedi nel seguente modo:

  1. Descrivi il provider e controlla il issuerUri configurato. Costruisci l'URL del documento di rilevamento 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 restituisce un errore 404, consulta della documentazione dell'IdP per identificare l'URI dell'emittente corretto. Se necessario, aggiorna issuerUri nel pool di identità della forza lavoro o il provider di servizi di terze parti.

      Se l'IdP è in esecuzione on-premise, consulta la relativa documentazione per di fornire l'accesso su internet.

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

      1. Verifica che l'URL non esegua troppe volte il reindirizzamento prima di pubblicare il documento di rilevamento del dominio. In questo caso, rivolgiti all'amministratore della tua 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 scoperta aperto deve essere in formato JSON.

      4. Cerca un campo jwks_uri nel JSON.

        1. Verifica che venga aperto 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 Un utente della federazione delle identità per la forza lavoro potrebbe riscontrare quando esegue 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 sulla risposta dell'IdP non può essere verificata utilizzando nessuno dei certificati X.509 forniti nel file XML dei metadati dell'IdP che hai 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 il pool di identità della forza lavoro del provider con il file XML dei metadati IdP più recente.

Per risolvere questo errore, svolgi i seguenti passaggi:

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

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

  3. Aggiorna il provider del pool di identità della forza lavoro con i metadati IdP scaricati XML.

  4. Riprova ad accedere.

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

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

Per risolvere questo errore, aggiorna Recipient URL / Redirect URL o il corrispondente campo 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 confermare 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 valore Recipient contenente l'URL di reindirizzamento viene visualizzato nella risposta SAML dell'IdP come mostrato di seguito:

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

La destinazione di SAMLResponse non corrisponde all'URL di callback RP

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

Per risolvere questo errore, aggiorna 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 ispezionare la risposta dell'IdP per verificare restituita dall'IdP e confermi che il campo Destination è risposta esatta.

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

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

Affermazione 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 il NameID che è l'oggetto di un'affermazione SAML, in genere l'utente che viene autenticato.

Segui la procedura descritta in Esaminare la risposta dell'IdP per visualizzare la risposta restituita dall'IdP e il valore NameID impostato.

Tutti i valori <AudienceRestriction> devono contenere l'ID entità RP SAML

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

Per risolvere questo errore, svolgi i seguenti passaggi:

  1. Consulta la documentazione dell'IdP per scoprire come configurare il segmento di pubblico nella sezione 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: Crea un provider di pool di identità per la forza lavoro nella sezione SAML per visualizzare il valore SP Entity ID da impostare.

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

Segui la procedura descritta in Esaminare la risposta dell'IdP per visualizzare la risposta restituita dall'IdP e i AudienceRestriction impostati.