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

Questa guida descrive come utilizzare la federazione delle identità di carico di lavoro con i certificati X.509 emessi dalla tua autorità di certificazione (CA) per autenticarti su Google Cloud e accedere alle risorse Google Cloud.

Se i tuoi workload dispongono di un certificato client mTLS, puoi autenticarti su Google Cloud registrando una o più CA con la federazione delle identità per i workload come ancore di attendibilità. Puoi anche registrare CA intermedie.

Utilizzando la federazione delle identità per i carichi di lavoro, puoi consentire a questi carichi di lavoro di ottenere credenziali Google Cloud di breve durata tramite una connessione TLS mutuale (mTLS). I workload possono utilizzare queste credenziali di breve durata per accedere alle API Google Cloud.

Concetti

I concetti di federazione basata su certificati X.509 includono quanto segue:

• Un ancora di attendibilità è un certificato CA considerato come la radice di attendibilità. Eventuali catene di certificati client devono essere collegate a uno degli ancoraggi di attendibilità.

• Un'autorità di certificazione intermedia è un certificato facoltativo dell'autorità di certificazione che aiuta a creare la catena di certificati client.

• Un archivio attendibilità contiene i certificati delle ancore di attendibilità e i certificati CA intermedi utilizzati per convalidare la catena di certificati client. Un'autorità di certificazione emette certificati attendibili per il client.

  Puoi caricare i seguenti tipi di certificati client nel trust store:

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

Prima di iniziare

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

1. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Go to project selector

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

2. Make sure that billing is enabled for your Google Cloud project.

Enable the IAM, Resource Manager, Service Account Credentials, and Security Token Service APIs.

Enable the APIs

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per configurare la federazione di Workload Identity, chiedi all'amministratore di concederti i seguenti ruoli IAM nel progetto:

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

Per saperne di più sulla concessione dei ruoli, consulta Gestire 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 Proprietario IAM (roles/owner) include anche le autorizzazioni per configurare la federazione delle identità. Non dovresti concedere ruoli di base in un ambiente di produzione, ma puoi farlo in un ambiente di sviluppo o di test.

Configurare la federazione delle identità per i carichi di lavoro

Questa sezione mostra come configurare la federazione delle identità per i carichi di lavoro e il tuo magazzino delle credenziali. Devi eseguire questi passaggi una sola volta per ogni elenco attendibile. Puoi quindi utilizzare lo stesso provider e lo stesso pool di identità di carico di lavoro per più carichi di lavoro e in più progetti Google Cloud.

Creare e configurare un archivio attendibilità

Questa sezione mostra come creare un file di configurazione YAML dell'archivio attendibilità e un certificato CA autofirmato.

Genera una chiave e certificati firmati

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

Se hai già i certificati, puoi saltare questo passaggio e continuare con Formattare i certificati.

Per generare un certificato radice e un certificato intermedio firmato con campi keyUsage e extendedKeyUsage validi, svolgi i seguenti passaggi:

1. Crea un file example.cnf di esempio con la configurazione minima richiesta per creare certificati di firma validi. Puoi modificare questo file per impostare campi aggiuntivi su questi certificati.

   cat > example.cnf << EOF
   [req]
   distinguished_name = empty_distinguished_name
   [empty_distinguished_name]
   # Kept empty to allow setting via -subj command line arg.
   [ca_exts]
   basicConstraints=critical,CA:TRUE
   keyUsage=keyCertSign
   extendedKeyUsage=clientAuth
   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 di firma 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
   

Formatta i certificati

Per includere certificati nuovi o esistenti in un archivio attendibilità, formattali in un'unica riga e memorizzali nelle variabili di ambiente in modo che possano essere letti nel file YAML. I certificati devono essere in formato PEM. Per formattare i certificati e memorizzarli nelle variabili di ambiente:

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 un file YAML del trust store

In questa sezione crei un file YAML dell'archivio attendibilità contenente le ancore di attendibilità e le CA intermedie.

Per creare il file YAML del magazzino delle credenziali, esegui il seguente comando. Questo file contiene i contenuti dei certificati delle variabili di ambiente che hai creato in Formattare i certificati. Per aggiungere altri riferimenti di attendibilità, aggiungi altre voci trustAnchors in trustStore. Per aggiungere altri certificati CA intermedi, aggiungi altre voci intermediateCas in trustStore.

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

Definire una mappatura degli attributi e una condizione

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

Se vuoi, 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 cliente, tra cui:

• serialNumberHex: il numero di serie
• subject.dn.cn: il nome comune dell'oggetto
• subject.dn.o: il nome dell'organizzazione soggetta
• subject.dn.ou: l'unità organizzativa in questione
• issuer.dn.cn: il nome comune dell'emittente
• issuer.dn.o: il nome dell'organizzazione emittente
• issuer.dn.ou: l'unità organizzativa dell'emittente
• san.dns: il primo nome DNS del nome alternativo dell'oggetto
• san.uri: il primo URI del nome alternativo del soggetto

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

(Facoltativo) 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 ha valore true per una determinata credenziale, la credenziale viene accettata. In caso contrario, le credenziali vengono rifiutate.

Puoi utilizzare una condizione dell'attributo per limitare i soggetti che possono utilizzare la federazione delle identità per i carichi di lavoro per ottenere token Google Cloud di 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"

Crea il provider e il pool di identità del workload

1. Per creare un nuovo pool di identità per i carichi di lavoro, esegui il seguente comando:

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

   Sostituisci quanto segue:

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

2. Per aggiungere un provider del pool di identità del workload X.509, esegui il seguente 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" \
       --billing-project="ALLOWLISTED_PROJECT"
   

   Sostituisci quanto segue:

   • PROVIDER_ID: un ID fornitore del pool di identità del workload univoco a tua scelta.
   • POOL_ID: l'ID del pool di identità del workload che hai creato in precedenza.
   • TRUST_STORE_CONFIG: il file YAML del trust store.
   • MAPPINGS: un elenco separato da virgole di mappature degli attributi che hai creato in precedenza in questa guida. Se non specifichi google.subject, la mappatura predefinita sarà google.subject=assertion.subject.dn.cn
   • CONDITIONS: un'condizione dell'attributo facoltativa che hai creato in precedenza in questa guida. Rimuovi il parametro se non hai una condizione dell'attributo.
   • ALLOWLISTED_PROJECT: l'ID progetto.

Autentica un carico di lavoro

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

Consenti al tuo carico di lavoro esterno di accedere alle risorse Google Cloud

Per fornire al tuo carico di lavoro l'accesso alle risorse Google Cloud, consigliamo di concedere l'accesso diretto alle risorse al principale. In questo caso, l'entità è l'utente federato. Alcuni prodotti Google Cloud presentano limitazioni dell'API Google Cloud. Se il tuo carico di lavoro chiama un endpoint API con una limitazione, puoi utilizzare la simulazione dell'identità dell'account di servizio. In questo caso, l'entità è l'account di servizio Google Cloud, che funge da identità. Concedi l'accesso all'account di servizio nella risorsa.

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"

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"

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"

Scaricare o creare una configurazione delle credenziali

Le librerie client di Cloud e la gcloud CLI possono ottenere automaticamente le credenziali esterne e utilizzarle per rubare l'identità di un account di servizio. Per consentire alle librerie e agli strumenti di completare questa procedura, devi fornire un file di configurazione delle credenziali. Questo file definisce quanto segue:

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

Inoltre, per la federazione dei certificati X.509 è necessario un file di configurazione del certificato. Questo file contiene i percorsi dei file del certificato client X.509 e della chiave privata.

Per creare file di configurazione delle credenziali e dei certificati:

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_KEY_PATH \
    --output-file=FILEPATH.json

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_KEY_PATH \
    --output-file=FILEPATH.json

Utilizzare la configurazione delle credenziali per accedere a Google Cloud

Per consentire agli strumenti e alle librerie client di utilizzare la configurazione delle credenziali, svolgi i seguenti 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 al file di configurazione delle credenziali.

   PowerShell

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

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

2. Assicurati che la libreria client possa trovare il file di configurazione del certificato. Il file di configurazione del certificato deve essere archiviato nella posizione predefinita di Google Cloud CLI:

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

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

   o indicato dalla variabile di ambiente GOOGLE_API_CERTIFICATE_CONFIG.

3. Utilizza una libreria client o uno strumento che supporta la federazione delle identità per i carichi di lavoro e può trovare automaticamente le credenziali:

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

  pip show google-auth

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

Ottenere un token di accesso utilizzando una richiesta normale per accedere a Google Cloud

Per ottenere il token di accesso:

1. Utilizza curl per eseguire 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",
   }'
   

   Sostituisci quanto segue:

   • CLIENT_CERT_KEY: la chiave privata del certificato client
   • CLIENT_CERT: il certificato client

   • WORKLOAD_IDENTITY_POOL_URI: l'URL del fornitore del pool di identità del workload nel seguente formato:

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

2. Utilizza il token di accesso con indicazione del portatore generato nel passaggio precedente per accedere alle risorse Google Cloud, ad esempio:

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

Quote e limiti

La tabella seguente elenca le quote e i limiti.

Passaggi successivi

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