Ottenere token di breve durata per la federazione delle identità per la forza lavoro

Questa guida mostra come utilizzare un pool di identità della forza lavoro e un provider di pool di identità della forza lavoro per ottenere token di breve durata da Security Token Service. Puoi utilizzare i token per accedere alle risorse Google Cloud che supportano la federazione delle identità della forza lavoro e a cui ti è stato concesso l'accesso.

Per ottenere token di breve durata, segui questa procedura:

  1. Ottieni una credenziale dal provider di identità attendibile.
  2. Scambia la credenziale con un token del servizio token di sicurezza.

Prima di iniziare

  1. Configura la federazione delle identità della forza lavoro oppure, per istruzioni specifiche per l'IdP, consulta le seguenti guide:

  2. Devi conoscere l'ID del pool di forza lavoro o l'ID provider.

  3. Assicurati di disporre dell'autorizzazione IAM (Identity and Access Management)serviceusage.services.use. Il ruolo con meno privilegi che contiene questa autorizzazione è Consumer utilizzo dei servizi (roles/serviceusage.serviceUsageConsumer).

  4. Enable the IAM and Security Token Service APIs.

    Enable the APIs

  5. Install the Google Cloud CLI, then initialize it by running the following command: 

    gcloud init

Scambia le credenziali esterne con un token di accesso Google Cloud

Questa sezione mostra come utilizzare Security Token Service per scambiare le credenziali esterne con un token di accesso che concede l'accesso a Google Cloud. A tale scopo, utilizza l'interfaccia a riga di comando gcloud CLI, l'API REST e le librerie client Cloud, come descritto più avanti in questa guida.

Se hai bisogno di un accesso a lungo termine, puoi configurare un processo a lungo termine per aggiornare continuamente le credenziali sulla macchina. In alternativa, puoi eseguire un server locale in background con un endpoint che restituisce le credenziali.

Accesso basato su browser con gcloud CLI

Questa sezione descrive come configurare gcloud CLI per utilizzare un flusso di accesso basato su browser. A tale scopo, crea un file di configurazione di accesso e poi fai riferimento al file nelle chiamate a gcloud auth login o attivalo in modo che venga utilizzato per impostazione predefinita.

Crea il file di configurazione di accesso

Per creare il file di configurazione di accesso, esegui il seguente comando. Facoltativamente, puoi attivare il file come predefinito per gcloud CLI utilizzando il flag --activate. 

gcloud iam workforce-pools create-login-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \
    --output-file=LOGIN_CONFIG_FILE

Sostituisci quanto segue:

  • WORKFORCE_POOL_ID: l'ID del pool di identità della forza lavoro
  • PROVIDER_ID: l'ID del provider del pool di identità della forza lavoro
  • LOGIN_CONFIG_FILE: un percorso al file di configurazione di accesso specificato, ad esempio login.json

Il file contiene gli endpoint utilizzati dalla gcloud CLI per attivare il flusso di autenticazione basato sul browser e impostare il segmento di pubblico sull'IdP configurato nel provider del pool di identità della forza lavoro. Il file non contiene informazioni riservate.

L'output è simile al seguente:

{
  "type": "external_account_authorized_user_login_config",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID",
  "auth_url": "https://auth.cloud.google/authorize",
  "token_url": "https://sts.googleapis.com/v1/oauthtoken",
  "token_info_url": "https://sts.googleapis.com/v1/introspect",
}

Accedere utilizzando l'autenticazione basata sul browser

Per eseguire l'autenticazione utilizzando l'autenticazione di accesso basata sul browser, puoi utilizzare uno dei seguenti metodi:

  • Se hai utilizzato il flag --activate quando hai creato il file di configurazione o se lo hai attivato con gcloud config set auth/LOGIN_CONFIG_FILE, la gcloud CLI lo utilizza automaticamente: 

    gcloud auth login

  • Per accedere specificando la posizione del file di configurazione, esegui il seguente comando: 

    gcloud auth login --login-config=LOGIN_CONFIG_FILE
  • Per utilizzare una variabile di ambiente per specificare la posizione del file di configurazione, imposta CLOUDSDK_AUTH_LOGIN_CONFIG_FILE sul percorso di configurazione.

Disattivare l'accesso tramite browser

Per interrompere l'utilizzo del file di configurazione dell'accesso:

  • Se hai utilizzato il flag --activate quando hai creato il file di configurazione o se lo hai attivato con gcloud config set auth/LOGIN_CONFIG_FILE, devi eseguire il seguente comando per reimpostarlo: 

    gcloud config unset auth/login_config_file
  • Cancella la variabile di ambiente CLOUDSDK_AUTH_LOGIN_CONFIG_FILE, se impostata.

Utilizzare i file di configurazione per l'accesso

Come alternativa all'accesso tramite browser, questa sezione mostra diversi modi per utilizzare i file di configurazione delle credenziali per fornire l'accesso alle azioni di Google Cloud autenticate. La configurazione dei file di configurazione non richiede di accedere alla gcloud CLI.

La configurazione del file dipende dal fatto che l'IdP utilizzi OIDC o SAML.

OIDC

Puoi recuperare le credenziali utilizzate per configurare il file di configurazione dalle seguenti origini:

Credenziali basate su file

I token vengono caricati da un file. Un altro processo deve aggiornare questo file con un nuovo token OIDC prima della scadenza del token precedente. Ad esempio, se il token ha una durata di un'ora, devi aggiornare il file prima che siano trascorse un'ora.

Per generare il file di configurazione con una credenziale basata su file, esegui il seguente comando:

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \
    --subject-token-type=urn:ietf:params:oauth:token-type:id_token \
    --credential-source-file=PATH_TO_OIDC_ID_TOKEN \
    --workforce-pool-user-project=WORKFORCE_POOL_USER_PROJECT \
    --output-file=config.json

Sostituisci quanto segue:

  • WORKFORCE_POOL_ID: l'ID del pool di forza lavoro
  • PROVIDER_ID: l'ID provider
  • PATH_TO_OIDC_TOKEN: il percorso del file delle credenziali dell'identità OIDC
  • WORKFORCE_POOL_USER_PROJECT: il numero o l'ID progetto associato al progetto utente dei pool di personale.

L'entità deve disporre dell'autorizzazione serviceusage.services.use per questo progetto.

L'esecuzione del comando genera un file di configurazione dell'identità provider OIDC simile al seguente:

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID",
  "subject_token_type": "urn:ietf:params:oauth:token-type:id_token",
  "token_url": "https://sts.googleapis.com/v1/token",
  "workforce_pool_user_project": "WORKFORCE_POOL_USER_PROJECT",
  "credential_source": {
    "file": "PATH_TO_OIDC_CREDENTIALS_FILE"
  }
}

Credenziali basate su URL

I token vengono caricati da un server locale con un endpoint che risponde alle richieste HTTP GET. La risposta deve essere un token ID OIDC, in testo normale o in formato JSON.

Per generare il file di configurazione con una credenziale basata su URL, esegui il comando seguente:

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \
    --subject-token-type=urn:ietf:params:oauth:token-type:id_token \
    --credential-source-url=URL_TO_RETURN_OIDC_ID_TOKEN \
    --workforce-pool-user-project=WORKFORCE_POOL_USER_PROJECT \
    --output-file=config.json

Sostituisci quanto segue:

  • WORKFORCE_POOL_ID: l'ID del pool di forza lavoro.
  • PROVIDER_ID: l'ID provider.
  • URL_TO_RETURN_OIDC_ID_TOKEN: l'URL da chiamare per recuperare le credenziali OIDC, ad esempio un token ID OIDC, ad esempio:http://localhost:5000/token.
  • WORKFORCE_POOL_USER_PROJECT: il numero del progetto utilizzato per la quota e la fatturazione. L'entità deve avere serviceusage.services.use permission in questo progetto.

L'esecuzione del comando genera un file di configurazione dell'identità provider OIDC simile al seguente:

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID",
  "subject_token_type": "urn:ietf:params:oauth:token-type:id_token",
  "token_url": "https://sts.googleapis.com/v1/token",
  "workforce_pool_user_project": "WORKFORCE_POOL_USER_PROJECT",
  "credential_source": {
    "url": "URL_TO_RETURN_OIDC_ID_TOKEN"
  }
}

Credenziali non interattive con origine file eseguibile

I token vengono caricati da un eseguibile locale. L'eseguibile deve fornire un token ID OIDC valido e non scaduto in formato JSON a stdout:

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

Questi campi sono obbligatori per una risposta positiva, ad eccezione di expiration_time. Il campo expiration_time è obbligatorio solo se nella configurazione delle credenziali è stato specificato un file di output.

L'eseguibile deve segnalare eventuali errori a stdout nel seguente formato JSON:

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

Questi campi sono tutti obbligatori per una risposta di errore. I campi codice e messaggio vengono utilizzati dalle librerie client quando viene sollevato l'errore appropriato.

Il comando può restituire i seguenti campi:

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

  • success: lo stato della risposta. Quando lo stato è true, l'eseguibile deve uscire con il codice di uscita 0 e la risposta deve contenere i seguenti campi:

    • token_type: id_token
    • Campo expiration_time, se nella configurazione delle credenziali è specificato un file di output

    Quando lo stato è false, l'eseguibile deve uscire con un valore diverso da zero e la risposta deve contenere i seguenti campi:

    • code
    • message

  • token_type: il tipo di token soggetto di terze parti, che deve essere urn:ietf:params:oauth:token-type:id_token

  • id_token: il token OIDC di terze parti

  • expiration_time: la scadenza del token OIDC di terze parti in secondi (tempo Unix epoch)

  • code: la stringa del codice di errore

  • message: il messaggio di errore

Le librerie client compilano le seguenti variabili di ambiente quando viene eseguito l'eseguibile:

  • GOOGLE_EXTERNAL_ACCOUNT_AUDIENCE: il campo del segmento di pubblico dalla configurazione delle credenziali. Sempre presente.
  • GOOGLE_EXTERNAL_ACCOUNT_TOKEN_TYPE: il tipo di token soggetto previsto. Sempre presente.
  • GOOGLE_EXTERNAL_ACCOUNT_OUTPUT_FILE: la posizione del file di output dalla configurazione delle credenziali. Presente solo se specificato nella configurazione delle credenziali.

Queste variabili di ambiente possono essere utilizzate dall'eseguibile per evitare di codificare rigidamente questi valori.

Per attivare questo metodo di recupero delle credenziali con le librerie client, la variabile di ambiente GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES deve essere impostata su 1.

Per generare il file di configurazione con una credenziale di origine eseguibile, esegui il seguente comando:

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \
    --subject-token-type=urn:ietf:params:oauth:token-type:id_token  \
    --executable-command=EXECUTABLE_COMMAND \
    --executable-timeout-millis=EXECUTABLE_TIMEOUT \
    --executable-output-file=EXECUTABLE_OUTPUT_FILE \
    --workforce-pool-user-project=WORKFORCE_POOL_USER_PROJECT \
    --output-file /path/to/generated/config.json

Sostituisci quanto segue:

  • WORKFORCE_POOL_ID: l'ID del pool di forza lavoro.
  • PROVIDER_ID: l'ID provider.
  • EXECUTABLE_COMMAND: il comando completo, inclusi gli argomenti, da eseguire per recuperare il token soggetto, ad esempio un token ID OIDC, nel seguente formato: --executable-command="/path/to/command --foo=bar".
  • (Facoltativo) EXECUTABLE_TIMEOUT: una durata in millisecondi per attendere l'esecuzione dell'eseguibile (il valore predefinito è 30 secondi).
  • EXECUTABLE_OUTPUT_FILE: (facoltativo) un percorso file alle credenziali di terze parti generate dall'eseguibile. Questo è utile per memorizzare nella cache le credenziali. Le librerie Auth controllano prima questo percorso prima di eseguire l'eseguibile.
  • WORKFORCE_POOL_USER_PROJECT: il numero o l'ID progetto utilizzato per la quota e la fatturazione. L'entità deve avere l'autorizzazione serviceusage.services.use impostata su questo progetto.

L'esecuzione del comando genera un file di configurazione dell'identità provider OIDC simile al seguente:

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID",
  "subject_token_type": "urn:ietf:params:oauth:token-type:id_token",
  "token_url": "https://sts.googleapis.com/v1/token",
  "workforce_pool_user_project": "WORKFORCE_POOL_USER_PROJECT",
  "credential_source": {
    "executable": {
      "command": "EXECUTABLE_COMMAND",
      "timeout_millis": "EXECUTABLE_TIMEOUT",
      "output_file": "EXECUTABLE_OUTPUT_FILE"
    }
  }
}

Credenziali interattive con origine file eseguibile

Puoi fornire un file eseguibile che interagisce con l'utente tramite stdin e stdout. Se l'utente accede correttamente, l'eseguibile scrive una credenziale valida e non scaduta nel file specificato.

Per utilizzare questa modalità, sono necessari i seguenti flag:

  • --executable-output-file: il file in cui l'eseguibile scrive le informazioni sulle credenziali
  • --exeutable-interactive-timeout-millis: un valore diverso da zero che indica la modalità interattiva e imposta il timeout, ad esempio 6000 per un timeout di 60 secondi

I seguenti campi sono obbligatori per una risposta corretta, con l'eccezione di expiration_time:

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

L'eseguibile deve scrivere eventuali errori nel file specificato in --executable-output-file nel seguente formato JSON. I seguenti campi sono tutti obbligatori quando viene restituita una risposta di errore.

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

I campi code e message devono indicare l'errore appropriato. Questi campi vengono utilizzati dalle librerie client quando viene generato l'errore.

Al termine dell'esecuzione, il comando restituisce gli stessi campi, indipendentemente dal fatto che i risultati delle credenziali basate su file eseguibili siano interattivi o meno.

Anche le variabili di ambiente sono le stesse di quelle delle normali credenziali con origine executable.

Per generare una credenziale interattiva basata su file eseguibili, aggiungi il parametro --executable-interactive-timeout-millis e il parametro --executable-output-file.

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \
    --subject-token-type=urn:ietf:params:oauth:token-type:id_token  \
    --executable-command=EXECUTABLE_COMMAND \
    --executable-interactive-timeout-millis=EXECUTABLE_INTERACTIVE_TIMEOUT \
    --executable-output-file=EXECUTABLE_OUTPUT_FILE \
    --workforce-pool-user-project=WORKFORCE_POOL_USER_PROJECT \
    --output-file /path/to/generated/config.json

Sostituisci quanto segue:

  • WORKFORCE_POOL_ID: l'ID del pool di forza lavoro.
  • PROVIDER_ID: l'ID provider.
  • EXECUTABLE_COMMAND: il comando completo, inclusi gli argomenti, da eseguire per recuperare il token soggetto, nel seguente formato: --executable-command="/path/to/command --arg1=val1 --arg2=val2"
  • EXECUTABLE_INTERACTIVE_TIMEOUT: una durata in millesimi di secondo da attendere per l'esecuzione dell'eseguibile.
  • EXECUTABLE_OUTPUT_FILE: un percorso file alle credenziali di terze parti generate dall'eseguibile. Questo percorso è utile per memorizzare nella cache le credenziali. Le librerie Auth controllano prima questo percorso prima di eseguire l'eseguibile.
  • WORKFORCE_POOL_USER_PROJECT: il numero o l'ID progetto utilizzato per la quota e la fatturazione. Il principale deve disporre dell'autorizzazione serviceusage.services.use per questo progetto.

L'esecuzione del comando genera un file di configurazione dell'identità provider OIDC simile al seguente:

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID",
  "subject_token_type": "urn:ietf:params:oauth:token-type:id_token",
  "token_url": "https://sts.googleapis.com/v1/token",
  "workforce_pool_user_project": "WORKFORCE_POOL_USER_PROJECT",
  "credential_source": {
    "executable": {
      "command": "EXECUTABLE_COMMAND",
      "interactive_timeout_millis": "EXECUTABLE_INTERACTIVE_TIMEOUT",
      "timeout_millis": "EXECUTABLE_TIMEOUT",
      "output_file": "EXECUTABLE_OUTPUT_FILE",
    }
  }
}

SAML

Puoi recuperare le credenziali utilizzate per configurare il file di configurazione dalle seguenti origini:

Credenziali basate su file

Le asserzioni vengono caricate da un file. Un altro procedura deve aggiornare questo file con una nuova asserzione SAML codificata in base64 prima che la vecchia asserzione scada. Ad esempio, se l'affermazione ha una durata di un'ora, devi aggiornare il file prima che siano trascorse un'ora.

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \
    --output-file=federation_config.json \
    --credential-source-file=CREDENTIAL_FILE \
    --subject-token-type=urn:ietf:params:oauth:token-type:saml2 \
    --workforce-pool-user-project=WORKFORCE_POOL_USER_PROJECT

Sostituisci quanto segue:

  • WORKFORCE_POOL_ID: l'ID del pool di forza lavoro.
  • PROVIDER_ID: l'ID provider.
  • CREDENTIAL_FILE: il percorso del file delle credenziali generato dall'IdP.
  • WORKFORCE_POOL_USER_PROJECT: il numero o l'ID progetto utilizzato per la quota e la fatturazione. L'entità deve avere serviceusage.services.use permission in questo progetto.

Credenziali basate su URL

Le asserzioni vengono caricate da un server locale con un endpoint che risponde alle richieste HTTP GET. La risposta deve essere o un'affermazione SAML codificata in base64 o JSON contenente un'affermazione SAML codificata in base64.

Per utilizzare le credenziali ricavate da URL, utilizza il flag --credential-source-url:

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \
    --output-file=federation_config.json \
    --credential-source-url=CREDENTIAL_URL \
    --subject-token-type=urn:ietf:params:oauth:token-type:saml2 \
    --workforce-pool-user-project=WORKFORCE_POOL_USER_PROJECT

Sostituisci quanto segue:

  • WORKFORCE_POOL_ID: l'ID del pool di forza lavoro.
  • PROVIDER_ID: l'ID provider.
  • CREDENTIAL_URL: l'URL dell'endpoint del server locale.
  • WORKFORCE_POOL_USER_PROJECT: il numero o l'ID progetto utilizzato per la quota e la fatturazione. L'entità deve avere serviceusage.services.use permission in questo progetto.

Credenziali provenienti da file eseguibili

Le verifiche vengono caricate da un file eseguibile locale. L'eseguibile deve fornire a stdout un'asserzione SAML valida e non scaduta in formato JSON.

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

Questi campi sono obbligatori per una risposta positiva, ad eccezione di expiration_time. Il campo expiration_time è obbligatorio solo quando nella configurazione delle credenziali è specificato un file di output.

Se si verifica un errore, l'eseguibile deve mostrarlo nell'output standard nel seguente formato JSON: 

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

Questi campi sono tutti obbligatori per una risposta di errore. I campi codice e messaggio vengono utilizzati dalle librerie client quando viene sollevato l'errore appropriato.

Il comando può restituire i seguenti campi:

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

  • success: lo stato della risposta. Quando lo stato è true, l'eseguibile deve uscire con il codice di uscita 0 e la risposta deve contenere i seguenti campi:

    • token_type: saml_response
    • Campo expiration_time, se nella configurazione delle credenziali è specificato un file di output

    Quando lo stato è false, l'eseguibile deve uscire con un valore diverso da zero e la risposta deve contenere i seguenti campi: + code + message

  • token_type: il tipo di token soggetto di terze parti, che deve essere urn:ietf:params:oauth:token-type:saml2

  • saml_response: la risposta SAML di terze parti

  • expiration_time: la scadenza della risposta SAML di terze parti in secondi (tempo Unix epoch)

  • code: la stringa del codice di errore

  • message: il messaggio di errore

Le librerie client compilano le seguenti variabili di ambiente quando viene eseguito l'eseguibile:

  • GOOGLE_EXTERNAL_ACCOUNT_AUDIENCE: il campo del segmento di pubblico dalla configurazione delle credenziali. Sempre presente.
  • GOOGLE_EXTERNAL_ACCOUNT_TOKEN_TYPE: il tipo di token soggetto previsto. Sempre presente.
  • GOOGLE_EXTERNAL_ACCOUNT_OUTPUT_FILE: la posizione del file di output dalla configurazione delle credenziali. È presente solo se è specificato nella configurazione delle credenziali.

Per attivare questo metodo di recupero delle credenziali con le librerie client, imposta la variabile di ambiente GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES su 1.

Per generare il file di configurazione con una credenziale di origine eseguibile, esegui il seguente comando:

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \
    --subject-token-type=urn:ietf:params:oauth:token-type:saml2  \
    --executable-command=EXECUTABLE_COMMAND \
    --executable-timeout-millis=EXECUTABLE_TIMEOUT \
    --executable-output-file=EXECUTABLE_OUTPUT_FILE \
    --workforce-pool-user-project=WORKFORCE_POOL_USER_PROJECT \
    --output-file /path/to/generated/config.json

Sostituisci quanto segue:

  • WORKFORCE_POOL_ID: l'ID del pool di forza lavoro.
  • PROVIDER_ID: l'ID provider.
  • EXECUTABLE_COMMAND: il comando completo, inclusi gli argomenti, da eseguire per recuperare il token soggetto nel seguente formato:--executable-command="/path/to/command --foo=bar".
  • EXECUTABLE_TIMEOUT: (facoltativo) la durata in millisecondi da attendere per l'esecuzione dell'eseguibile (il valore predefinito è 30 secondi).
  • EXECUTABLE_OUTPUT_FILE: (facoltativo) il percorso del file delle credenziali 3PI generate dall'eseguibile. Questa operazione è utile per memorizzare nella cache le credenziali. Le librerie Auth ne verificano l'esistenza prima di eseguire il file eseguibile.
  • WORKFORCE_POOL_USER_PROJECT: il numero del progetto utilizzato per la quota e la fatturazione. Il principale deve disporre dell'autorizzazione serviceusage.services.use per questo progetto.

L'esecuzione del comando genera un file di configurazione dell'IdP SAML simile al seguente:

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID",
  "subject_token_type": "urn:ietf:params:oauth:token-type:saml2",
  "token_url": "https://sts.googleapis.com/v1/token",
  "workforce_pool_user_project": "WORKFORCE_POOL_USER_PROJECT",
  "credential_source": {
    "executable": {
      "command": "EXECUTABLE_COMMAND",
      "timeout_millis": "EXECUTABLE_TIMEOUT",
      "output_file": "EXECUTABLE_OUTPUT_FILE"
    }
  }
}

Credenziali provenienti da file eseguibili per la modalità interattiva di gcloud

Un file eseguibile interagisce con l'utente tramite la riga di comando.

Nel comando precedente, sostituisci quanto segue:

  • EXECUTABLE_OUTPUT_FILE: (obbligatorio) il percorso del file che fornisce le credenziali generate dall'eseguibile.
  • EXECUTABLE_TIMEOUT: (obbligatorio) un valore di timeout diverso da zero indica anche al comando di utilizzare la modalità interattiva.
    {
      "version": 1,
      "success": true,
      "token_type": "urn:ietf:params:oauth:token-type:saml2",
      "saml_response": "...",
      "expiration_time": 1620499962
    }

Questi campi sono obbligatori per una risposta positiva, ad eccezione di expiration_time. L'assenza di expiration_time verrà considerata come un segnale che indica che eseguiremo comunque l'eseguibile.

L'eseguibile deve segnalare eventuali errori a executable-output-file nel seguente formato JSON:

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

Questi campi sono tutti obbligatori per una risposta di errore. I campi codice e messaggio vengono utilizzati dalle librerie client quando viene generato l'errore appropriato.

I campi di ritorno del comando per un'esecuzione riuscita sono esattamente gli stessi dei risultati delle credenziali normali con origine eseguibile riportati sopra.

Anche le variabili di ambiente sono le stesse di quelle delle normali credenziali con origine executable.

Per generare una credenziale interattiva basata su file eseguibili, aggiungi il parametro--executable-interactive-timeout-millis.

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \
    --subject-token-type=urn:ietf:params:oauth:token-type:saml2  \
    --executable-command=EXECUTABLE_COMMAND \
    --executable-interactive-timeout-millis=EXECUTABLE_INTERACTIVE_TIMEOUT \
    --executable-output-file=EXECUTABLE_OUTPUT_FILE \
    --workforce-pool-user-project=WORKFORCE_POOL_USER_PROJECT \
    --output-file /path/to/generated/config.json

Sostituisci quanto segue:

  • WORKFORCE_POOL_ID: l'ID del pool di forza lavoro.
  • PROVIDER_ID: l'ID provider.
  • EXECUTABLE_COMMAND: il comando completo, inclusi gli argomenti, da eseguire per recuperare il token soggetto, formattato come segue:--executable-command="/path/to/command --foo=bar").
  • EXECUTABLE_INTERACTIVE_TIMEOUT: una durata in millisecondi da attendere per l'esecuzione dell'eseguibile.
  • EXECUTABLE_OUTPUT_FILE: un percorso file alle credenziali di terze parti generate dall'eseguibile. Questo è utile per memorizzare nella cache le credenziali. Le librerie Auth controllano prima questo percorso prima di eseguire l'eseguibile.
  • WORKFORCE_POOL_USER_PROJECT: il numero o l'ID progetto utilizzato per la quota e la fatturazione. L'entità ha impostato l'autorizzazione serviceusage.services.use su questo progetto.

L'esecuzione del comando genera un file di configurazione dell'IdP SAML simile al seguente:

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/<var>WORKFORCE_POOL_ID<var>/providers/<var>PROVIDER_ID</var>",
  "subject_token_type": "urn:ietf:params:oauth:token-type:saml2",
  "token_url": "https://sts.googleapis.com/v1/token",
  "workforce_pool_user_project": "<var>WORKFORCE_POOL_USER_PROJECT</var>",
  "credential_source": {
    "executable": {
      "command": "<var>EXECUTABLE_COMMAND</var>",
      "interactive_timeout_millis": "<var>EXECUTABLE_INTERACTIVE_TIMEOUT</var>",
      "timeout_millis": "<var>EXECUTABLE_TIMEOUT</var>",
      "output_file": "<var>EXECUTABLE_OUTPUT_FILE</var>",
    }
  }
}

Per accedere, esegui il seguente comando:

gcloud auth login --cred-file=/path/to/config.json

Tieni presente che le interfacce a riga di comando (gcloud, bq) non supportano i tipi di credenziali con origine eseguibile.

Per i flussi headless, gcloud utilizza automaticamente il seguente ambito: https://www.googleapis.com/auth/cloud-platform. gcloud poi pubblica in modo trasparente le tue credenziali nell'endpoint Security Token Service, dove vengono scambiate per token di accesso temporanei di Google Cloud.

Ora puoi eseguire i comandi gcloud utilizzando la gcloud CLI.

Utilizzare le librerie client di Google Cloud

Se utilizzi una libreria client supportata, puoi configurarla in modo che generi automaticamente le credenziali di Google. Se possibile, ti consigliamo di generare le credenziali automaticamente, in modo da non dover implementare autonomamente la procedura di scambio di token.

Il supporto della libreria client di Google Cloud per i pool di risorse è supportato nei seguenti linguaggi: Node.js, Java, Python, Go e C++ (gRPC).

Per utilizzare le librerie client con questi servizi o linguaggi, svolgi i seguenti passaggi:

bq

Per autenticarti utilizzando la federazione delle identità della forza lavoro, utilizza il comando gcloud auth login:

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

dove FILEPATH è il percorso del file di configurazione delle credenziali.

Il supporto della federazione delle identità per la forza lavoro in bq è disponibile nella versione 390.0.0 e successive di Google Cloud CLI.

C++

La maggior parte delle librerie client di Google Cloud per C++ supporta la federazione delle identità per la forza lavoro utilizzando un oggetto ChannelCredentials, creato chiamando grpc::GoogleDefaultCredentials(). Per inizializzare questa credenziale, devi compilare le librerie client con la versione 1.42.0 o superiore di gRPC.

La libreria client Cloud Storage per C++ utilizza l'API REST, non gRPC, pertanto non supporta la federazione delle identità per il personale.

auto creds = grpc::GoogleDefaultCredentials();

// Create a channel, stub and make RPC calls (same as in the previous example)
auto channel = grpc::CreateChannel("greeter.googleapis.com", creds);
std::unique_ptr<Greeter::Stub> stub(Greeter::NewStub(channel));
grpc::Status s = stub->sayHello(&context, *request, response);

gcloud

Per autenticarti utilizzando la federazione delle identità della forza lavoro, utilizza il comando gcloud auth login:

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

dove FILEPATH è il percorso del file di configurazione delle credenziali.

Il supporto della federazione delle identità per la forza lavoro in gcloud è disponibile nella versione 392.0.0 e successive di Google Cloud CLI.

Vai

Le librerie client per Go supportano la federazione delle identità della forza lavoro se utilizzano la versione v0.0.0-20211005180243-6b3c2da341f1 o successive del modulo golang.org/x/oauth2.

import (
  "context"
  "fmt"
  "log"

  "cloud.google.com/go/storage"
  "google.golang.org/api/iterator"
  "google.golang.org/api/option"
  "io/ioutil"
)
ctx := context.Background()
client, err := storage.NewClient(ctx)
# Explicit initialization can also be used.
# var jsonPath = "/path/to/3p-credentials.json"
# client, err := storage.NewClient(ctx, option.WithCredentialsFile(jsonPath))
if err != nil {
  log.Fatal(err)
}
fmt.Println("Buckets:")
it := client.Buckets(ctx, projectID)
for {
  battrs, err := it.Next()
  if err == iterator.Done {
    break
  }
  if err != nil {
    log.Fatal(err)
  }
  fmt.Println(battrs.Name)
}

Java

Le librerie client per Java supportano la federazione delle identità della forza lavoro se utilizzano la versione 1.2.0 o successive dell'elemento com.google.auth:google-auth-library-oauth2-http.

import com.google.auth.oauth2.GoogleCredentials;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;

GoogleCredentials credentials = GoogleCredentials.getApplicationDefault();
GoogleCredentials sourceCredentials = credentials
    .createScoped(Arrays.asList("https://www.googleapis.com/auth/devstorage.read_only"));

Storage storageService = StorageOptions.newBuilder().setProjectId("project-id")
    .setCredentials(sourceCredentials).build().getService();

Node.js

Le librerie client per Node.js supportano la federazione delle identità della forza lavoro. Devi usare la versione 7.10.0 o successive del pacchetto google-auth-library. A differenza dei pool di identità di workload, i pool di forza lavoro sono associati a un'organizzazione e non a un progetto Google Cloud. Quando crei un oggetto GoogleAuth, devi specificare un ID progetto. Per ulteriori informazioni, consulta il file README del pacchetto google-auth-library.

const auth = new GoogleAuth({
  scopes: 'https://www.googleapis.com/auth/cloud-platform',
  // Specify a project ID.
  projectId: 'CLOUD_RESOURCE_PROJECT_ID',
});

# API request using Auth library.
const client = await auth.getClient();
const url =
    `https://storage.googleapis.com/storage/v1/b?projects=${projectId}`;
const res = await client.request({url});
console.log(res.data);

Python

Le librerie client per Python supportano la federazione delle identità della forza lavoro se utilizzano la versione 2.3.0 o successive del pacchetto google-auth.

from google.cloud import storage
import google.auth

credentials, project = google.auth.default(
    scopes=['https://www.googleapis.com/auth/devstorage.read_only'])

client = storage.Client(
    project="project-id", credentials=credentials)

Nell'esempio precedente, il valore project può essere None se la libreria non è in grado di rilevarlo automaticamente. Puoi passarlo esplicitamente quando utilizzi un'istanza di servizio (come nell'esempio del client di archiviazione) o impostarlo tramite la variabile di ambiente GOOGLE_CLOUD_PROJECT.

Per maggiori dettagli, consulta la guida dell'utente per il pacchetto google-auth.

Utilizzo dell'API REST

Puoi chiamare l'API Google Cloud Security Token Service per scambiare le tue credenziali esterne con i token di accesso Google Cloud.

curl https://sts.googleapis.com/v1/token \
    --data-urlencode "audience=//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID" \
    --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
    --data-urlencode "requested_token_type=urn:ietf:params:oauth:token-type:access_token" \
    --data-urlencode "scope=https://www.googleapis.com/auth/cloud-platform" \
    --data-urlencode "subject_token_type=SUBJECT_TOKEN_TYPE" \
    --data-urlencode "subject_token=EXTERNAL_SUBJECT_TOKEN"  \
    --data-urlencode "options={\"userProject\":\"BILLING_PROJECT_NUMBER\"}"

Sostituisci quanto segue:

  • AUDIENCE: il nome completo della risorsa del fornitore che emette il token soggetto.
  • PROVIDER_ID: l'ID provider

  • SUBJECT_TOKEN_TYPE: impostato su una delle seguenti opzioni:

    • urn:ietf:params:oauth:token-type:id_token per i token ID OIDC
    • urn:ietf:params:oauth:token-type:saml2 per le asserzioni SAML

  • EXTERNAL_SUBJECT_TOKEN: il token emesso dall'IdP che rappresenta l'identità dell'entità per cui viene richiesto il token di accesso. Nota: se utilizzi OIDC, il token è in formato JWT.

  • BILLING_PROJECT_NUMBER: il numero o l'ID progetto utilizzato per la quota e la fatturazione. Il principale deve disporre dell'autorizzazione serviceusage.services.use su questo progetto.

La risposta è simile alla seguente:

{
  "access_token": "ya29.dr.AaT61Tc6Ntv1ktbGkaQ9U_MQfiQw...",
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "token_type": "Bearer",
  "expires_in": 3600
}

Gestire le sessioni utilizzando gcloud CLI

I token Google Cloud temporanei che gcloud ottiene dall'endpoint Security Token Service scadono dopo un intervallo di tempo specificato. Quando il token sta per scadere, gcloud controlla il file delle credenziali che hai fornito e la validità delle credenziali che hai ricevuto dalla tua IdP. Se le tue credenziali sono ancora valide, gcloud procede a ottenere in modo trasparente un nuovo token di accesso Google Cloud e la sessione corrente viene eseguita senza interruzione.

Se le credenziali sono scadute, non vengono emessi nuovi token Google Cloud e tutte le chiamate effettuate con queste credenziali non vanno a buon fine. A questo punto, devi eseguire nuovamente l'autenticazione.

Puoi terminare la sessione eseguendo il seguente comando:

gcloud auth revoke

gcloud supporta più sessioni utente. Per ottenere l'elenco delle sessioni, inclusa quella attiva al momento, esegui il seguente comando:

gcloud auth list

L'output del comando è simile al seguente:

Credentialed Accounts
ACTIVE    ACCOUNT
*         bola@example.com
          principal://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/subject/kalani@example.com

Per passare a un'altra sessione e impostarla come attiva, esegui il seguente comando:

gcloud config set account principal://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/subject/SUBJECT_ID

Passaggi successivi