Configura la federazione delle identità per i carichi di lavoro con altri provider di identità

Questa guida descrive come utilizzare la federazione delle identità per i carichi di lavoro con altri provider di identità (IdP).

I carichi di lavoro eseguiti al di fuori di Google Cloud potrebbero avere accesso a credenziali esistenti specifiche dell'ambiente, ad esempio:

• Un carico di lavoro potrebbe essere in grado di ottenere un'asserzione SAML o un token OpenID Connect (OIDC) da un provider di identità (IdP) eseguito nello stesso ambiente.

  Per eseguire l'autenticazione su Google Cloud, puoi consentire al carico di lavoro di scambiare le proprie credenziali specifiche per l'ambiente per credenziali Google Cloud a breve durata utilizzando la federazione delle identità per i carichi di lavoro.

• Un carico di lavoro potrebbe possedere altri tipi di credenziali, ad esempio un certificato client mTLS.

  Combinando la federazione delle identità per i carichi di lavoro con un broker di token personalizzato, puoi consentire ai carichi di lavoro di utilizzare altri tipi di credenziali per ottenere credenziali Google Cloud a breve durata.

L'utilizzo della federazione delle identità per i carichi di lavoro può aiutarti a ridurre il numero di credenziali che richiedono la rotazione.

Le sezioni seguenti descrivono come utilizzare la federazione delle identità per i carichi di lavoro con IdP che supportano i protocolli di autenticazione OpenID Connect (OIDC) o SAML.

Nota: se i carichi di lavoro vengono eseguiti su AWS o Azure, consulta Configurare la federazione delle identità per i carichi di lavoro con AWS o Azure. Se utilizzi Active Directory Federation Services (ADFS) come IdP, consulta Configurare la federazione delle identità per i carichi di lavoro con Active Directory.

Prepara l'IdP esterno

Dovrai eseguire questi passaggi solo una volta per ogni IdP.

Prima di iniziare, verifica che l'IdP esterno soddisfi i seguenti requisiti:

OIDC

• L'IdP supporta OpenID Connect 1.0.

• I metadati OIDC e gli endpoint JWKS dell'IdP sono protetti con SSL e TLS, gli URL degli endpoint iniziano con https:// e gli endpoint sono accessibili pubblicamente su internet.

  Google Cloud utilizza questi endpoint per scaricare il set di chiavi dell'IdP e lo utilizza per convalidare i token.

  Gli endpoint protetti con certificati autofirmati non sono supportati da Google Cloud.

SAML

• L'IdP supporta SAML 2.0.

• L'IdP fornisce un documento di metadati SP SAML che descrive la configurazione del fornitore di servizi SAML e contiene il certificato di firma dell'IdP.

  Google Cloud utilizza questo certificato per convalidare le asserzioni e le risposte SAML.

Se l'IdP soddisfa questi criteri:

OIDC

Configura l'IdP in modo che il carico di lavoro possa ottenere token ID che soddisfano i seguenti criteri:

• I token vengono firmati utilizzando l'algoritmo RS256 o ES256.

• I token contengono un'attestazione aud con il seguente valore:

  https://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID
  

  Sostituisci quanto segue:

  • PROJECT_NUMBER: il numero di progetto del progetto Google Cloud che utilizzi per creare il pool di identità per i carichi di lavoro.
  • POOL_ID: un ID a tua scelta che identifica il pool di identità per i carichi di lavoro. Devi utilizzare lo stesso ID durante la creazione del pool di identità per i carichi di lavoro in un secondo momento.
  • PROVIDER_ID: un ID a tua scelta che identifica il provider del pool di identità per i carichi di lavoro. Devi utilizzare lo stesso ID durante la creazione del provider del pool di identità per i carichi di lavoro in un secondo momento.

  In alternativa, puoi configurare il provider del pool di identità per i carichi di lavoro in modo che preveda un segmento di pubblico personalizzato.

• I token contengono un'attestazione exp futura e un'attestazione iat nel passato.

  Il valore di exp deve essere maggiore di quello di iat di massimo 24 ore.

In genere, è preferibile utilizzare i token ID quando si esegue uno scambio di token, in quanto questi token ID riflettono l'identità dell'utente. Se decidi di utilizzare invece i token di accesso, assicurati che i token di accesso soddisfino i seguenti requisiti aggiuntivi:

• I token di accesso hanno il formato Token Web JSON

• I token di accesso contengono un'attestazione ISSUER in modo che l'URL ISSUER/.well-known/openid-configuration rimandi all'endpoint dei metadati OIDC dell'IdP.

• Per caricare le chiavi JWK locali, consulta Gestire le chiavi JWK OIDC.

Nota: la federazione delle identità per i carichi di lavoro non supporta i token opachi o l'introspezione dei token.

SAML

Configura l'IdP in modo che le asserzioni SAML contengano:

• un elemento Issuer impostato sull'ID entità configurato nel provider del pool di identità del carico di lavoro. Il formato dell'emittente deve essere omesso o impostato su urn:oasis:names:tc:SAML:2.0:nameid-format:entity.
• un elemento Subject con:
  • un elemento NameID.
  • esattamente un elemento SubjectConfirmation con Method impostato su urn:oasis:names:tc:SAML:2.0:cm:bearer.
  • un elemento SubjectConfirmationData con NotOnOrAfter impostato su un timestamp futuro senza valore NotBefore.

• un elemento Conditions con:

  • NotBefore omesso o in passato.
  • NotOnOrAfter omesso o una data futura.

  • Un elemento Audience con il seguente formato:

    https://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID
    

    Sostituisci quanto segue:

    • PROJECT_NUMBER: il numero di progetto del progetto Google Cloud che utilizzi per creare il pool di identità per i carichi di lavoro.
    • POOL_ID: un ID a tua scelta che identifica il pool di identità per i carichi di lavoro. Devi utilizzare lo stesso ID durante la creazione del pool di identità per i carichi di lavoro in un secondo momento.
    • PROVIDER_ID: un ID a tua scelta che identifica il provider del pool di identità per i carichi di lavoro. Devi utilizzare lo stesso ID durante la creazione del provider del pool di identità per i carichi di lavoro in un secondo momento.

• almeno un elemento AuthnStatement.

• un elemento SessionNotOnOrAfter con un timestamp che ricorrerà in futuro. In alternativa, ometti l'elemento.

Per le asserzioni SAML racchiuse in una risposta SAML, la risposta SAML deve contenere:

• è esattamente un'affermazione che soddisfa i criteri di cui sopra.
• un attributo IssueInstant con un valore inferiore a un'ora prima.
• lo StatusCode urn:oasis:names:tc:SAML:2.0:status:Success.

Devi firmare l'asserzione SAML, la risposta o entrambe.

Configura la federazione delle identità per i carichi di lavoro

Dovrai eseguire questi passaggi solo una volta per ogni IdP. Puoi quindi utilizzare lo stesso pool di identità per i carichi di lavoro e lo stesso provider per più carichi di lavoro e su più progetti Google Cloud.

Per avviare la configurazione della federazione delle identità per i carichi di lavoro:

1. Nella pagina del selettore di progetti della console Google Cloud, seleziona o crea un progetto Google Cloud.

   Vai al selettore progetti

È preferibile utilizzare un progetto dedicato per gestire provider e pool di identità per i carichi di lavoro.

2. Assicurati che la fatturazione sia attivata per il tuo progetto Google Cloud.

Abilita le API IAM, Resource Manager, Service Account Credentials, and Security Token Service.

Abilita le API

Gestisci JWK OIDC (facoltativo)

Questa sezione mostra come gestire le JWK OIDC caricate automaticamente nei provider OIDC del pool di identità dei carichi di lavoro.

Crea un provider e carica i JWK OIDC

Per creare JWK OIDC, consulta Implementazioni JWT, JWS, JWE, JWK e JWA.

Per caricare un file JWK OIDC quando crei un provider di pool di identità per i carichi di lavoro, esegui il comando gcloud iam Workload-identity-poolsProvider create-oidc con --jwk-json-path="JWK_JSON_PATH". Sostituisci JWK_JSON_PATH con il percorso del file JSON JWKs.

Questa operazione crea le chiavi caricate con quelle nel file.

Aggiorna JWK OIDC

Per aggiornare i JWK OIDC, esegui il comando gcloud iam Workload-identity-pools Provider update-oidc con --jwk-json-path="JWK_JSON_PATH". Sostituisci JWK_JSON_PATH con il percorso del file JSON JWKs.

Questa operazione sostituisce qualsiasi chiave caricata esistente con quelle nel file. Non puoi ripristinare le chiavi sostituite.

Elimina tutti i JWK OIDC caricati

Per eliminare tutti i JWK OIDC caricati e tornare a utilizzare l'URI dell'emittente per recuperare le chiavi, esegui il comando gcloud iam workload-identity-poolsProvider update-oidc con --jwk-json-path="JWK_JSON_PATH". Sostituisci JWK_JSON_PATH con il percorso di un file vuoto. Utilizza il flag --issuer-uri per impostare l'URI dell'emittente.

Questa operazione elimina tutte le chiavi caricate esistenti insieme a quelle nel file. Non puoi ripristinare le chiavi eliminate.

Definisci una mappatura e una condizione degli attributi

I token OIDC o le asserzioni SAML emessi dal tuo IdP potrebbero contenere più attributi e devi decidere quale attributo utilizzare come identificatore del soggetto (google.subject) in Google Cloud.

Se vuoi, puoi mappare ulteriori attributi. Puoi quindi fare riferimento a questi attributi quando concedi l'accesso alle risorse.

OIDC

Le mappature degli attributi possono utilizzare le rivendicazioni incorporate nel token ID o nel token di accesso emesso dall'IdP esterno.

Devi mappare una di queste rivendicazioni a google.subject per identificare in modo univoco l'utente. Per proteggerti dalle minacce di spoofing, scegli una rivendicazione con un valore univoco che non possa essere modificato.

Molti IdP compilano l'attestazione sub con un ID univoco e immutabile. Per questi IdP, valuta la possibilità di mappare la dichiarazione sub a google.subject:

google.subject=assertion.sub

Evita di utilizzare una dichiarazione come email a questo scopo. Generalmente, gli indirizzi email possono essere riassegnati o modificati, in modo da non identificare un utente in modo univoco e permanente.

SAML

Le mappature degli attributi possono utilizzare gli elementi <Subject> e <Attribute> incorporati nell'asserzione emessa dall'IdP esterno. Gli attributi SAML possono essere denominati utilizzando le seguenti parole chiave:

• assertion.subject contiene NameID dell'utente autenticato trovato nell'elemento <Subject>.
• assertion.attributes['ATTRIBUTE_NAME'] contiene un elenco di valori per <Attribute> con lo stesso nome.

Devi mappare una di queste attestazioni a google.subject per identificare in modo univoco l'utente. Per proteggerti dalle minacce di spoofing, scegli una dichiarazione con un valore univoco che non possa essere modificato.

Molti IdP popolano NameId con un ID univoco e immutabile. Per questi IdP, valuta la possibilità di mappare l'attributo NameId su google.subject:

google.subject=assertion.subject

Evita di utilizzare un attributo come http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress per questo scopo. Generalmente, gli indirizzi email possono essere riassegnati o modificati, quindi non identificano un utente in modo univoco e permanente.

Facoltativamente, definisci una condizione dell'attributo. Le condizioni degli attributi sono espressioni CEL in grado di controllare gli attributi di asserzioni e gli attributi di destinazione. Se la condizione dell'attributo ha valore true per una determinata credenziale, la credenziale viene accettata. In caso contrario, la credenziale viene rifiutata.

OIDC

Puoi utilizzare una condizione degli attributi per limitare gli utenti che possono utilizzare la federazione delle identità per i carichi di lavoro per ottenere token Google Cloud a breve durata.

Ad esempio, la seguente condizione limita l'accesso ai token che contengono un'attestazione service_account personalizzata con un valore true:

assertion.service_account==true

SAML

Puoi utilizzare una condizione degli attributi per limitare gli utenti che possono utilizzare la federazione delle identità per i carichi di lavoro per ottenere token Google Cloud a breve durata.

Ad esempio, la seguente condizione limita l'accesso alle asserzioni che contengono un attributo https://example.com/SAML/Attributes/AllowGcpFederation personalizzato con un valore true:

assertion.attributes['https://example.com/SAML/Attributes/AllowGcpFederation'][0]=='true'

Crea il pool di identità per i carichi di lavoro e il provider

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per configurare la federazione delle identità per i carichi di lavoro, chiedi all'amministratore di concederti i seguenti ruoli IAM sul progetto:

• Amministratore pool di identità per carichi di lavoro (roles/iam.workloadIdentityPoolAdmin)
• Amministratore account di servizio (roles/iam.serviceAccountAdmin)

Per saperne di più sulla concessione dei ruoli, consulta Gestire l'accesso.

Potresti anche essere in grado di ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

In alternativa, il ruolo di base Proprietario IAM (roles/owner) include anche le autorizzazioni per configurare la federazione delle identità. Non devi concedere ruoli di base in un ambiente di produzione, ma puoi concederli in un ambiente di sviluppo o test.

Ora hai raccolto tutte le informazioni necessarie per creare un provider e un pool di identità per i carichi di lavoro:

Console

1. Nella console Google Cloud, vai alla pagina Nuovo provider e pool di carichi di lavoro.

   Vai a Nuovo provider e pool di carichi di lavoro

2. In Crea un pool di identità, inserisci quanto segue:

   • Nome: il nome del pool. Il nome viene utilizzato anche come ID pool. Non potrai modificare l'ID pool in un secondo momento.
   • Descrizione: testo che descrive lo scopo del pool.

3. Fai clic su Continua.

4. Configura le impostazioni del provider nel seguente modo:

   OIDC

   • In Seleziona un provider, scegli OpenID Connect (OIDC).
   • In Nome provider, inserisci un nome per il provider. Il nome viene utilizzato anche come ID provider. Non puoi modificare l'ID provider dopo aver creato il provider.
   • In Issuer URL (URL emittente), inserisci l'URL dell'emittente dell'IdP. L'URL deve iniziare con https://
   • (Facoltativo) In File JWK (JSON), scegli un file JWK da caricare. Se questo campo non viene compilato, Google Cloud tenta di recuperare un JWK dall'emittente.
   • Segmenti di pubblico consentiti: segmenti di pubblico previsti dei token ID.

   SAML

   • In Select a provider (Seleziona un provider), seleziona SAML ( SAML).
   • In Nome provider, inserisci un nome per il provider. Il nome viene utilizzato anche come ID provider. Non puoi modificare l'ID provider dopo aver creato il provider.
   • In File di metadati IDP (XML), carica il documento XML di metadati SAML fornito dal tuo provider di identità.

5. Fai clic su Continua.

6. In Configura gli attributi del provider, aggiungi le mappature degli attributi identificate in precedenza in questa guida.

7. In Condizioni degli attributi, inserisci la condizione dell'attributo identificata in precedenza in questa guida. Lascia vuoto il campo se non hai una condizione per l'attributo.

8. Per creare il provider e il pool di identità per i carichi di lavoro, fai clic su Salva.

gcloud

1. Per creare un nuovo pool di Workload Identity, esegui questo comando:

   gcloud iam workload-identity-pools create POOL_ID \
       --location="global" \
       --description="DESCRIPTION" \
       --display-name="DISPLAY_NAME"
   

   Sostituisci quanto segue:

   • POOL_ID: l'ID univoco del pool.
   • DISPLAY_NAME: il nome del pool.
   • DESCRIPTION: una descrizione del pool scelto. Questa descrizione viene visualizzata quando concedi l'accesso alle identità dei pool.

2. Per aggiungere un provider di pool di identità per i carichi di lavoro:

   OIDC

   Per aggiungere un provider di pool di identità per i carichi di lavoro OIDC, esegui questo comando:

   gcloud iam workload-identity-pools providers create-oidc PROVIDER_ID \
       --location="global" \
       --workload-identity-pool="POOL_ID" \
       --issuer-uri="ISSUER" \
       --allowed-audiences="AUDIENCE" \
       --attribute-mapping="MAPPINGS" \
       --attribute-condition="CONDITIONS"
       --jwk-json-path="JWK_JSON_PATH"
   

   Sostituisci quanto segue:

   • PROVIDER_ID: un ID provider univoco del pool di identità per i carichi di lavoro a tua scelta.
   • POOL_ID: l'ID pool di identità per i carichi di lavoro creato in precedenza.
   • ISSUER: l'URI dell'emittente come definito nei metadati OIDC.
   • AUDIENCE: il pubblico previsto di token ID che, per molti provider, corrisponde all'ID client.
   • MAPPINGS: un elenco separato da virgole di mappature degli attributi che hai creato in precedenza in questa guida.
   • CONDITIONS: una condizione dell'attributo facoltativa che hai creato in precedenza in questa guida. Rimuovi il parametro se non hai una condizione per l'attributo.
   • JWK_JSON_PATH: un percorso facoltativo di JWK OIDC caricati in locale. Se questo parametro non è specificato, Google Cloud utilizza il percorso /.well-known/openid-configuration dell'IdP per eseguire l'origine dei JWK contenenti le chiavi pubbliche.

   SAML

   Per aggiungere un provider di pool di identità per i carichi di lavoro SAML, esegui questo comando:

   gcloud iam workload-identity-pools providers create-saml PROVIDER_ID \
       --location="global" \
       --workload-identity-pool="POOL_ID" \
       --idp-metadata-path="IDP_METADATA_PATH" \
       --attribute-mapping="MAPPINGS" \
       --attribute-condition="CONDITIONS"
   

   Sostituisci quanto segue:

   • POOL_ID: l'ID del pool
   • IDP_METADATA_PATH: il percorso del file locale per il documento dei metadati dell'IdP SAML
   • MAPPINGS: un elenco separato da virgole di mappature degli attributi che hai creato in precedenza in questa guida.
   • CONDITIONS: facoltativo: la condizione dell'attributo che hai creato in precedenza in questa guida.

   Il prefisso gcp- è riservato e non può essere utilizzato in un ID pool o provider.

   (Facoltativo) Accetta le asserzioni SAML criptate dal tuo IdP

   Per consentire all'IdP SAML 2.0 di produrre asserzioni SAML criptate che possono essere accettate dalla federazione delle identità per i carichi di lavoro:

   • Nella federazione delle identità per i carichi di lavoro, segui questi passaggi:
   • Crea una coppia di chiavi asimmetriche per il provider del pool di identità per i carichi di lavoro.
   • Scarica un file di certificato contenente la chiave pubblica.
   • Configura l'IdP SAML in modo che utilizzi la chiave pubblica per criptare le asserzioni SAML che causa.
   • Nell'IdP, segui questi passaggi:
   • Consente di attivare la crittografia delle asserzioni, nota anche come crittografia dei token.
   • Carica la chiave pubblica che hai creato nella federazione delle identità per i carichi di lavoro.
   • Verifica che l'IdP generi asserzioni SAML criptate.

   Tieni presente che, anche se sono configurate le chiavi del provider di crittografia SAML, la federazione delle identità per i carichi di lavoro può comunque elaborare un'asserzione in testo non crittografato.

   Crea chiavi di crittografia delle asserzioni SAML della federazione delle identità per i carichi di lavoro

   Questa sezione illustra come creare una coppia di chiavi asimmetriche che consente alla federazione delle identità dei carichi di lavoro di accettare asserzioni SAML criptate.

   Google Cloud utilizza la chiave privata per decriptare le asserzioni SAML problematiche dall'IdP. Per creare una coppia di chiavi asimmetriche da utilizzare con la crittografia SAML, esegui questo comando. Per scoprire di più, vedi Algoritmi di crittografia SAML supportati.

   gcloud iam workload-identity-pools providers keys create KEY_ID \
       --workload-identity-pool WORKLOAD_POOL_ID \
       --provider PROVIDER_ID \
       --location global \
       --use encryption \
       --spec KEY_SPECIFICATION
   

   Sostituisci quanto segue:

   • KEY_ID: un nome chiave a tua scelta
   • WORKLOAD_POOL_ID: l'ID pool
   • PROVIDER_ID: l'ID provider
   • KEY_SPECIFICATION: la specifica della chiave, che può essere rsa-2048, rsa-3072 e rsa-4096.

   Dopo aver creato la coppia di chiavi, esegui questo comando per scaricare la chiave pubblica in un file di certificato. Solo la federazione delle identità per i carichi di lavoro ha accesso alla chiave privata.

   gcloud iam workload-identity-pools providers keys describe KEY_ID \
       --workload-identity-pool WORKLOAD_POOL_ID \
       --provider PROVIDER_ID \
       --location global \
       --format "value(keyData.key)" \
       > CERTIFICATE_PATH
   

   Sostituisci quanto segue:

   • KEY_ID: il nome della chiave
   • WORKLOAD_POOL_ID: l'ID pool
   • PROVIDER_ID: l'ID provider
   • CERTIFICATE_PATH: il percorso in cui scrivere il certificato, ad esempio saml-certificate.cer o saml-certificate.pem

   Configura il tuo IdP conforme a SAML 2.0 per emettere asserzioni SAML criptate

   Configura l'IdP SAML in modo che utilizzi il certificato pubblico scaricato nell'ultimo passaggio per criptare le asserzioni SAML emesse. Consulta il team dell'IdP per istruzioni specifiche.

   Dopo aver configurato l'IdP per criptare le asserzioni SAML, ti consigliamo di assicurarti che le asserzioni che genera siano effettivamente criptate. Anche se è configurata la crittografia delle asserzioni SAML, la federazione delle identità per i carichi di lavoro può comunque elaborare le asserzioni di testo non crittografato.

   Elimina le chiavi di crittografia della federazione delle identità per i carichi di lavoro

   Per eliminare le chiavi di crittografia SAML, esegui questo comando:

     gcloud iam workload-identity-pools providers keys delete KEY_ID \
         --workload-identity-pool WORKLOAD_POOL_ID \
         --provider PROVIDER_ID \
         --location global
   

   Sostituisci quanto segue:

   • KEY_ID: il nome della chiave
   • WORKLOAD_POOL_ID: l'ID pool
   • PROVIDER_ID: l'ID provider

   Algoritmi di crittografia SAML supportati

   La federazione delle identità per i carichi di lavoro supporta i seguenti algoritmi di trasporto chiave:

   • http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p
   • http://www.w3.org/2009/xmlenc11#rsa-oaep"
   • http://www.w3.org/2001/04/xmlenc#rsa-1_5"

   La federazione delle identità per i carichi di lavoro supporta i seguenti algoritmi di crittografia a blocchi:

   • http://www.w3.org/2001/04/xmlenc#aes128-cbc
   • http://www.w3.org/2001/04/xmlenc#aes192-cbc
   • http://www.w3.org/2001/04/xmlenc#aes256-cbc
   • http://www.w3.org/2009/xmlenc11#aes128-gcm
   • http://www.w3.org/2009/xmlenc11#aes256-gcm

Autentica un carico di lavoro

Devi eseguire questi passaggi una volta per ogni carico di lavoro.

Crea un account di servizio per il carico di lavoro esterno

1. Abilita le API IAM, Security Token Service, and Service Account Credentials.

   Abilita le API

2. Crea un account di servizio che rappresenti il carico di lavoro. È preferibile utilizzare un account di servizio dedicato per ogni carico di lavoro.

   L'account di servizio non deve necessariamente trovarsi nello stesso progetto del pool di identità dei carichi di lavoro.

3. Concedi all'account di servizio l'accesso alle risorse a cui vuoi che accedano le identità esterne.

Consenti al carico di lavoro esterno di impersonare l'account di servizio

Per consentire a identità esterne di impersonare un account di servizio, concedi loro il ruolo Utente Workload Identity (roles/iam.workloadIdentityUser) per l'account di servizio. Puoi concedere il ruolo a un'identità esterna specifica o a più identità esterne:

• Per un'identità esterna specifica, scrivi una condizione dell'attributo che controlli l'attributo google.subject.
• Per un gruppo di identità esterne, scrivi una condizione dell'attributo che controlli l'attributo google.groups o un attributo personalizzato attribute.NAME.

Nota: puoi verificare solo gli attributi che hai configurato nella mappatura degli attributi nella configurazione del provider del pool di identità per i carichi di lavoro.

Console

Per consentire alle identità esterne di impersonare un account di servizio utilizzando la console Google Cloud:

1. Nella console Google Cloud, vai alla pagina Pool di identità carichi di lavoro.

   Vai ai pool Workload Identity

2. Individua e seleziona il pool Workload Identity da aggiornare.

3. Per concedere l'accesso al pool di identità per i carichi di lavoro selezionato, fai clic su Concedi l'accesso.

4. Nell'elenco Account di servizio, seleziona l'account di servizio per le identità esterne da impersonare.

5. Per scegliere quali identità nel pool possono impersonare l'account di servizio, esegui una delle seguenti azioni:

   • Per consentire solo a identità specifiche del pool di identità per i carichi di lavoro di assumere l'identità dell'account di servizio, seleziona Solo le identità che corrispondono al filtro.

     Nell'elenco Nome attributo, seleziona l'attributo in base al quale applicare il filtro.

     Nel campo Valore attributo, inserisci il valore previsto dell'attributo; ad esempio, se utilizzi una mappatura degli attributi google.subject=assertion.sub, imposta Nome attributo su subject e Valore attributo sul valore dell'attestazione sub nei token emessi dal tuo provider di identità esterno.

6. Per salvare la configurazione, fai clic su Salva e poi su Ignora.

gcloud

Per consentire alle identità esterne di impersonare un account di servizio utilizzando gcloud CLI, segui questi passaggi:

1. Per ottenere il numero del tuo progetto attuale, esegui questo comando:

   gcloud projects describe $(gcloud config get-value core/project) --format=value\(projectNumber\)
   

2. Per concedere il ruolo Utente Workload Identity (roles/iam.workloadIdentityUser) alle identità esterne che soddisfano determinati criteri:

   Per soggetto

   gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_EMAIL \
       --role=roles/iam.workloadIdentityUser \
       --member="principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT"
   

   Per gruppo

   gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_EMAIL \
       --role=roles/iam.workloadIdentityUser \
       --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/group/GROUP"
   

   Per attributo

   gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_EMAIL \
       --role=roles/iam.workloadIdentityUser \
       --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE"
   

   Sostituisci quanto segue:

   • SERVICE_ACCOUNT_EMAIL: l'indirizzo email dell'account di servizio
   • PROJECT_NUMBER: il numero di progetto del progetto che contiene il pool di identità per i carichi di lavoro
   • POOL_ID: l'ID pool del pool di identità per i carichi di lavoro
   • SUBJECT: il valore previsto per l'attributo che hai mappato a google.subject
   • GROUP: il valore previsto per l'attributo che hai mappato a google.groups
   • ATTRIBUTE_NAME: il nome di un attributo personalizzato nella mappatura degli attributi
   Nota: devi utilizzare il numero di progetto nell'identificatore del membro. L'utilizzo dell'ID progetto non è supportato.

Crea una configurazione delle credenziali

Le librerie client di Cloud, gcloud CLI e Terraform possono ottenere automaticamente credenziali esterne e utilizzare queste credenziali per impersonare un account di servizio. Per consentire a librerie e strumenti di completare questa procedura, devi fornire un file di configurazione delle credenziali. Questo file definisce quanto segue:

• Da dove ottenere le credenziali esterne
• Provider di identità e pool di identità per i carichi di lavoro da utilizzare
• Quale account di servizio utilizzare

Le librerie client di Cloud ricevono le credenziali esterne da un file locale, un URL HTTP, eseguendo un eseguibile locale:

• Credenziali provenienti da file eseguibili: le librerie avviano un eseguibile ogni volta che hanno bisogno di una nuova credenziale. Se l'eseguibile riesce a ottenere una nuova credenziale esterna, deve scrivere in STDOUT un documento JSON simile al seguente:

  OIDC

  {
    "version": 1,
    "success": true,
    "token_type": "urn:ietf:params:oauth:token-type:id_token",
    "id_token": "HEADER.PAYLOAD.SIGNATURE",
    "expiration_time": 1620499962
  }
  

  Se l'eseguibile non riesce a ottenere una nuova credenziale, deve scrivere su STDOUT un documento JSON simile al seguente:

  {
    "version": 1,
    "success": false,
    "code": "401",
    "message": "Caller not authorized."
  }
  

  I documenti JSON utilizzano i seguenti campi:

  • version: la versione dell'output JSON. Attualmente è supportata solo la versione 1.

  • success: lo stato della risposta.

    Quando true, la risposta deve contenere i campi id_token e token_type. L'eseguibile deve essere chiuso con il codice di uscita 0.

    Quando false, la risposta deve contenere i campi code e message e uscire con un valore diverso da zero.

  • token_type: il tipo di token della credenziale esterna. I valori supportati sono

    • urn:ietf:params:oauth:token-type:id_token
    • urn:ietf:params:oauth:token-type:jwt

  • id_token: la credenziale esterna.

  • expiration_time: la data e l'ora di scadenza del token OIDC in secondi (tempo Unix epoch). Questo campo è obbligatorio solo quando è stato specificato un file di output nella configurazione delle credenziali.

  • code: la stringa del codice di errore.

  • message: il messaggio di errore.

  SAML

  {
    "version": 1,
    "success": true,
    "token_type": "urn:ietf:params:oauth:token-type:saml2",
    "saml_response": "...",
    "expiration_time": 1620499962
  }
  

  Se l'eseguibile non riesce a ottenere una nuova credenziale, deve scrivere su STDOUT un documento JSON simile al seguente:

  {
    "version": 1,
    "success": false,
    "code": "401",
    "message": "Caller not authorized."
  }
  

  I documenti JSON utilizzano i seguenti campi:

  • version: la versione dell'output JSON. Attualmente è supportata solo la versione 1.

  • success: lo stato della risposta.

    Quando true, la risposta deve contenere i campi id_token e token_type. L'eseguibile deve essere chiuso con il codice di uscita 0.

    Quando false, la risposta deve contenere i campi code e message e uscire con un valore diverso da zero.

  • token_type: il tipo di token della credenziale esterna. Deve essere urn:ietf:params:oauth:token-type:saml2.

  • saml_response: la risposta SAML o l'asserzione SAML con codifica Base64.

  • expiration_time: il tempo di scadenza dell'asserzione in secondi (tempo epoche Unix). Questo campo è obbligatorio solo quando è stato specificato un file di output nella configurazione delle credenziali.

  • code: la stringa del codice di errore.

  • message: il messaggio di errore.

  All'avvio dell'eseguibile, le librerie client impostano le seguenti variabili di ambiente:

  • GOOGLE_EXTERNAL_ACCOUNT_AUDIENCE: segmento di pubblico della configurazione delle credenziali. Sempre presente.
  • GOOGLE_EXTERNAL_ACCOUNT_TOKEN_TYPE: tipo di token oggetto previsto. Sempre presente.
  • GOOGLE_EXTERNAL_ACCOUNT_IMPERSONATED_EMAIL: email dell'account di servizio. Presente solo quando viene utilizzata la simulazione dell'identità degli account di servizio.
  • GOOGLE_EXTERNAL_ACCOUNT_OUTPUT_FILE: Posizione del file di output dalla configurazione delle credenziali. Presente solo se specificato nella configurazione delle credenziali.

  Per utilizzare le credenziali provenienti da eseguibili, devi impostare la variabile di ambiente GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES su 1.

• Credenziali basate su file: le librerie leggono le credenziali esterne da un file di testo normale o JSON locale. Ad esempio:

  JSON

  {
    "mytoken": "ey...
  }
  

  Testo

  ey...
  

  La credenziale esterna può essere:

  • un token OIDC
  • una risposta SAML
  • un'asserzione SAML con codifica Base64

  Devi aggiornare periodicamente il file in modo che contenga sempre una credenziale valida. Ad esempio, se il token OIDC o l'asserzione SAML sono validi per un'ora, è necessario aggiornare il file almeno una volta ogni ora.

• Credenziali basate su URL: le librerie eseguono una richiesta GET a un endpoint HTTP ogni volta che hanno bisogno di una nuova credenziale. L'endpoint deve restituire una risposta in testo normale o JSON equivalente al formato utilizzato dalle credenziali provenienti da file.

Nota: a differenza di una chiave dell'account di servizio, un file di configurazione delle credenziali non contiene una chiave privata e non deve essere necessariamente riservato. I dettagli del file di configurazione delle credenziali sono disponibili all'indirizzo https://google.aip.dev/auth/4117.

Per creare un file di configurazione delle credenziali:

Credenziali provenienti da eseguibili

gcloud iam workload-identity-pools create-cred-config \
    projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID \
    --service-account=SERVICE_ACCOUNT_EMAIL \
    --service-account-token-lifetime-seconds=SERVICE_ACCOUNT_TOKEN_LIFETIME \
    --output-file=FILEPATH.json \
    --executable-command=EXECUTABLE_COMMAND \
    --executable-timeout-millis=EXECUTABLE_TIMEOUT \
    --executable-output-file=EXECUTABLE_OUTPUT_FILE

Sostituisci quanto segue:

• PROJECT_NUMBER: il numero del progetto che contiene il pool di identità per i carichi di lavoro
• POOL_ID: l'ID del pool di identità per i carichi di lavoro
• PROVIDER_ID: l'ID del provider del pool di identità per i carichi di lavoro
• SERVICE_ACCOUNT_EMAIL: l'indirizzo email dell'account di servizio
• SERVICE_ACCOUNT_TOKEN_LIFETIME: durata del token di accesso all'account di servizio, in secondi; se non viene specificato, il valore predefinito è un'ora. Per specificare una durata superiore a un'ora, devi configurare il vincolo del criterio dell'organizzazione constraints/iam.allowServiceAccountCredentialLifetimeExtension.
• FILEPATH: il file in cui salvare la configurazione
• EXECUTABLE_COMMAND: il comando completo, inclusi gli argomenti, da eseguire per recuperare il token ID OIDC (ad es. --executable-command="/path/to/command --foo=bar")
• EXECUTABLE_TIMEOUT: la durata facoltativa di attesa in millisecondi per l'esecuzione dell'eseguibile (il valore predefinito è 30 secondi)
• EXECUTABLE_OUTPUT_FILE: questo percorso file rimanda alle credenziali di 3PI generate dall'eseguibile. È utile per memorizzare le credenziali nella cache. Specificando questo percorso, le librerie di autenticazione ne verificano l'esistenza prima di eseguire l'eseguibile.

Credenziali basate su file

gcloud iam workload-identity-pools create-cred-config \
    projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID \
    --service-account=SERVICE_ACCOUNT_EMAIL \
    --service-account-token-lifetime-seconds=SERVICE_ACCOUNT_TOKEN_LIFETIME \
    --output-file=FILEPATH.json \
    --credential-source-file=TOKEN_FILEPATH \
    --credential-source-type=SOURCE_TYPE \
    --credential-source-field-name=FIELD_NAME

Sostituisci quanto segue:

• PROJECT_NUMBER: numero del progetto che contiene il pool di identità per i carichi di lavoro
• POOL_ID: ID del pool di identità per i carichi di lavoro
• PROVIDER_ID: ID del provider del pool di identità per i carichi di lavoro
• SERVICE_ACCOUNT_EMAIL: indirizzo email dell'account di servizio
• SERVICE_ACCOUNT_TOKEN_LIFETIME: durata del token di accesso all'account di servizio, in secondi; se non viene specificato, il valore predefinito è un'ora. Per specificare una durata superiore a un'ora, devi configurare il vincolo del criterio dell'organizzazione constraints/iam.allowServiceAccountCredentialLifetimeExtension.
• FILEPATH: file in cui salvare la configurazione
• TOKEN_FILEPATH: percorso in cui sono archiviati i token ID OIDC
• SOURCE_TYPE: formato del file token ID OIDC, impostato su text (valore predefinito) o json
• FIELD_NAME: campo nel file di testo che contiene il token (se SOURCE_TYPE è json)

Credenziali basate su URL

gcloud iam workload-identity-pools create-cred-config \
    projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID \
    --service-account=SERVICE_ACCOUNT_EMAIL \
    --service-account-token-lifetime-seconds=SERVICE_ACCOUNT_TOKEN_LIFETIME \
    --output-file=FILEPATH.json \
    --credential-source-url="TOKEN_URL" \
    --credential-source-headers="KEY_1=VALUE_1,KEY_2=VALUE_2" \
    --credential-source-type=SOURCE_TYPE \
    --credential-source-field-name=FIELD_NAME

Sostituisci quanto segue:

• PROJECT_NUMBER: numero del progetto che contiene il pool di identità per i carichi di lavoro
• POOL_ID: ID del pool di identità per i carichi di lavoro
• PROVIDER_ID: ID del provider del pool di identità per i carichi di lavoro
• SERVICE_ACCOUNT_EMAIL: indirizzo email dell'account di servizio
• SERVICE_ACCOUNT_TOKEN_LIFETIME: durata del token di accesso all'account di servizio, in secondi; se non viene specificato, il valore predefinito è un'ora. Per specificare una durata superiore a un'ora, devi configurare il vincolo del criterio dell'organizzazione constraints/iam.allowServiceAccountCredentialLifetimeExtension.
• FILEPATH: file in cui salvare la configurazione
• TOKEN_URL: URL da cui recuperare il token ID OIDC
• KEY_n, VALUE_n: intestazioni personalizzate da includere nella richiesta HTTP a TOKEN_URL
• SOURCE_TYPE: formato del file token ID OIDC, impostato su text (valore predefinito) o json
• FIELD_NAME: campo nel file di testo che contiene il token (se SOURCE_TYPE è json)

Utilizzo della configurazione delle credenziali per accedere a Google Cloud

Per consentire a strumenti e librerie client di utilizzare la configurazione delle credenziali, segui questi passaggi:

1. Inizializza una variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS e puntala al file di configurazione delle credenziali:

   Bash

     export GOOGLE_APPLICATION_CREDENTIALS=`pwd`/FILEPATH.json
     

   dove FILEPATH è il percorso file relativo al file di configurazione delle credenziali.

   PowerShell

     $env:GOOGLE_APPLICATION_CREDENTIALS = Resolve-Path 'FILEPATH.json'
     

   dove FILEPATH è il percorso file relativo al file di configurazione delle credenziali.

2. Utilizza una libreria client o uno strumento che supporti la federazione delle identità per i carichi di lavoro e che possa trovare le credenziali automaticamente:

   C++

   Le librerie client di Google Cloud per C++ supportano la federazione delle identità per i carichi di lavoro a partire dalla versione v2.6.0. Per utilizzare la federazione delle identità per i carichi di lavoro, devi creare le librerie client con versione 1.36.0 o successiva di gRPC.

   Go

   Le librerie client per Go supportano la federazione delle identità se utilizzano la versione v0.0.0-20210218202405-ba52d332ba99 o successiva del modulo golang.org/x/oauth2.

   Per verificare quale versione di questo modulo utilizza la tua libreria client, esegui questi comandi:

   cd $GOPATH/src/cloud.google.com/go
   go list -m golang.org/x/oauth2
   

   Java

   Le librerie client per Java supportano la federazione delle identità se utilizzano la versione 0.24.0 o successive dell'artefatto com.google.auth:google-auth-library-oauth2-http.

   Per verificare quale versione di questo artefatto utilizza la tua libreria client, esegui il seguente comando Maven nella directory dell'applicazione:

   mvn dependency:list -DincludeArtifactIds=google-auth-library-oauth2-http
   

   Node.js

   Le librerie client per Node.js supportano la federazione delle identità per i carichi di lavoro se utilizzano la versione 7.0.2 o successiva del pacchetto google-auth-library.

   Per verificare quale versione di questo pacchetto viene utilizzata dalla tua libreria client, esegui questo comando nella directory dell'applicazione:

   npm list google-auth-library
   

   Quando crei un oggetto GoogleAuth, puoi specificare un ID progetto o consentire a GoogleAuth di trovare automaticamente l'ID progetto. Per trovare automaticamente l'ID progetto, l'account di servizio nel file di configurazione deve avere il ruolo Browser (roles/browser) o un ruolo con autorizzazioni equivalenti nel progetto. Per maggiori dettagli, consulta il documento README per il pacchetto google-auth-library.

   Python

   Le librerie client per Python supportano la federazione delle identità se utilizzano la versione 1.27.0 o successiva del pacchetto google-auth.

   Per verificare quale versione di questo pacchetto viene utilizzata dalla tua libreria client, esegui questo comando nell'ambiente in cui è installato il pacchetto:

   pip show google-auth
   

   Per specificare un ID progetto per il client di autenticazione, puoi impostare la variabile di ambiente GOOGLE_CLOUD_PROJECT o consentire al client di trovare automaticamente l'ID progetto. Per trovare automaticamente l'ID progetto, l'account di servizio nel file di configurazione deve avere il ruolo Browser (roles/browser) o un ruolo con autorizzazioni equivalenti nel progetto. Per i dettagli, consulta la guida dell'utente per il pacchetto google-auth.

   gcloud

   Per eseguire l'autenticazione con la federazione delle identità per i carichi di lavoro, utilizza il comando gcloud auth login:

   gcloud auth login --cred-file=FILEPATH.json
   

   Sostituisci FILEPATH con il percorso del file di configurazione delle credenziali.

   Il supporto per la federazione delle identità per i carichi di lavoro in gcloud CLI è disponibile nella versione 363.0.0 e successive di gcloud CLI.

   Terraform

   Il provider Google Cloud supporta la federazione delle identità per i carichi di lavoro se utilizzi la versione 3.61.0 o successive:

   terraform {
     required_providers {
       google = {
         source  = "hashicorp/google"
         version = "~> 3.61.0"
       }
     }
   }
   

   gsutil

   Per eseguire l'autenticazione con la federazione delle identità per i carichi di lavoro, utilizza uno dei seguenti metodi:

   Quando utilizzi gsutil in combinazione con gcloud, accedi normalmente:

   gcloud auth login --cred-file=FILEPATH.json
   

   Quando utilizzi gsutil come applicazione a riga di comando autonoma, modifica il file .boto in modo da includere la seguente sezione:

   [Credentials]
   gs_external_account_file = FILEPATH
   

   In entrambi i casi, sostituisci FILEPATH con il percorso del file di configurazione delle credenziali.

   Il supporto per la federazione delle identità per i carichi di lavoro in gsutil è disponibile nella versione 379.0.0 e nelle versioni successive di gcloud CLI.

   bq

   Per eseguire l'autenticazione con la federazione delle identità per i carichi di lavoro, utilizza il comando gcloud auth login come segue:

   gcloud auth login --cred-file=FILEPATH.json
   

   Sostituisci FILEPATH con il percorso del file di configurazione delle credenziali.

   Il supporto per la federazione delle identità per i carichi di lavoro in bq è disponibile nella versione 390.0.0 e successive di gcloud CLI.

Passaggi successivi

• Scopri di più sulla federazione delle identità per i carichi di lavoro.
• Scopri le best practice per l'utilizzo della federazione delle identità per i carichi di lavoro.
• Scopri come gestire pool di identità per i carichi di lavoro e provider.