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

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

Se i tuoi workload possiedono un certificato client mTLS, puoi autenticarti a Trusted 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 Trusted Cloud di breve durata tramite una connessione TLS reciproca (mTLS). I workload possono utilizzare queste credenziali di breve durata per accedere alle APITrusted Cloud .

Concetti

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

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

• Una CA intermedia è un certificato dell'autorità di certificazione facoltativo che consente di creare la catena di certificati client.

• Un archivio di attendibilità contiene i certificati 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 attendibile:

  • 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 workload:

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

   Go to project selector

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

2. Verify that billing is enabled for your Trusted Cloud project.

3. 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 delle identità per i carichi di lavoro, chiedi all'amministratore di concederti i seguenti ruoli IAM nel progetto:

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

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 Proprietario IAM (roles/owner) include anche le autorizzazioni per configurare la federazione delle identità. Non devi concedere ruoli di base in un ambiente di produzione, ma puoi concederli in un ambiente di sviluppo o di test.

Crea un trust store

Questa sezione mostra come creare un truststore. A livello generale, i passaggi sono i seguenti:

• Generare certificati autofirmati
• Formattare i certificati
• Crea l'archivio attendibilità

Generare 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 Formattare i certificati.

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

Per generare un certificato radice e un certificato intermedio firmato con campi keyUsage e extendedKeyUsage validi, procedi nel seguente modo:

1. Crea un file di configurazione openssl per creare i certificati di firma. Come minimo, 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 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
   

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 dall'intermedio.

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

Formattare i certificati

Per includere certificati nuovi o esistenti in un archivio di attendibilità, formattali 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, fai quanto segue:

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 attendibilità

In questa sezione, crei un archivio di attendibilità utilizzando un file in formato YAML che contiene le ancore di attendibilità 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 ancore attendibili, aggiungi altre voci trustAnchors in trustStore. Per aggiungere altri certificati CA intermedi, aggiungi altre voci intermediateCas in trustStore.

Per creare il file del truststore, esegui questo comando:

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

Definisci un mapping degli attributi e una condizione

Il certificato X.509 client può contenere più attributi. Devi selezionare l'attributo da utilizzare come identificatore del soggetto mappando google.subject in Trusted Cloud all'attributo del certificato. Ad esempio, se l'attributo nel certificato è il nome comune del soggetto, il mapping sarà il 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 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 del soggetto
• subject.dn.ou: l'ultima unità organizzativa del soggetto
• 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 del soggetto del certificato client, assertion.subject.dn.cn.

(Facoltativo) Puoi definire una condizione dell'attributo. Le condizioni degli attributi sono espressioni CEL che possono controllare gli attributi dell'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 carichi di lavoro per ottenere token Trusted 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"

Configura la federazione delle identità per i workload

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

Crea il pool di identità del workload

1. Per creare un nuovo pool di identità dei carichi di lavoro, 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.

Crea il fornitore del pool di identità del workload

1. Per aggiungere un fornitore di 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"
   

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

Autenticare un workload

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

Consenti al carico di lavoro esterno di accedere alle risorse Trusted Cloud

Per fornire al tuo workload l'accesso alle risorse Trusted Cloud , ti consigliamo di concedere l'accesso diretto alle risorse all'entità. In questo caso, il principal è l'utente federato. Alcuni prodotti Trusted Cloud hanno limitazioni dell'API Google Cloud. Se il tuo carico di lavoro chiama un endpoint API che presenta una limitazione, puoi invece utilizzare la rappresentazione dell'identità delaccount di serviziot. In questo caso, l'entità è il service accountTrusted Cloud , che funge da identità. Concedi l'accesso alaccount di serviziot sulla 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 rappresentare un account di servizio. Per consentire a librerie e strumenti di completare questa procedura, devi fornire un file di configurazione delle credenziali. Questo file fornisce le seguenti informazioni:

• Dove ottenere le credenziali esterne
• Quale fornitore e pool di identità del workload utilizzare
• Quale account di servizio rappresentare

Inoltre, per la federazione di 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.

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

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 \
    --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 \
    --credential-cert-trust-chain-path=TRUST_CHAIN_PATH \
    --output-file=FILEPATH.json

Utilizza la configurazione delle credenziali per accedere a Trusted Cloud

Per consentire a strumenti e 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. 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.

2. 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 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.

3. Utilizza le seguenti librerie client di Cloud che supportano la federazione delle identità dei carichi di lavoro con i certificati X.509.

   Vai

   Le librerie client per Go supportano la federazione delle identità per i carichi di lavoro 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 il seguente comando nella directory contenente il file go.mod per il 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 carichi di lavoro X.509 se utilizzano la versione 2.39.0 o successive del pacchettogoogle-auth.

   Per controllare 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 oppure puoi consentire al client di trovare automaticamente l'ID progetto. Per trovare automaticamente l'ID progetto, il service account nel file di configurazione deve disporre del ruolo Browser (roles/browser) o di un ruolo con autorizzazioni equivalenti per il tuo progetto. Per maggiori dettagli, consulta la guida dell'utente per il pacchetto google-auth.

4. Se il tuo carico di lavoro viene eseguito su macOS, imposta CLOUDSDK_PYTHON_SITEPACKAGES=1 per configurare gcloud CLI in modo che utilizzi le librerie Python al di fuori della directory di installazione.

5. Per eseguire l'autenticazione 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 della federazione delle identità per i carichi di lavoro X.509 in gcloud CLI è disponibile nella versione 519.0 e successive di gcloud CLI.

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

Crea la catena di attendibilità

Questo passaggio mostra come creare la catena di attendibilità. Quando chiami Security Token Service in una richiesta non criptata, trasmetti la catena di attendibilità nel campo subject_token.

Formatta i certificati da includere nella catena come elenco in formato JSON, come specificato nella RFC 7515. Il certificato foglia utilizzato per l'handshake mTLS deve essere specificato come primo elemento. Ogni certificato nel bundle deve essere una stringa codificata in 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 trasmesse come subject_token nella chiamata a Security Token Service, più avanti in questo documento

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

Ottenere 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.s3nsapis.fr/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 riportate nella sezione Formattare i certificati, sostituisci TRUST_CHAIN con '"${TRUST_CHAIN}"'.

2. Utilizza il token di accesso di tipo bearer generato nel passaggio precedente per accedere alle risorseTrusted Cloud , ad esempio:

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

Limiti

La tabella seguente elenca i limiti.

Passaggi successivi

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