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

Controlla la risposta dell'IdP

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

Accesso basato su browser

Per ispezionare la risposta restituita dal tuo IdP, genera un 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'identità provider SAML:

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

OIDC

Per controllare la risposta dell'identità provider OIDC, svolgi i seguenti 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 percorso /signin-callback.
  2. Decodificalo utilizzando uno strumento di debug JWT a tua scelta.

Interfaccia a riga di comando gcloud

Per ispezionare la risposta dell'IDP quando utilizzi l'interfaccia alla 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, poi svolgi i passaggi che seguono:

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 a 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 visualizzare esempi di log, vedi Esempi di log di controllo.

Errori di gestione del pool di forza lavoro e del provider

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_ARGUMENT: manca la configurazione del 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 fornitore 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 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 le risorse del pool di forza lavoro. Contatta il rappresentante dell'account Google Cloud 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à 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 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 dall'identity provider (IdP) non contiene gcp-users.

Per risolvere questo errore, svolgi i seguenti passaggi:

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

  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 dell'IDP.

L'attributo mappato deve essere di tipo STRING

Questo errore si verifica per un provider di pool di identità forza lavoro SAML quando l'attributo specificato nel messaggio di errore dovrebbe essere una STRINGA con un solo valore, 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, svolgi i seguenti passaggi:

  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 chiamato userRole è mappato all'attributo role e l'attributo role compare 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 un attributo alternativo, stabile e con valore di stringa. Aggiorna quindi la mappatura degli attributi per utilizzarla facendo riferimento al primo elemento. Per l'esempio precedente, se myRole è stato identificato come attributo alternativo dell'identità provider a valore singolo, la mappatura degli attributi sarà:

      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 dall'elenco un identificatore stabile con un solo valore, consulta la definizione della lingua e aggiorna di conseguenza la mappatura degli attributi.

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 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 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 errato, accedi alla Console di amministrazione della tua IdP e controlla 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 Inform your users how to sign in (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 del 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, svolgi i seguenti passaggi:

  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 scoperta in una finestra di navigazione in incognito.

    1. Se l'URL non si apre o il browser mostra un errore 404, consulta la documentazione del tuo provider di identità per identificare l'URI 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 eseguire il provisioning per l'accesso tramite internet.

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

      1. Prima di pubblicare il documento di scoperta, controlla che l'URL non reindirizzi troppe volte. 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 errori specifici SAML che un utente della federazione delle identità della 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 nessuno dei certificati X.509 forniti nel file XML dei metadati dell'IdP che hai configurato nel tuo 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à del personale con il file XML dei metadati dell'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 il campo X509Certificate. 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 dall'IdP. I certificati devono corrispondere.

  2. Accedi alla Console di amministrazione dell'IdP e scarica i metadati XML più recenti.

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

  4. Riprova ad accedere.

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

Questo errore si verifica per un provider del 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 Recipient URL / Redirect URL o il corrispondente campo nella configurazione dell'IdP in modo da utilizzare l'URL di reindirizzamento descritto nella sezione 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à della forza lavoro locations/global/workforcePools/example-pool/providers/example-provider, 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 del 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 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 di pool di identità per la forza lavorolocations/global/workforcePools/example-pool/providers/example-provider, ilDestination 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 <AudienceRestriction> devono contenere l'ID entità RP 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 dell'entità del provider del pool di identità della forza lavoro.

Per risolvere questo errore, svolgi i seguenti passaggi:

  1. Consulta la documentazione dell'IdP su come configurare il segmento di pubblico nei tag AudienceRestriction inviati 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 su come creare un provider del pool di identità della forza lavoro per conoscere 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.