Configurare 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 workload con altri provider di identità (IdP).

Per autenticarti su Google Cloud, puoi consentire al workload di scambiare le proprie credenziali specifiche per l'ambiente con credenziali Google Clouddi breve durata utilizzando la federazione delle identità per i workload.

I workload eseguiti al di fuori di Google Cloud potrebbero avere accesso a credenziali esistenti specifiche per l'ambiente, ad esempio:

  • Un workload potrebbe essere in grado di ottenere un token di asserzione OpenID Connect (OIDC) da un IdP.

  • Un workload potrebbe essere in grado di ottenere un token di asserzione SAML da un provider di identità (IdP).

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

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

Prepara l'IdP esterno

Devi eseguire questi passaggi 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.

  • L'IdP ha un URI dell'emittente.

  • Google Cloud può accedere a un set di chiavi web JSON (JWKS) che contiene chiavi web JSON (JWK). I JWK vengono utilizzati per convalidare i token di asserzione OIDC. Puoi fornire l'accesso al JWKS tramite uno dei seguenti metodi:

    • Google Cloud scarica i metadati OIDC dall'IdP tramite un URL di rilevamento accessibile da internet, noto e disponibile pubblicamente. All'interno dei metadati, l'URL JWKS deve essere protetto con SSL e TLS. L'URL JWKS deve iniziare con https://. Google Cloud non supporta gli URL JWKS protetti con certificati autofirmati.

      Per impostazione predefinita, Google Cloud aggiunge /.well-known/openid-configuration all'URI dell'emittente per individuare l'URL Discovery. Se l'IdP ospita i metadati di rilevamento in un endpoint personalizzato, puoi specificare un URI di rilevamento personalizzato (--discovery-uri) (anteprima).

      L'URI di discovery personalizzato deve soddisfare i seguenti requisiti:

      • L'URI deve iniziare con https://.
      • L'URI non può superare i 2000 caratteri.
      • Schema, host e porta devono corrispondere all'URI dell'emittente.
      • Il percorso URI deve contenere /.well-known/<suffix> (dove <suffix> non è vuoto, ad esempio openid-configuration) e deve essere conforme a una delle seguenti topologie di URL dell'emittente:
      • Il segmento di percorso well-known viene inserito prima del percorso dell'emittente (ad esempio, https://example.com/.well-known/openid-configuration/tenant1 per l'emittente https://example.com/tenant1).
      • Il segmento del percorso noto viene aggiunto al percorso dell'emittente (ad esempio, https://example.com/tenant1/.well-known/openid-configuration per l'emittente https://example.com/tenant1).

      Google Cloud utilizza questi URL degli endpoint per scaricare le chiavi web JSON (JWK) dell'IdP e utilizza queste chiavi per convalidare i token. Google Cloud non limita il numero di chiavi che può scaricare.

    • Puoi caricare un file JWKS OIDC direttamente su Google Cloud quando crei o aggiorni il provider del pool di identità dei workload OIDC. Per farlo, utilizza --jwk-json-path per fornire un percorso al file JWKS. Puoi utilizzare questo metodo quando l'URL dell'endpoint dei metadati OIDC dell'IdP non è accessibile pubblicamente. È possibile caricare un massimo di 8 chiavi su Google Cloud. Come best practice, ti consigliamo di ruotare regolarmente le chiavi JWKS aggiornando il file JWKS.

  • Se esegui la federazione dei workload da AWS utilizzando la federazione delle identità in uscita di AWS, AWS funge da IdP OIDC. Per preparare l'ambiente AWS, segui questi passaggi:

    1. Attiva la federazione delle identità in uscita nelle impostazioni dell'account AWS per generare l'URL dell'emittente OIDC univoco.

    2. Assicurati che i tuoi workload AWS (come i profili delle istanze EC2 o i ruoli delle attività ECS) dispongano della policy AWS IAM richiesta che concede l'autorizzazione per ottenere i token JWT (JSON Web Token).

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.

  • Il certificato di firma dell'IdP deve contenere una chiave ECDSA o RSA all'interno di un certificato X.509 v3.

  • Gli algoritmi di firma consigliati includono:

  • Il certificato di firma deve soddisfare i seguenti requisiti di validità:

    • notBefore: un timestamp che non sia successivo a 7 giorni nel futuro
    • notAfter: un timestamp che non superi i 25 anni nel futuro

Puoi configurare un provider di pool di identità dei workload SAML con un massimo di tre certificati di firma SAML alla volta. Questa limitazione non si applica ad altri tipi di provider di pool di identità del workload, come OIDC e X.509. Se esistono più certificati, Google Cloud li esamina e tenta di utilizzare ogni certificato non scaduto per soddisfare una richiesta di scambio di token.

Come best practice di sicurezza, ti consigliamo vivamente di non riutilizzare la stessa coppia di chiavi con altri servizi.

Se il tuo IdP soddisfa questi criteri, segui questi passaggi:

OIDC

Configura l'IdP in modo che il workload 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/WORKLOAD_PROVIDER_ID

    Sostituisci quanto segue:

    • PROJECT_NUMBER: il numero di progetto del progetto Google Cloud che utilizzi per creare un pool di identità del workload.
    • POOL_ID: un ID di tua scelta che identifica il pool di identità del workload. Devi utilizzare lo stesso ID quando crei il pool di identità del workload in un secondo momento.
    • WORKLOAD_PROVIDER_ID: un ID di tua scelta che identifica il provider del pool di identità del workload. Devi utilizzare lo stesso ID quando crei il provider di pool di identità del workload in un secondo momento.

    In alternativa, puoi configurare il provider del pool di identità del workload in modo che si aspetti un segmento di pubblico personalizzato.

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

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

  • Token associati ai certificati (anteprima): facoltativamente, i token possono includere un claim cnf (conferma) contenente un fingerprint del certificato SHA-256 (x5t#S256):

    "cnf": {
  "x5t#S256": "BASE64URL_SHA256_CERT_FINGERPRINT"
}

    Il valore di x5t#S256 deve essere l'hash SHA-256 con codifica base64url della codifica DER del certificato X.509 del client. Quando un token contenente questa attestazione viene presentato alla federazione delle identità per i workload tramite una connessione mutual TLS (mTLS) (sts.mtls.googleapis.com), Security Token Service convalida che l'impronta corrisponda al certificato client presentato durante l'handshake TLS ed emette un token di accesso di breve durata associato in modo crittografico al certificato.

    Per proteggere le risorse dal furto di token e dagli attacchi di replay, applica i token associati ai certificati configurando le policy di accesso sensibile al contesto.

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

  • I token di accesso sono in formato token web JSON.

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

  • Per caricare le chiavi JWK locali, consulta Gestisci i JWK OIDC.

SAML

Configura l'IdP in modo che le asserzioni SAML contengano elementi che soddisfano i seguenti criteri:

  • un elemento Issuer impostato sull'ID entità configurato nel provider del pool di identità del workload. 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 che si verifica in futuro e nessun valore NotBefore.

  • Un elemento Conditions con:

    • NotBefore omesso o nel passato.
    • NotOnOrAfter omesso o nel futuro.

    • Un Audience formattato come segue:

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

      Sostituisci quanto segue:

      • PROJECT_NUMBER: il numero di progetto del progetto Google Cloud che utilizzi per creare il pool di identità del workload.
      • POOL_ID: un ID di tua scelta che identifica il pool di identità del workload. Devi utilizzare lo stesso ID quando crei il pool di identità del workload in un secondo momento.
      • WORKLOAD_PROVIDER_ID: un ID di tua scelta che identifica il provider di pool di identità del workload. Devi utilizzare lo stesso ID quando crei il provider del pool di identità del workload in un secondo momento.

  • almeno un elemento AuthnStatement.

  • un elemento SessionNotOnOrAfter con un timestamp che si verifica nel futuro. In alternativa, ometti l'elemento.

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

  • esattamente un'asserzione che soddisfi i criteri di asserzione SAML descritti in precedenza in questa sezione.
  • un attributo IssueInstant con un valore inferiore a 1 ora nel passato.
  • StatusCode urn:oasis:names:tc:SAML:2.0:status:Success.

L'asserzione SAML, la risposta o entrambe devono essere firmate.

Configura la federazione delle identità per i workload

Devi eseguire questi passaggi una sola volta per ogni IdP. Puoi quindi utilizzare lo stesso pool di identità del workload e lo stesso provider per più workload e in più progetti Google Cloud .

Per iniziare a configurare la federazione delle identità per i workload, segui questi passaggi:

  1. Nella console Google Cloud , nella pagina di selezione del progetto, seleziona o crea un progetto Google Cloud .

    Ruoli richiesti per selezionare o creare un progetto

    • Seleziona un progetto: la selezione di un progetto non richiede un ruolo IAM specifico. Puoi selezionare qualsiasi progetto per cui ti è stato concesso un ruolo.
    • Crea un progetto: per creare un progetto, devi disporre del ruolo Autore progetto (roles/resourcemanager.projectCreator), che contiene l'autorizzazione resourcemanager.projects.create. Scopri come concedere i ruoli.

    Vai al selettore di progetti

    2. È consigliabile utilizzare un progetto dedicato per gestire i pool e i provider di identità del workload.

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

    3. Abilita le API IAM, Resource Manager, Service Account Credentials e Security Token Service, se non sono già abilitate.

    Ruoli richiesti per abilitare le API

    Per abilitare le API, devi disporre dell'autorizzazione serviceusage.services.enable. Se hai creato il progetto, probabilmente hai già questa autorizzazione tramite il ruolo Proprietario (roles/owner). In caso contrario, puoi ottenere questa autorizzazione tramite il ruolo Amministratore Service Usage (roles/serviceusage.serviceUsageAdmin). Scopri come concedere i ruoli.

    Abilita le API

(Facoltativo) Gestisci i JWK OIDC caricati autonomamente

Questa sezione mostra come gestire i JWK OIDC caricati autonomamente nei provider OIDC dei pool di identità del workload.

Crea un provider e carica i JWK OIDC

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

Per caricare un file JWK OIDC quando crei un provider di pool di identità del workload, esegui il comando gcloud iam workload-identity-pools providers create-oidc con --jwk-json-path="JWK_JSON_PATH". Sostituisci JWK_JSON_PATH con il percorso del file JSON JWK.

Questa operazione crea chiavi caricate con quelle nel file.

Aggiorna i JWK OIDC

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

Questa operazione sostituisce le chiavi caricate esistenti con quelle presenti 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-pools providers 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 e le sostituisce con quelle presenti 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.

Facoltativamente, puoi mappare altri 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 attestazioni a google.subject per identificare in modo univoco l'utente. Per proteggerti dalle minacce di spoofing, scegli un'attestazione con un valore univoco che non può essere modificato.

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

google.subject=assertion.sub

Evita di utilizzare un'affermazione come email a questo scopo. In genere, gli indirizzi email possono essere riassegnati o modificati, pertanto non identificano in modo univoco e permanente un utente.

Mappa gli attributi dell'attore con la delega dell'identità (anteprima): quando utilizzi la delega dell'identità, Security Token Service combina le rivendicazioni del soggetto e dell'attore, esponendo le rivendicazioni dell'attore nell'oggetto della rivendicazione act. Puoi fare riferimento alle rivendicazioni dell'attore nelle mappature degli attributi utilizzando assertion.act.<claim_name>.

Quando esegui uno scambio di token delegato, vengono valutate e applicate solo le mappature degli attributi e le condizioni degli attributi del provider soggetto. Eventuali mappature o condizioni degli attributi configurate nel provider attore vengono ignorate.

Ad esempio, puoi mappare l'identificatore del soggetto e l'URI dell'emittente dell'attore ad attributi Google personalizzati:

attribute.actor_subject=assertion.act.sub,attribute.actor_issuer=assertion.act.iss

Se viene utilizzata la delega multi-hop, gli attori upstream sono nidificati all'interno di assertion.act.act. Tuttavia, l'ordine delle attestazioni nidificate non è garantito.

SAML

Le mappature degli attributi possono utilizzare gli elementi <Subject> e <Attribute> incorporati nell'asserzione emessa dall'IdP esterno. È possibile fare riferimento agli attributi SAML utilizzando le seguenti parole chiave:

  • assertion.subject contiene l'elemento 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 un'attestazione con un valore univoco che non può essere modificato.

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

google.subject=assertion.subject

Evita di utilizzare un attributo come http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress a questo scopo. In genere, 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 che possono controllare gli attributi di asserzione e gli attributi di destinazione. Se la condizione dell'attributo restituisce true per una determinata credenziale, la credenziale viene accettata. In caso contrario, la credenziale viene rifiutata.

OIDC

Puoi utilizzare una condizione dell'attributo per limitare gli utenti che possono utilizzare la federazione delle identità per i workload per ottenere token Google Clouddi 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

Condizioni di delega dell'identità (token attore) (anteprima): quando utilizzi la delega dell'identità, puoi utilizzare le condizioni degli attributi CEL per limitare gli attori autorizzati a eseguire operazioni per conto dei soggetti o applicare rivendicazioni specifiche al token attore.

Ad esempio, la seguente condizione richiede che sia presente un token attore e che l'attore provenga da un emittente previsto:

has(assertion.act) && assertion.act.iss == 'https://actor-idp.example.com'

Per limitare l'accesso a un identificatore del soggetto dell'attore specifico:

assertion.act.sub == 'authorized-agent-worker'

SAML

Puoi utilizzare una condizione dell'attributo per limitare gli utenti che possono utilizzare la federazione delle identità per i workload per ottenere token Google Clouddi 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à del workload e il provider

Ruoli obbligatori

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

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

In alternativa, anche il ruolo di base IAM Owner (roles/owner) include 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 di test.

Ora hai raccolto tutte le informazioni necessarie per creare un pool di identità del workload e un provider:

Console

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

    Vai a Nuovo provider e pool di workload

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

    • Nome: il nome del pool. Il nome viene utilizzato anche come ID del 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 come segue:

    OIDC

    • In Seleziona un provider, seleziona 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 averlo creato.
    • In URL emittente, inserisci l'URL emittente del tuo IdP. L'URL deve iniziare con https://
    • (Facoltativo) In File JWK (JSON), scegli un file JWK da caricare. Se questo campo non viene fornito, Google Cloud tenta di recuperare un JWK dall'emittente.
    • Segmenti di pubblico consentiti: pubblico previsto dei token ID.

    SAML

    • In Seleziona un provider, seleziona 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 averlo creato.
    • In IDP Metadata file (XML) (File di metadati IDP (XML)), carica il documento XML dei metadati SAML fornito dal tuo IdP.

  5. Fai clic su Continua.

  6. In Configura attributi del provider, aggiungi le mappature degli attributi che hai identificato in precedenza in questa guida.

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

  8. Per creare il pool di identità del workload e il provider, fai clic su Salva.

gcloud

  1. Per creare un nuovo pool di identità del workload, 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 che scegli. Questa descrizione viene visualizzata quando concedi l'accesso alle identità del pool.

  2. Per aggiungere un provider di pool di identità del workload, segui questi passaggi:

    OIDC

    Per aggiungere un provider di pool di identità del workload OIDC, esegui questo comando:

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

    Sostituisci quanto segue:

    • WORKLOAD_PROVIDER_ID: un ID provider del pool di identità del workload univoco di tua scelta.
    • POOL_ID: l'ID del pool di identità del workload che hai creato in precedenza.
    • ISSUER: un URI emittente come definito nei metadati OIDC.
    • DISCOVERY_URI Anteprima: un URL Discovery personalizzato facoltativo per recuperare i metadati OIDC se il tuo IdP non ospita l'endpoint di discovery OIDC noto in https://<issuer_url>/.well-known/openid-configuration. Lo schema, l'host e la porta devono corrispondere a ISSUER e il percorso deve essere conforme alla topologia dell'URL dell'emittente (contenente /.well-known/<suffix>).
    • AUDIENCE: il pubblico previsto dei token ID, che per molti provider corrisponde all'ID client.
    • MAPPINGS: un elenco separato da virgole delle 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 dell'attributo.
    • JWK_JSON_PATH: Un percorso opzionale a un JWK OIDC caricato localmente. Se questo parametro non viene fornito, Google Cloud utilizza l'URL Discovery (DISCOVERY_URI o il percorso /.well-known/openid-configuration del tuo IdP) per recuperare i JWK contenenti le chiavi pubbliche.
    • ACTOR_PROVIDERS Anteprima: un elenco facoltativo separato da virgole dei nomi completi delle risorse dei provider di pool di identità del workload nello stesso pool autorizzati a emettere token attore per questo provider (ad esempio projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/ACTOR_PROVIDER_ID). L'ID container del progetto nel nome della risorsa deve corrispondere al formato utilizzato per il provider del soggetto (entrambi utilizzano il numero di progetto numerico o entrambi utilizzano l'ID progetto). Puoi specificare al massimo tre provider di attori. Per saperne di più, consulta Configura la delega dell'identità e i token degli attori.

    SAML

    Per aggiungere un provider di pool di identità del workload SAML, esegui questo comando:

    gcloud iam workload-identity-pools providers create-saml WORKLOAD_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 locale del 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 di identità della forza lavoro o in un ID provider di pool di identità della forza lavoro.

    (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 workload, segui questi passaggi:

    • Nella federazione delle identità per i workload, segui questi passaggi:
      • Crea una coppia di chiavi asimmetriche per il provider di pool di identità del workload.
      • Scarica un file di certificato che contiene la chiave pubblica.
      • Configura l'IdP SAML in modo che utilizzi la chiave pubblica per criptare le asserzioni SAML che emette.
    • Nel tuo IdP, segui questi passaggi:
      • Attiva la crittografia delle asserzioni, nota anche come crittografia dei token.
      • Carica la chiave pubblica che hai creato nella federazione delle identità per i workload.
      • Verifica che l'IdP produca asserzioni SAML criptate.
    Tieni presente che, anche se sono configurate le chiavi del provider di crittografia SAML, la federazione delle identità per i workload può comunque elaborare un'asserzione in testo non crittografato.

    Crea chiavi di crittografia delle asserzioni SAML per la federazione delle identità per i workload

    Questa sezione ti guida nella creazione di una coppia di chiavi asimmetriche che consente alla federazione delle identità per i workload di accettare asserzioni SAML criptate.

    Google Cloud utilizza la chiave privata per decriptare le asserzioni SAML emesse dal tuo IdP. Per creare una coppia di chiavi asimmetriche da utilizzare con la crittografia SAML, esegui il comando seguente. Per saperne di più, consulta Algoritmi di crittografia SAML supportati. 

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

    Sostituisci quanto segue:

    • KEY_ID: un nome della chiave scelto da te
    • WORKLOAD_POOL_ID: l'ID del pool
    • WORKLOAD_PROVIDER_ID: l'ID provider del pool di identità della forza lavoro
    • KEY_SPECIFICATION: la specifica della chiave, che può essere rsa-2048, rsa-3072 e rsa-4096.

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

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

    Sostituisci quanto segue:

    • KEY_ID: il nome della chiave
    • WORKLOAD_POOL_ID: l'ID del pool
    • WORKLOAD_PROVIDER_ID: l'ID provider del pool di identità della forza lavoro
    • CERTIFICATE_PATH: il percorso in cui scrivere il certificato, ad esempio saml-certificate.cer o saml-certificate.pem

    Configura l'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 che emette. Per istruzioni specifiche, consulta il team del tuo IdP.

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

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

    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 WORKLOAD_PROVIDER_ID \
      --location global

    Sostituisci quanto segue:

    • KEY_ID: il nome della chiave
    • WORKLOAD_POOL_ID: l'ID del pool
    • WORKLOAD_PROVIDER_ID: l'ID provider del pool di identità della forza lavoro

    Algoritmi crittografici SAML supportati

    La federazione delle identità per i workload supporta i seguenti algoritmi di trasporto delle chiavi:

    La federazione delle identità per i workload supporta i seguenti algoritmi crittografici a blocchi:

Configura l'applicazione di accesso sensibile al contesto per la federazione delle identità per i workload

L'applicazione delle policy di accesso sensibile al contesto si applica solo quando si utilizzano token associati a certificati. Puoi rafforzare la sicurezza delle risorse contro gli attacchi di replay e furto di token attivando l'accesso sensibile al contesto, che applica la convalida mTLS e l'associazione dei certificati per le richieste di accesso. Quando i criteri di accesso sensibile al contesto sono configurati per i token associati ai certificati, Google Cloud valuta il contesto di trasporto e il certificato client delle richieste in entrata per garantire che i token di accesso presentati dal tuo workload siano associati in modo crittografico a una sessione di certificato client mTLS attendibile. L'applicazione delle policy di accesso sensibile al contesto non si applica ai token standard non associati.

Configura la delega dell'identità e i token degli attori

In uno scenario di delega dell'identità, come definito in RFC 8693: OAuth 2.0 Token Exchange, un attore esegue operazioni per conto di un'identità del soggetto.

Per configurare e autorizzare la delega dell'identità, devi soddisfare i seguenti requisiti:

  1. Autorizzazione del provider attore: nella configurazione dei provider attore del provider soggetto (--actor-providers), includi il nome completo della risorsa del provider che emette il token attore. Il fornitore dell'attore deve soddisfare i seguenti criteri:

    • Deve trovarsi nello stesso pool di identità del workload del provider del soggetto.
    • L'ID container del progetto nel nome della risorsa deve corrispondere al formato utilizzato per il provider del soggetto (ad esempio, se utilizzi Google Cloud CLI per creare il provider del soggetto, deve essere l'ID progetto alfanumerico).
    • È possibile autorizzare al massimo 3 provider di attori per provider.

  2. Claim may_act nel token del soggetto: il token ID del soggetto deve includere un claim may_act:

    "may_act": {
  "sub": "ACTOR_SUBJECT",
  "iss": "ACTOR_ISSUER"
}

    Sostituisci quanto segue:

    • ACTOR_SUBJECT: l'identificatore del soggetto dell'attore autorizzato (deve corrispondere alla dichiarazione sub nel token dell'attore).
    • ACTOR_ISSUER: (Facoltativo) L'URI dell'emittente del provider di identità dell'attore (deve corrispondere alla rivendicazione iss nel token dell'attore). Se omesso, l'attore deve condividere lo stesso emittente del token dell'oggetto.

  3. Parametri di scambio dei token: quando esegue uno scambio di token con la federazione delle identità per i workload, il client fornisce sia subject_token che actor_token, insieme ai rispettivi tipi di token (subject_token_type e actor_token_type):

    • subject_token: il token di sicurezza che rappresenta l'identità per conto della quale viene effettuata la richiesta.
    • subject_token_type: un identificatore che indica il tipo di token del soggetto (ad esempio urn:ietf:params:oauth:token-type:jwt o urn:ietf:params:oauth:token-type:id_token).
    • actor_token: il token di sicurezza che rappresenta l'identità della parte che agisce. Il token dell'attore deve soddisfare i seguenti requisiti:
      • Claim Audience (aud): deve contenere l'URI completo della risorsa del provider di attori specifico che emette actor_token: //iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/ACTOR_PROVIDER_ID. La rivendicazione aud deve contenere un solo URI della risorsa del provider del pool di identità del workload. Se nello stesso pool di identità del workload esistono più provider di attori, includi solo l'URI della risorsa per il provider che emette actor_token.
      • Provider di attori autorizzato: il provider di attori identificato nella rivendicazione aud deve risiedere nello stesso pool di identità del workload del provider di soggetti ed essere elencato nella configurazione dei provider di attori del provider di soggetti (--actor-providers).
      • Claim sub e iss corrispondenti: il claim sub e il claim facoltativo iss del token dell'attore devono corrispondere ai valori sub e iss dichiarati nel claim may_act del token del soggetto.
    • actor_token_type: un identificatore che indica il tipo di token dell'attore (urn:ietf:params:oauth:token-type:jwt o urn:ietf:params:oauth:token-type:id_token). Questo parametro è obbligatorio se è presente actor_token.
    • Token associati a certificati con delega: se il subject_token è associato a un certificato (contiene un claim di conferma cnf), anche il actor_token deve essere associato a un certificato (contenere un claim cnf). Quando esegui lo scambio di token su mTLS (sts.mtls.googleapis.com), il certificato client presentato nell'handshake mTLS deve corrispondere all'impronta del certificato di actor_token.

Autentica un workload

Devi eseguire questi passaggi una volta per ogni workload.

Consenti al tuo workload esterno di accedere alle risorse Google Cloud

Per fornire al tuo workload l'accesso alle risorse Google Cloud , ti consigliamo di concedere l'accesso diretto alle risorse all'entità. In questo caso, l'entità è l'utente federato. Alcuni prodotti Google Cloud hanno limiti API Google Cloud. Se il tuo workload chiama un endpoint API con una limitazione, puoi utilizzare la simulazione dell'identità dei account di servizio. In questo caso, l'entità è il service accountGoogle Cloud , che funge da identità. Concedi l'accesso al account di servizio sulla risorsa.

Accesso diretto alle risorse

Puoi concedere l'accesso a un'identità federata direttamente sulle risorse utilizzando la console Google Cloud o gcloud CLI.

Console

Per utilizzare la console Google Cloud per concedere i ruoli IAM direttamente su una risorsa, devi andare alla pagina della risorsa e poi concedere il ruolo. L'esempio seguente mostra come andare alla pagina Cloud Storage e concedere il ruolo Storage Object Viewer (roles/storage.objectViewer) a un'identità federata direttamente su un bucket Cloud Storage.

  1. Nella console Google Cloud , vai alla pagina Bucket in Cloud Storage.

    Vai a Bucket

  2. Nell'elenco dei bucket, fai clic sul nome del bucket per cui vuoi concedere il ruolo.

  3. Seleziona la scheda Autorizzazioni nella parte superiore della pagina.

  4. Fai clic sul pulsante Concedi l'accesso.

    Viene visualizzata la finestra di dialogo Aggiungi entità.

  5. Nel campo Nuove entità, inserisci una o più identità che devono accedere al tuo bucket.

    Per materia 

    principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT

    Sostituisci quanto segue:

    • PROJECT_NUMBER: il numero del progetto
    • POOL_ID: l'ID del pool di workload
    • SUBJECT: il singolo soggetto mappato dal tuo IdP, ad esempio administrator@example.com

    Per gruppo 

    principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/group/GROUP

    Sostituisci quanto segue:

    • PROJECT_NUMBER: il numero del progetto
    • WORKLOAD_POOL_ID: l'ID del pool di workload
    • GROUP: il gruppo mappato dal tuo IdP, ad esempio administrator-group@example.com

    Per attributo 

    principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE

    Sostituisci quanto segue:

    • PROJECT_NUMBER: il numero del progetto
    • WORKLOAD_POOL_ID: l'ID del pool di workload
    • ATTRIBUTE_NAME: uno degli attributi mappati dal tuo IdP
    • ATTRIBUTE_VALUE: il valore dell'attributo

  6. Seleziona uno o più ruoli dal menu a discesa Seleziona un ruolo. I ruoli selezionati vengono visualizzati nel riquadro con una breve descrizione delle autorizzazioni che concedono.

  7. Fai clic su Salva.

gcloud

Per utilizzare gcloud CLI per concedere ruoli IAM su una risorsa in un progetto, segui questi passaggi:

  1. Ottieni il numero del progetto in cui è definita la risorsa.

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

  2. Concedi l'accesso alla risorsa.

    Per utilizzare gcloud CLI per concedere il ruolo Visualizzatore oggetti Storage (roles/storage.objectViewer) alle identità esterne che soddisfano determinati criteri, esegui questo comando.

    Per materia

    gcloud storage buckets add-iam-policy-binding BUCKET_ID \
    --role=roles/storage.objectViewer \
    --member="principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT"

    Per gruppo

    gcloud storage buckets add-iam-policy-binding BUCKET_ID \
    --role=roles/storage.objectViewer \
    --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/group/GROUP"

    Per attributo

    gcloud storage buckets add-iam-policy-binding BUCKET_ID \
    --role=roles/storage.objectViewer \
    --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE"

    Sostituisci quanto segue:

    • BUCKET_ID: il bucket a cui concedere l'accesso
    • PROJECT_NUMBER: il numero di progetto del progetto che contiene il pool di identità del workload
    • POOL_ID: l'ID del pool di identità del workload
    • 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
    • ATTRIBUTE_VALUE: il valore dell'attributo personalizzato nella mappatura degli attributi

    Puoi concedere ruoli su qualsiasi risorsa Google Cloud che supporta le policy di autorizzazione IAM.

Simulazione dell'identità dei service account

  1. Per creare un account di servizio per il workload esterno:

    1. Attiva le API IAM, Security Token Service e API Service Account Credentials, se non sono già attive.

      Ruoli richiesti per abilitare le API

      Per abilitare le API, devi disporre dell'autorizzazione serviceusage.services.enable. Se hai creato il progetto, probabilmente hai già questa autorizzazione tramite il ruolo Proprietario (roles/owner). In caso contrario, puoi ottenere questa autorizzazione tramite il ruolo Amministratore Service Usage (roles/serviceusage.serviceUsageAdmin). Scopri come concedere i ruoli.

      Abilita le API

    2. Crea un service account che rappresenta il workload. Ti consigliamo di utilizzare un account di servizio dedicato per ogni workload. Il account di servizio non deve trovarsi nello stesso progetto del pool di identità del workload, ma devi fare riferimento al progetto che contiene il account di servizio.

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

  2. Per consentire all'identità federata di assumere l'identità del account di servizio, segui questi passaggi:

Console

Per utilizzare la console Google Cloud per concedere i ruoli IAM a un'identità federata con un account di servizio, segui questi passaggi:

Service account nello stesso progetto

  1. Per concedere l'accesso utilizzando la simulazione dell'identità dei account di servizio per un account di servizio nello stesso progetto, segui questi passaggi:

    1. Vai alla pagina Pool di Workload Identity.

      Vai a Pool di identità del workload

    2. Seleziona Concedi l'accesso.

    3. Nella finestra di dialogo Concedi l'accesso al service account, seleziona Concedi l'accesso utilizzando la simulazione dell'identità dei service account.

    4. Nell'elenco Service account, seleziona il account di servizio di cui le identità esterne devono assumere l'identità e segui questi passaggi:

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

      • Per consentire solo a identità specifiche del pool di identità del workload di simulare l'identità del account di servizio, seleziona Solo le identità corrispondenti al filtro.

      • Nell'elenco nome dell'attributo, seleziona l'attributo in base al quale vuoi filtrare.

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

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

Service account in un progetto diverso

  1. Per concedere l'accesso utilizzando la simulazione dell'identità dei account di servizio per un account di servizio in un altro progetto, segui questi passaggi:

    1. Vai alla pagina Service Accounts.

      Vai a Service account

    2. Seleziona il account di servizio di cui vuoi assumere l'identità.

    3. Fai clic su Gestisci accesso.

    4. Fai clic su Aggiungi entità.

    5. Nel campo Nuova entità, inserisci uno dei seguenti identificatori di entità per le identità nel tuo pool che assumeranno l'identità del account di servizio.

      Per materia 

      principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT

      Sostituisci quanto segue:

      • PROJECT_NUMBER: il numero del progetto
      • POOL_ID: l'ID del pool di workload
      • SUBJECT: il singolo soggetto mappato dal tuo IdP, ad esempio administrator@example.com

      Per gruppo 

      principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/group/GROUP

      Sostituisci quanto segue:

      • PROJECT_NUMBER: il numero del progetto
      • WORKLOAD_POOL_ID: l'ID del pool di workload
      • GROUP: il gruppo mappato dal tuo IdP, ad esempio administrator-group@example.com

      Per attributo 

      principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE

      Sostituisci quanto segue:

      • PROJECT_NUMBER: il numero del progetto
      • WORKLOAD_POOL_ID: l'ID del pool di workload
      • ATTRIBUTE_NAME: uno degli attributi mappati dal tuo IdP
      • ATTRIBUTE_VALUE: il valore dell'attributo

      Per pool

      principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/*

      Sostituisci quanto segue:

      • PROJECT_NUMBER: il numero del progetto
      • WORKLOAD_POOL_ID: l'ID del pool di workload

    6. In Seleziona un ruolo, seleziona il ruolo Workload Identity User (roles/iam.workloadIdentityUser).

    7. Per salvare la configurazione, fai clic su Salva.

gcloud

Per concedere il ruolo Utente Workload Identity (roles/iam.workloadIdentityUser) a un'entità o un set di entità federate, esegui il seguente comando. Per scoprire di più sugli identificatori delle entità della federazione delle identità per i workload, consulta Tipi di entità.

Per materia

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 del account di servizio
  • PROJECT_NUMBER: il numero di progetto del progetto che contiene il pool di identità del workload
  • POOL_ID: l'ID del pool di identità del workload
  • 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
  • ATTRIBUTE_VALUE: il valore dell'attributo personalizzato nella mappatura degli attributi

Scarica una configurazione delle credenziali

Questa sezione descrive come scaricare la configurazione delle credenziali utilizzando la consoleGoogle Cloud .

Per consentire al tuo workload di accedere alle librerie client, devi prima scaricare e configurare le Credenziali predefinite dell'applicazione (ADC) seguendo questi passaggi:

  1. Nella console Google Cloud , vai alla pagina Pool di identità del workload.

    Vai a Pool di identità del workload

  2. Nella tabella, seleziona il tuo pool per andare alla pagina dei dettagli.

  3. Fai clic su Concedi l'accesso.

  4. Seleziona Concedi l'accesso usando identità federate (consigliato).

  5. Per scaricare le Credenziali predefinite dell'applicazione (ADC) in modo che il tuo workload possa accedere alle librerie client, segui questi passaggi:

    1. Fai clic su Scarica configurazione.

    2. Nella finestra di dialogo Configura l'applicazione, segui questi passaggi:

      1. Nell'elenco a discesa Provider, seleziona il tuo provider.

      2. In Percorso token OIDC o Percorso asserzione SAML, inserisci il percorso in cui si trova il token o l'asserzione.

        3. Nell'elenco a discesa Tipo di formato, seleziona il formato.

    3. Fai clic su Scarica configurazione e prendi nota del percorso in cui hai salvato il file.

Crea una configurazione delle credenziali

Le librerie client di Cloud, gcloud CLI e Terraform possono ottenere automaticamente credenziali esterne e utilizzarle per accedere a Google Cloud. Per consentire alle librerie e agli strumenti di completare questa procedura, devi fornire un file di configurazione delle credenziali. Questo file definisce quanto segue:

  • Dove ottenere le credenziali esterne
  • Quale pool di identità del workload e quale provider utilizzare
  • Il account di servizio di cui simulare l'identità, se utilizzi la simulazione dell'identità dei account di servizio

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

  • Credenziali provenienti da un eseguibile: 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 un documento JSON in STDOUT 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 un documento JSON in STDOUT 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. È 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 terminare 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 (epoca di Unix). Questo campo è obbligatorio solo se è 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 un documento JSON in STDOUT 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. È 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 terminare 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 codificata in Base64.

    • expiration_time: la data e l'ora di scadenza dell'asserzione in secondi (epoca di Unix). Questo campo è obbligatorio solo se è 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: il pubblico della configurazione delle credenziali. Sempre presente.
    • GOOGLE_EXTERNAL_ACCOUNT_TOKEN_TYPE: tipo di token del soggetto previsto. Sempre presente.
    • GOOGLE_EXTERNAL_ACCOUNT_IMPERSONATED_EMAIL: l'indirizzo email del service account. Presente solo quando viene utilizzata la simulazione dell'identità dei account di servizio.
    • GOOGLE_EXTERNAL_ACCOUNT_OUTPUT_FILE: la posizione del file di output dalla configurazione delle credenziali. Presente solo se specificato nella configurazione delle credenziali.

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

  • Credenziali provenienti da file: le librerie leggono la credenziale esterna 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, devi aggiornare il file almeno una volta ogni ora.

  • Credenziali provenienti da 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.

Per creare un file di configurazione delle credenziali, segui questi passaggi:

Credenziali provenienti da eseguibili 

gcloud iam workload-identity-pools create-cred-config \
    projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/WORKLOAD_PROVIDER_ID \
    --service-account=SERVICE_ACCOUNT_EMAIL \
    --service-account-token-lifetime-seconds=SERVICE_ACCOUNT_TOKEN_LIFETIME \
    --sts-location=REGION \
    --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à del workload.
  • POOL_ID: l'ID del pool di identità del workload.
  • WORKLOAD_PROVIDER_ID: l'ID del provider del pool di identità del workload.
  • SERVICE_ACCOUNT_EMAIL: se utilizzi la simulazione dell'identità dei service account, sostituisci con l'indirizzo email del account di servizio. Ometti questo flag se non utilizzi la simulazione dell'identità dei service account.
  • SERVICE_ACCOUNT_TOKEN_LIFETIME: se utilizzi la simulazione dell'identità dei account di servizio, sostituisci con la durata del token di accesso del account di servizio, in secondi; il valore predefinito è un'ora se non viene fornito. Ometti questo flag se non utilizzi la simulazione dell'identità dei account di servizio. Per specificare una durata superiore a un'ora, devi configurare il vincolo della policy dell'organizzazione constraints/iam.allowServiceAccountCredentialLifetimeExtension.
  • REGION: (Facoltativo) Specifica la regione degli endpoint regionali di Security Token Service, se disponibili.
  • 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 esempio --executable-command="/path/to/command --foo=bar".
  • EXECUTABLE_TIMEOUT: la durata facoltativa in millisecondi di attesa per l'esecuzione dell'eseguibile (il valore predefinito è 30 secondi).
  • EXECUTABLE_OUTPUT_FILE: un percorso che rimanda alle credenziali 3PI generate dall'eseguibile. Questa opzione è utile per memorizzare nella cache le credenziali. Se specifichi questo percorso, le librerie di autenticazione ne verificheranno l'esistenza prima di eseguire l'eseguibile.

Credenziali provenienti da file 

gcloud iam workload-identity-pools create-cred-config \
    projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/WORKLOAD_PROVIDER_ID \
    --service-account=SERVICE_ACCOUNT_EMAIL \
    --service-account-token-lifetime-seconds=SERVICE_ACCOUNT_TOKEN_LIFETIME \
    --sts-location=REGION \
    --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: il numero del progetto che contiene il pool di identità del workload.
  • POOL_ID: l'ID del pool di identità del workload.
  • WORKLOAD_PROVIDER_ID: l'ID del provider del pool di identità del workload.
  • SERVICE_ACCOUNT_EMAIL: se utilizzi la simulazione dell'identità dei service account, sostituiscilo con l'indirizzo email del service account. Ometti questo flag se non utilizzi la simulazione dell'identità dei account di servizio.
  • SERVICE_ACCOUNT_TOKEN_LIFETIME: se utilizzi la simulazione dell'identità dei account di servizio, sostituisci con la durata del token di accesso del account di servizio, in secondi; il valore predefinito è un'ora se non viene fornito. Ometti questo flag se non utilizzi la simulazione dell'identità dei account di servizio. Per specificare una durata superiore a un'ora, devi configurare il vincolo della policy dell'organizzazione constraints/iam.allowServiceAccountCredentialLifetimeExtension.
  • REGION: (Facoltativo) Specifica la regione degli endpoint regionali di Security Token Service, se disponibili.
  • FILEPATH: il file in cui salvare la configurazione.
  • TOKEN_FILEPATH: il percorso in cui vengono archiviati i token ID OIDC.
  • SOURCE_TYPE: il formato del file del token ID OIDC, impostato su text (predefinito) o json.
  • FIELD_NAME: il campo nel file di testo che contiene il token (se SOURCE_TYPE è json).

Credenziali provenienti da URL 

gcloud iam workload-identity-pools create-cred-config \
    projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/WORKLOAD_PROVIDER_ID \
    --service-account=SERVICE_ACCOUNT_EMAIL \
    --service-account-token-lifetime-seconds=SERVICE_ACCOUNT_TOKEN_LIFETIME \
    --sts-location=REGION \
    --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: il numero del progetto che contiene il pool di identità del workload.
  • POOL_ID: l'ID del pool di identità del workload.
  • WORKLOAD_PROVIDER_ID: l'ID del provider del pool di identità del workload
  • SERVICE_ACCOUNT_EMAIL: se utilizzi la simulazione dell'identità dei service account, sostituisci con l'indirizzo email del service account. Ometti questo flag se non utilizzi la simulazione dell'identità dei account di servizio.
  • SERVICE_ACCOUNT_TOKEN_LIFETIME: se utilizzi la simulazione dell'identità dei account di servizio, sostituisci con la durata del token di accesso del account di servizio, in secondi; il valore predefinito è un'ora se non viene fornito. Ometti questo flag se non utilizzi la simulazione dell'identità dei account di servizio. Per specificare una durata superiore a un'ora, devi configurare il vincolo della policy dell'organizzazione constraints/iam.allowServiceAccountCredentialLifetimeExtension.
  • REGION: (Facoltativo) Specifica la regione degli endpoint regionali di Security Token Service, se disponibili.
  • FILEPATH: il 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 del token ID OIDC, impostato su text (predefinito) o json
  • FIELD_NAME: campo nel file di testo che contiene il token (se SOURCE_TYPE è json)

Utilizza la 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 indirizzala al file di configurazione delle credenziali:

    Bash

      export GOOGLE_APPLICATION_CREDENTIALS=`pwd`/FILEPATH.json
    dove FILEPATH è il percorso relativo del file di configurazione delle credenziali.

    PowerShell

      $env:GOOGLE_APPLICATION_CREDENTIALS = Resolve-Path 'FILEPATH.json'
    dove FILEPATH è il percorso relativo del file di configurazione delle credenziali.

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

    C++

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

    Vai

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

    Per verificare quale versione di questo modulo utilizza la tua libreria client, esegui i seguenti 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à per i workload 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 workload se utilizzano la versione 7.0.2 o successive del pacchetto google-auth-library.

    Per verificare quale versione di questo pacchetto utilizza la 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 trovarlo automaticamente. Per trovare l'ID progetto automaticamente, il account di servizio nel file di configurazione deve avere il ruolo Browser (roles/browser) o un ruolo con autorizzazioni equivalenti nel tuo progetto. Per maggiori dettagli, consulta la README per il pacchetto google-auth-library.

    Python

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

    Per verificare quale versione di questo pacchetto utilizza la tua libreria client, esegui il seguente 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, il service account nel file di configurazione deve avere il ruolo Browser (roles/browser) o un ruolo con autorizzazioni equivalenti nel progetto. Per maggiori dettagli, consulta la guida dell'utente per il pacchetto google-auth.

    gcloud

    Per eseguire l'autenticazione utilizzando la federazione delle identità per i workload, 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 della federazione delle identità per i workload in gcloud CLI è disponibile nella versione 363.0.0 e successive di gcloud CLI.

    Terraform

    Il providerGoogle Cloud supporta la federazione delle identità per i workload se utilizzi la versione 3.61.0 o successive:

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

    bq

    Per eseguire l'autenticazione utilizzando la federazione delle identità per i workload, 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 della federazione delle identità per i workload in bq è disponibile nella versione 390.0.0 e successive di gcloud CLI.

Passaggi successivi