Configurare la federazione delle identità per i carichi di lavoro con certificati X.509

La federazione delle identità per i workload ti consente di utilizzare i certificati X.509 emessi dalla tua autorità di certificazione (CA) per autenticarti su Google Cloud senza gestire le chiavi degli account di servizio. Quando registri i trust anchor e le CA intermedie facoltative, i workload possono utilizzare i certificati client su mutual TLS (mTLS) per ottenere credenziali di breve durata per le APIGoogle Cloud .

Concetti

I concetti della federazione basata su certificati X.509 includono:

  • Un trust anchor è un certificato CA considerato come la radice di attendibilità. Le catene di certificati client devono essere concatenate a uno dei trust anchor.

  • Una CA intermedia è un certificato CA facoltativo che aiuta a creare la catena di certificati client.

  • Un archivio di attendibilità contiene i certificati dei trust anchor e i certificati CA intermedi utilizzati per convalidare la catena di certificati client. Una CA emette certificati attendibili per il client.

    Puoi caricare i seguenti tipi di certificati client nell'archivio di attendibilità:

    • Certificati emessi da CA di terze parti di tua scelta
    • Certificati emessi dalle tue CA private
    • Certificati firmati, come descritto in Crea certificati autofirmati

Prima di iniziare

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

  1. Verifica di disporre delle autorizzazioni necessarie per completare questa guida.
  2. 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

  3. Ti consigliamo di utilizzare un progetto dedicato per gestire i pool e i provider di identità dei workload.
  4. Verifica che la fatturazione sia attivata per il tuo progetto Google Cloud .

  5. 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 disponi già di 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

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, il ruolo di base IAM Proprietario (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 di test.

Crea un archivio di attendibilità

Questa sezione spiega come creare un archivio di attendibilità. A livello generale, i passaggi sono i seguenti:

Genera certificati autofirmati

Questa sezione mostra come generare chiavi e creare certificati firmati. Se hai già creato i certificati, puoi saltare questa sezione e continuare con Formatta i certificati.

Questa sezione utilizza i comandi openssl per creare certificati radice e intermedi.

Per generare un certificato radice e un certificato intermedio firmato con campi keyUsage e extendedKeyUsage validi, segui questi passaggi:

  1. Crea un file di configurazione openssl per creare i certificati di firma. Il file è simile al seguente, ma puoi impostare campi aggiuntivi in base alle tue esigenze.

    cat > example.cnf << EOF
    [req]
    distinguished_name = empty_distinguished_name
    [empty_distinguished_name]
    # Kept empty to allow setting via -subj command-line argument.
    [ca_exts]
    basicConstraints=critical,CA:TRUE
    keyUsage=keyCertSign
    extendedKeyUsage=clientAuth
    [leaf_exts]
    keyUsage=critical,Digital Signature, Key Encipherment
    basicConstraints=critical, CA:FALSE
    EOF
    
  2. Crea il certificato radice.

    openssl req -x509 \
        -new -sha256 -newkey rsa:2048 -nodes \
        -days 3650 -subj '/CN=root' \
        -config example.cnf \
        -extensions ca_exts \
        -keyout root.key -out root.cert
    
  3. Crea la richiesta firmata per il certificato intermedio.

    openssl req \
        -new -sha256 -newkey rsa:2048 -nodes \
        -subj '/CN=int' \
        -config example.cnf \
        -extensions ca_exts \
        -keyout int.key -out int.req
    
  4. Crea il certificato intermedio.

    openssl x509 -req \
        -CAkey root.key -CA root.cert \
        -set_serial 1 \
        -days 3650 \
        -extfile example.cnf \
        -extensions ca_exts \
        -in int.req -out int.cert
    
  5. Crea la richiesta di firma per il certificato foglia.

    openssl req -new -sha256 -newkey rsa:2048 -nodes \
        -subj '/CN=example' \
        -config example.cnf \
        -extensions leaf_exts \
        -keyout leaf.key -out leaf.req
    
  6. Crea il certificato foglia emesso dal certificato intermedio.

    openssl x509 -req \
        -CAkey int.key -CA int.cert \
        -set_serial 1 -days 1 \
        -extfile example.cnf \
        -extensions leaf_exts \
        -in leaf.req -out leaf.cert
    

Formatta i certificati

Per includere certificati nuovi o esistenti in un archivio di attendibilità, formatta i certificati in una stringa di una riga e memorizzali nelle variabili di ambiente. I certificati devono essere in formato PEM. Per formattare i certificati e archiviarli nelle variabili di ambiente, segui questi passaggi:

  1. Salva il certificato radice come stringa di una riga.

    export ROOT_CERT=$(cat root.cert | sed 's/^[ ]*//g' | sed -z '$ s/\n$//' | tr '\n' $ | sed 's/\$/\\n/g')
    
  2. Salva un certificato intermedio come stringa di una riga.

    export INTERMEDIATE_CERT=$(cat int.cert | sed 's/^[ ]*//g' | sed -z '$ s/\n$//' | tr '\n' $ | sed 's/\$/\\n/g')
    

Crea l'archivio di attendibilità

In questa sezione creerai un archivio di attendibilità utilizzando un file in formato YAML contenente i trust anchor e le CA intermedie.

Questo file contiene i contenuti del certificato delle variabili di ambiente che hai creato in Formatta i certificati. Per aggiungere altri trust anchor, aggiungi altre voci trustAnchors in trustStore. Per aggiungere altri certificati CA intermedi, aggiungi altre voci intermediateCas in trustStore.

Per creare il file dell'archivio di attendibilità, esegui questo comando:

cat << EOF > trust_store.yaml
trustStore:
  trustAnchors:
  - pemCertificate: "${ROOT_CERT}"
  intermediateCas:
  - pemCertificate: "${INTERMEDIATE_CERT}"
EOF

Definisci una mappatura e una condizione degli attributi

Il certificato X.509 del client può contenere più attributi. Devi selezionare l'attributo che vuoi utilizzare come identificatore del soggetto mappando google.subject in Google Cloud all'attributo del tuo certificato. Ad esempio, se l'attributo nel certificato è il nome comune dell'oggetto, la mappatura sarà la seguente: google.subject=assertion.subject.dn.cn

Facoltativamente, puoi mappare altri attributi. Puoi quindi fare riferimento a questi attributi quando concedi l'accesso alle risorse.

Le mappature degli attributi possono utilizzare gli attributi all'interno del certificato client, inclusi i seguenti:

  • serialNumberHex: il numero di serie
  • subject.dn.cn: il nome comune del soggetto
  • subject.dn.o: il nome dell'organizzazione oggetto
  • subject.dn.ou: l'ultima unità organizzativa dell'oggetto
  • issuer.dn.cn: il nome comune dell'emittente
  • issuer.dn.o: il nome dell'organizzazione emittente
  • issuer.dn.ou: l'ultima unità organizzativa dell'emittente
  • san.dns: il primo nome DNS del nome alternativo del soggetto
  • san.uri: il primo URI del nome alternativo del soggetto
  • sha256Fingerprint: hash del certificato foglia SHA256 (Base64)

Devi mappare uno di questi attributi a google.subject per identificare in modo univoco il soggetto. Per proteggerti dalle minacce di spoofing, scegli un attributo con un valore univoco che non può essere modificato. Per impostazione predefinita, l'identificatore google.subject è impostato sul nome comune dell'oggetto del certificato client, assertion.subject.dn.cn.

Facoltativamente, puoi definire 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.

Puoi utilizzare una condizione dell'attributo per limitare i soggetti 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 certificati client contenenti l'ID SPIFFE spiffe://example/path:

assertion.san.uri=="spiffe://example/path"

Configura la federazione delle identità per i workload

Questa sezione mostra come configurare un pool di identità del workload e un provider del pool di identità del workload. Devi eseguire questi passaggi una sola volta per ogni archivio di attendibilità. Puoi quindi utilizzare lo stesso pool di identità del workload e lo stesso provider per più workload e in più progetti Google Cloud .

Crea il pool di identità del workload e il 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. Nella sezione 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. Nella sezione Aggiungi un provider al pool, segui questi passaggi:

    1. In Seleziona un provider, seleziona X509.
    2. In Nome provider, inserisci un nome per il provider. Il nome viene utilizzato anche come ID provider. Non puoi modificare l'ID provider dopo la creazione del provider.
    3. In Trust anchor, inserisci i certificati CA attendibili in formato PEM. Vengono utilizzati per convalidare la catena di certificati client.
    4. (Facoltativo) In Certificati intermedi, inserisci eventuali certificati CA intermedi in formato PEM per creare la catena di attendibilità completa.
    5. Fai clic su Continua.
  5. Nella sezione Configura gli attributi del provider, aggiungi le mappature e le condizioni degli attributi che hai identificato in precedenza.

  6. 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 X.509, esegui questo comando:

    gcloud iam workload-identity-pools providers create-x509 PROVIDER_ID \
        --location=global \
        --workload-identity-pool="POOL_ID" \
        --trust-store-config-path="TRUST_STORE_CONFIG" \
        --attribute-mapping="MAPPINGS" \
        --attribute-condition="CONDITIONS"
    

    Sostituisci quanto segue:

    • 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.
    • TRUST_STORE_CONFIG: il file YAML dell'archivio di attendibilità.
    • MAPPINGS: un elenco separato da virgole di mappature degli attributi che hai creato in precedenza in questo documento. Ad esempio: google.subject=assertion.subject.dn.cn.
    • CONDITIONS: (Facoltativo) Una condizione di attributo che hai creato in precedenza in questo documento. Rimuovi il parametro se non hai una condizione dell'attributo.

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

Puoi rafforzare la sicurezza delle risorse contro gli attacchi di replay dei token attivando l'accesso sensibile al contesto, che applica la convalida mTLS per le richieste di accesso. In questo processo, un'associazione mTLS incorpora policy basate sul contesto di trasporto e utilizza lo stato del certificato del client all'interno della sessione TLS per prendere decisioni di autorizzazione. Per la federazione delle identità dei workload X.509, un'associazione mTLS garantisce che l'intero flusso di autenticazione sia collegato in modo sicuro a un workload attendibile. In questo modo, si riduce il rischio di furto di credenziali, perché l'autenticazione è associata a un endpoint specifico e attendibile.

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

    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 disponi già di 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 impersonare il account di servizio, segui questi passaggi:

Console

Per utilizzare la console Google Cloud per concedere 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 Utente Workload Identity (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à federata o a un set di entità, 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 o crea una configurazione delle credenziali

Le librerie client di Cloud e gcloud CLI possono ottenere automaticamente credenziali esterne e utilizzarle per simulare l'identità di un account di servizio. Per consentire alle librerie e agli strumenti di completare questo processo, devi fornire un file di configurazione delle credenziali.

Inoltre, per la federazione dei certificati X.509, è necessario un file di configurazione del certificato.

I file di configurazione includono:

  • Configurazione delle credenziali: un file JSON che definisce il modo in cui la libreria client interagisce con Security Token Service (STS).
  • Configurazione del certificato: un file JSON che specifica i percorsi locali del certificato client e della chiave privata nel workload.

Crea file di configurazione delle credenziali e dei certificati che consentano alla libreria di ottenere token di accesso utilizzando i certificati X.509.

Accesso diretto alle risorse

Per creare i file di configurazione delle credenziali e dei certificati per l'accesso diretto alle risorse, segui questi passaggi:

Console

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

    Vai a Pool di identità del workload

  2. Fai clic sul nome del pool che contiene il provider che vuoi utilizzare.

  3. Fai clic su Concedi l'accesso.

  4. Nel riquadro Concedi l'accesso al service account, seleziona Concedi l'accesso usando identità federate (consigliato).

  5. Fai clic su Scarica configurazione.

  6. Nella sezione Configura l'applicazione, seleziona il provider che contiene le identità esterne e specifica le seguenti impostazioni:

    • Percorso del certificato client: il percorso locale del file del certificato client.
    • Percorso della chiave privata del client: il percorso locale del file della chiave privata del client.
    • Percorso della catena di attendibilità: (facoltativo) il percorso del file della catena di attendibilità che contiene il certificato client e gli eventuali certificati intermedi necessari per la ricerca dei certificati, ma non configurati nel provider X.509.
  7. Per scaricare un file ZIP contenente i file Configurazione delle credenziali e Configurazione del certificato, fai clic su Scarica configurazione.

  8. Fai clic su Ignora.

Se vuoi utilizzare gli endpoint regionali di Security Token Service, ad esempio https://sts.us-central1.rep.mtls.googleapis.com, consulta Utilizzo degli endpoint regionali di Security Token Service per una maggiore affidabilità.

gcloud

  1. Per creare i file di configurazione delle credenziali e dei certificati per l'accesso diretto alle risorse utilizzando gcloud iam workload-identity-pools create-cred-config, esegui questo comando:

    gcloud iam workload-identity-pools create-cred-config \
      projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID \
        --credential-cert-path=CLIENT_CERT_PATH \
        --credential-cert-private-key-path=CLIENT_PRIVATE_KEY_PATH \
        --credential-cert-trust-chain-path=TRUST_CHAIN_PATH \
        --sts-location=REGION \
        --output-file=FILEPATH.json
    

    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.
    • PROVIDER_ID: l'ID del provider del pool di identità del workload.
    • CLIENT_CERT_PATH: il percorso del file del certificato client.
    • CLIENT_PRIVATE_KEY_PATH: il percorso del file della chiave privata del certificato client.
    • TRUST_CHAIN_PATH: (Facoltativo) Il percorso del file della catena di attendibilità che contiene il certificato client ed eventuali certificati intermedi necessari per la ricerca dei certificati, ma non configurati nel provider X.509.
    • REGION: (Facoltativo) Specifica la regione degli endpoint regionali di Security Token Service, se disponibili.
    • FILEPATH: il file in cui salvare la configurazione.

    L'esecuzione di questo comando creerà anche un file di configurazione del certificato e lo memorizzerà nella posizione predefinita di gcloud CLI:

    • Linux e macOS: ~/.config/gcloud/certificate_config.json

    • Windows: %APPDATA%\gcloud\certificate_config.json

Simulazione dell'identità dei service account

Per creare file di configurazione delle credenziali e dei certificati con la simulazione dell'identità dei account di servizio, segui questi passaggi:

Console

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

    Vai a Pool di identità del workload

  2. Fai clic sul nome del pool che contiene il provider che vuoi utilizzare.

  3. Fai clic su Concedi l'accesso.

  4. Seleziona Concedi l'accesso utilizzando la account di servizio account.

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

  6. Fai clic su Scarica configurazione.

  7. Nella finestra di dialogo Configura l'applicazione, specifica le seguenti impostazioni:

    • Percorso del certificato client: il percorso locale del file del certificato client.
    • Percorso della chiave privata del client: il percorso locale del file della chiave privata del client.
    • Percorso della catena di attendibilità: (facoltativo) il percorso del file della catena di attendibilità che contiene il certificato client e gli eventuali certificati intermedi necessari per la ricerca dei certificati, ma non configurati nel provider X.509.
  8. Per scaricare un file ZIP contenente i file Configurazione delle credenziali e Configurazione del certificato, fai clic su Scarica configurazione.

  9. Fai clic su Ignora.

Se vuoi utilizzare gli endpoint regionali di Security Token Service, ad esempio https://sts.us-central1.rep.mtls.googleapis.com, consulta Utilizzo degli endpoint regionali di Security Token Service per una maggiore affidabilità.

gcloud

  1. Per creare file di configurazione delle credenziali e dei certificati con la simulazione dell'identità dei account di servizio utilizzando gcloud iam workload-identity-pools create-cred-config, esegui questo comando:

    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 \
        --credential-cert-path=CLIENT_CERT_PATH \
        --credential-cert-private-key-path=CLIENT_PRIVATE_KEY_PATH \
        --credential-cert-trust-chain-path=TRUST_CHAIN_PATH \
        --sts-location=REGION \
        --output-file=FILEPATH.json
    

    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.
    • 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 SERVICE_ACCOUNT_EMAIL con l'indirizzo email del account di servizio.
    • SERVICE_ACCOUNT_TOKEN_LIFETIME: la durata del token di accesso del account di servizio, in secondi, se utilizzi la simulazione dell'identità dei account di servizio. Se omessa, la durata predefinita è un'ora. 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.
    • CLIENT_CERT_PATH: il percorso del file del certificato client.
    • CLIENT_PRIVATE_KEY_PATH: il percorso del file della chiave privata del certificato client.
    • TRUST_CHAIN_PATH: (Facoltativo) Il percorso del file della catena di attendibilità che contiene il certificato client ed eventuali certificati intermedi necessari per la ricerca dei certificati, ma non configurati nel provider X.509.
    • REGION: (Facoltativo) Specifica la regione degli endpoint regionali di Security Token Service, se disponibili.
    • FILEPATH: il file in cui salvare la configurazione.

    L'esecuzione di questo comando creerà anche un file di configurazione del certificato e lo memorizzerà nella posizione predefinita di Google Cloud CLI:

    • Linux e macOS: ~/.config/gcloud/certificate_config.json

    • Windows: %APPDATA%\gcloud\certificate_config.json

Utilizza la configurazione delle credenziali per accedere a Google Cloud

Per consentire agli strumenti e alle librerie client di utilizzare la configurazione delle credenziali, segui questi passaggi. Per scoprire di più sulle Credenziali predefinite dell'applicazione, consulta Come Credenziali predefinite dell'applicazione dell'applicazione.

  1. Se hai scaricato un file ZIP dalla console Google Cloud , estrai l'archivio nel tuo workload esterno.

  2. Aggiorna il file di configurazione del certificato con i percorsi dei file locali effettivi per il certificato client e la chiave privata per i seguenti campi:

    • cert_path: il percorso del certificato client.
    • key_path: il percorso della chiave privata.
  3. Inizializza una variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS e impostala sul file di configurazione delle credenziali:

    Bash

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

    PowerShell

      $env:GOOGLE_APPLICATION_CREDENTIALS = Resolve-Path 'FILEPATH.json'
      
    Sostituisci FILEPATH con il percorso relativo del file di configurazione delle credenziali.
  4. Assicurati che la libreria client possa trovare il file di configurazione del certificato. Il file di configurazione del certificato si trova in uno dei seguenti percorsi:

    • Il percorso in cui estrai il file ZIP. (se hai scaricato la configurazione dalla console Google Cloud ).

    • Il percorso predefinito di gcloud CLI:

      • Linux e macOS: ~/.config/gcloud/certificate_config.json

      • Windows: %APPDATA%\gcloud\certificate_config.json

    • Il percorso impostato nella variabile di ambiente GOOGLE_API_CERTIFICATE_CONFIG.

  5. Utilizza le seguenti librerie client di Cloud che supportano la federazione delle identità per i workload con i certificati X.509.

    Vai

    Le librerie client per Go supportano la federazione delle identità per i workload X.509 se utilizzano la versione 0.16.0 o successive del modulo cloud.google.com/go/auth e la versione 0.189.0 del modulo google.golang.org/api.

    Per verificare quale versione di questi moduli utilizza la tua libreria client, esegui questo comando nella directory contenente il file go.mod del tuo modulo:

      go list -m cloud.google.com/go/auth
      go list -m cloud.google.com/api
    

    Python

    Le librerie client per Python supportano la federazione delle identità per i workload X.509 se utilizzano la versione 2.39.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 l'ID progetto automaticamente. 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.

  6. Se il tuo workload viene eseguito su macOS, imposta CLOUDSDK_PYTHON_SITEPACKAGES=1 per configurare gcloud CLI in modo che utilizzi le librerie Python esterne alla directory di installazione.

  7. Per autenticarti utilizzando gcloud CLI, esegui questo comando:

    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 workload X.509 in gcloud CLI è disponibile nella versione 538.0 e successive di gcloud CLI.

Ottieni un token di accesso utilizzando una richiesta semplice per accedere a Google Cloud

Crea la catena di attendibilità

Questo passaggio mostra come creare la catena di attendibilità. Passi la catena di attendibilità nel campo subject_token quando chiami Security Token Service in una richiesta in testo non crittografato.

Formatta i certificati che devono essere inclusi nella catena come elenco in formato JSON, come specificato in RFC 7515. Il certificato foglia utilizzato per l'handshake mTLS deve essere specificato come primo elemento. Ogni certificato nel bundle deve essere una stringa con codifica base64.

  1. Salva il certificato foglia e il certificato intermedio in stringhe con codifica base64.

    export LEAF_CERT=$(openssl x509 -in leaf.cert -out leaf.der -outform DER && cat leaf.der | openssl enc -base64 -A)
    
    export INTERMEDIATE_CERT=$(openssl x509 -in int.cert -out int.der -outform DER && cat int.der | openssl enc -base64 -A)
    
  2. Crea un elenco di stringhe in formato JSON che possono essere passate come subject_token nella chiamata a Security Token Service, più avanti in questa guida.

    export TRUST_CHAIN="[\\\"${LEAF_CERT}\\\", \\\"${INTERMEDIATE_CERT}\\\"]"
    

Ottieni il token di accesso

Per ottenere il token di accesso:

  1. Esegui lo scambio di token con mTLS e il certificato client:

    curl --key CLIENT_CERT_KEY \
    --cert CLIENT_CERT \
    --request POST 'https://sts.mtls.googleapis.com/v1/token' \
    --header "Content-Type: application/json" \
    --data-raw '{
        "subject_token_type": "urn:ietf:params:oauth:token-type:mtls",
        "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
        "audience": "WORKLOAD_IDENTITY_POOL_URI",
        "requested_token_type": "urn:ietf:params:oauth:token-type:access_token",
        "scope": "https://www.googleapis.com/auth/cloud-platform",
        "subject_token": "TRUST_CHAIN"
    }'
    

    Sostituisci quanto segue:

    • CLIENT_CERT_KEY: la chiave privata del certificato client
    • CLIENT_CERT: il certificato client
    • WORKLOAD_IDENTITY_POOL_URI: l'URL del provider del pool di identità del workload nel seguente formato:

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

    • TRUST_CHAIN: la catena di attendibilità necessaria per verificare il certificato foglia deve includere almeno CLIENT_CERT come primo elemento. Se hai seguito le istruzioni nella sezione Formatta i certificati, sostituisci TRUST_CHAIN con '"${TRUST_CHAIN}"'.

    Per utilizzare gli endpoint Security Token Service regionali, sostituisci https://sts.mtls.googleapis.com/v1/token con quanto segue:

     https://sts.REGION.rep.mtls.googleapis.com/v1/token 

    Sostituisci REGION con una localitàGoogle Cloud , ad esempio us-central1 o europe-west4.

  2. (Facoltativo) Se utilizzi la simulazione dell'identità dei account di servizio, chiama il metodo generateAccessToken dell'API Service Account Credentials di IAM con il token di Security Token Service per ottenere un token di accesso.

    curl -X POST 'https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/SERVICE_ACCOUNT_EMAIL:generateAccessToken' \
        -H "Content-Type: application/json; charset=utf-8" \
        -H "Authorization: Bearer STS_TOKEN" \
        -d '{"scope": ["https://www.googleapis.com/auth/cloud-platform"]}'
    

    Sostituisci quanto segue:

    • SERVICE_ACCOUNT_EMAIL: l'indirizzo email del account di servizio.
    • STS_TOKEN: il token di accesso generato da Security Token Service nel passaggio precedente.
  3. Utilizza il token di accesso di tipo Bearer per accedere alle risorseGoogle Cloud , ad esempio:

    curl -X GET 'https://storage.googleapis.com/my_object' -H "Authorization: Bearer $ACCESS_TOKEN"
    

Limiti

La tabella seguente elenca i limiti.

Elemento Limite Note
Numero di trust anchor 3 Ogni certificato non deve superare i 32 KB.
Numero di certificati intermedi 10 Ogni certificato non deve superare i 32 kB.
Numero di vincoli di nome consentiti durante la convalida dei certificati root e intermedi 10
Certificati intermedi che condividono le stesse informazioni Subject e chiave pubblica Subject 5 Questo limite si applica a ogni archivio di attendibilità.
Profondità della catena di certificati 5 La profondità massima per una catena di certificati, inclusi i certificati radice e client.
Numero di volte in cui i certificati intermedi possono essere valutati durante il tentativo di creare la catena di attendibilità 100
Chiavi dei certificati caricati e trasmessi dal client

Le chiavi RSA possono essere comprese tra 2048 e 4096 bit.

I certificati ECDSA devono utilizzare curve P-256 o P-384.

RSA-2048 e P-256 sono consigliati per i casi d'uso normali, utilizza altri per best practice di sicurezza.
Durata massima del certificato foglia 390 giorni. I certificati con un periodo di validità superiore a 390 giorni smetteranno di funzionare dopo essere stati validi per più di 390 giorni.

Passaggi successivi