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

Questa guida mostra come utilizzare un provider di pool di identità e 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à per la forza lavoro e a cui ti è stato concesso l'accesso.

Per ottenere i token di breve durata:

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

Prima di iniziare

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

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

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

  4. Abilita le API IAM and Security Token Service.

    Abilita le API

  5. Installa Google Cloud CLI, quindi initialize eseguendo questo comando: 

    gcloud init

Scambiare le credenziali esterne per un token di accesso di Google Cloud

Questa sezione mostra come utilizzare il servizio token di sicurezza per scambiare le credenziali esterne con un token di accesso che concede l'accesso a Google Cloud. Per farlo, puoi utilizzare gcloud CLI, l'API REST e le librerie client di Cloud, come descritto più avanti in questa guida.

Se hai bisogno di un accesso di lunga durata, puoi configurare un processo a lunga esecuzione per aggiornare continuamente le credenziali su quella macchina. In alternativa, puoi eseguire un server locale in background con un endpoint che restituisca 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. Per farlo, crea un file di configurazione dell'accesso e fai riferimento al file nelle chiamate a gcloud auth login oppure 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 questo 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 forza lavoro
  • PROVIDER_ID: l'ID provider
  • LOGIN_CONFIG_FILE: un percorso al file di configurazione da te specificato, ad esempio login.json

Il file contiene gli endpoint utilizzati da gcloud CLI per abilitare il flusso di autenticazione basato su browser e impostare il pubblico sul provider che hai creato in precedenza in questa guida. 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",
}

Accedi utilizzando l'autenticazione basata sul browser

Per eseguire l'autenticazione mediante l'autenticazione dell'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 hai attivato il file di configurazione con gcloud config set auth/LOGIN_CONFIG_FILE, gcloud CLI utilizza automaticamente il file di configurazione: 

    gcloud auth login

  • Per accedere specificando la posizione del file di configurazione, esegui questo 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.

Disattiva l'accesso basato su browser

Per non utilizzare più il file di configurazione dell'accesso:

  • Se hai utilizzato il flag --activate quando hai creato il file di configurazione o hai attivato il file di configurazione con gcloud config set auth/LOGIN_CONFIG_FILE, devi eseguire questo comando per annullarne l'impostazione: 

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

Utilizza i file di configurazione per l'accesso

In alternativa all'accesso basato su browser, questa sezione mostra diversi modi per utilizzare i file di configurazione delle credenziali per fornire l'accesso ad azioni Google Cloud autenticate. Per impostare i file di configurazione, non è necessario aver effettuato l'accesso a gcloud CLI.

La modalità di impostazione del file di configurazione varia a seconda che l'IdP utilizzi OIDC o SAML.

OIDC

Puoi reperire le credenziali utilizzate per impostare 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 sia vecchio di un'ora.

Per generare il file di configurazione con una credenziale proveniente da file, esegui questo 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 credenziali IdP OIDC
  • WORKFORCE_POOL_USER_PROJECT: il numero o l'ID del progetto associato al progetto utente dei pool di forza lavoro.

L'entità deve avere l'autorizzazione serviceusage.services.use in questo progetto.

L'esecuzione del comando produce un file di configurazione IdP 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 formato di testo normale o JSON.

Per generare il file di configurazione con una credenziale generata dall'URL, esegui questo 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-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 di progetto utilizzato per la quota e la fatturazione. L'entità deve avere serviceusage.services.use permission in questo progetto.

L'esecuzione del comando produce un file di configurazione IdP 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 basate su eseguibili non interattive

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 corretta, ad eccezione di expiration_time. Il campo expiration_time è obbligatorio solo quando è stato specificato un file di output nella configurazione delle credenziali.

L'eseguibile deve segnalare eventuali errori in 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. Il codice e i campi dei messaggi vengono utilizzati dalle librerie client per segnalare 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 essere chiuso con il codice di uscita 0 e la risposta deve contenere i seguenti campi:

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

    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 del 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 data di scadenza del token OIDC di terze parti in secondi (tempo epoch di Unix)

  • code: la stringa del codice di errore

  • message: il messaggio di errore

Quando viene eseguito l'eseguibile, le librerie client compilano le seguenti variabili di ambiente:

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

Queste variabili di ambiente possono essere utilizzate dall'eseguibile per evitare l'hardcoded di questi valori.

Per abilitare questo metodo di origine 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 generata da eseguibili, esegui questo 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 oggetto, ad esempio un token ID OIDC, nel seguente formato: --executable-command="/path/to/command --foo=bar".
  • EXECUTABLE_TIMEOUT: (facoltativo) una durata, in millisecondi, di attesa dell'esecuzione dell'eseguibile (il valore predefinito è 30 secondi).
  • EXECUTABLE_OUTPUT_FILE: (facoltativo) un percorso file delle credenziali di terze parti generate dall'eseguibile. Ciò è utile per memorizzare le credenziali nella cache. Le librerie di autenticazione controllano il percorso prima di eseguire l'eseguibile.
  • WORKFORCE_POOL_USER_PROJECT: il numero o l'ID del progetto utilizzato per la quota e la fatturazione. L'entità deve avere l'autorizzazione serviceusage.services.use impostata in questo progetto.

L'esecuzione del comando produce un file di configurazione IdP 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 basate su eseguibili

Puoi fornire un file eseguibile che interagisce con l'utente tramite stdin e stdout. Se l'utente esegue l'accesso correttamente, l'eseguibile scrive una [credenziale valida 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 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, ad 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 si restituisce 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 generano l'errore.

Dopo l'esecuzione riuscita, il comando restituisce gli stessi campi a prescindere dal risultato di credenziali provenienti da eseguibili interattive o non interattive riportate sopra.

Le variabili di ambiente sono anche le stesse delle normali credenziali provenienti da eseguibili.

Per generare una credenziale interattiva generata da eseguibili, aggiungi i parametri --executable-interactive-timeout-millis e --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 oggetto, formattato come segue: --executable-command="/path/to/command --arg1=val1 --arg2=val2"
  • EXECUTABLE_INTERACTIVE_TIMEOUT: una durata in millisecondi di attesa dell'esecuzione dell'eseguibile.
  • EXECUTABLE_OUTPUT_FILE: un percorso file delle credenziali di terze parti generate dall'eseguibile. Questo percorso è utile per memorizzare le credenziali nella cache. Le librerie di autenticazione controllano il percorso prima di eseguire l'eseguibile.
  • WORKFORCE_POOL_USER_PROJECT: il numero o l'ID del progetto utilizzato per la quota e la fatturazione. L'entità deve avere l'autorizzazione serviceusage.services.use in questo progetto.

L'esecuzione del comando produce un file di configurazione IdP 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 reperire le credenziali utilizzate per impostare il file di configurazione dalle seguenti origini:

Credenziali basate su file

Le asserzioni vengono caricate da un file. Un altro processo deve aggiornare questo file con una nuova asserzione SAML con codifica Base64 prima della scadenza della precedente. Ad esempio, se l'asserzione ha una durata di un'ora, devi aggiornare il file prima che sia vecchio di 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 del 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 un'asserzione SAML con codifica Base64 o un JSON contenente un'asserzione SAML con codifica Base64.

Per utilizzare le credenziali provenienti dall'URL, usa 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 del progetto utilizzato per la quota e la fatturazione. L'entità deve avere serviceusage.services.use permission in questo progetto.

Credenziali provenienti da eseguibili

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

{
  "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 corretta, ad eccezione di expiration_time. Il campo expiration_time è obbligatorio solo quando viene specificato un file di output nella configurazione delle credenziali.

Se si verifica un errore, deve essere indicato dall'eseguibile nel seguente formato JSON per stdout: 

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

Questi campi sono tutti obbligatori per una risposta di errore. Il codice e i campi dei messaggi vengono utilizzati dalle librerie client per segnalare 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 essere chiuso con il codice di uscita 0 e la risposta deve contenere i seguenti campi:

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

    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 del soggetto di terze parti, che deve essere urn:ietf:params:oauth:token-type:saml2

  • saml_response: la risposta SAML di terze parti

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

  • code: la stringa del codice di errore

  • message: il messaggio di errore

Quando viene eseguito l'eseguibile, le librerie client compilano le seguenti variabili di ambiente:

  • GOOGLE_EXTERNAL_ACCOUNT_AUDIENCE: il campo relativo al pubblico dalla configurazione delle credenziali. Sempre presente.
  • GOOGLE_EXTERNAL_ACCOUNT_TOKEN_TYPE: il tipo di token oggetto previsto. Sempre presente.
  • GOOGLE_EXTERNAL_ACCOUNT_OUTPUT_FILE: la posizione del file di output dalla configurazione delle credenziali. Presente solo quando è specificato nella configurazione delle credenziali.

Per abilitare questo metodo di origine 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 generata da eseguibili, esegui questo 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 oggetto, nel seguente formato: --executable-command="/path/to/command --foo=bar".
  • EXECUTABLE_TIMEOUT: (facoltativo) la durata in millisecondi di attesa per l'esecuzione dell'eseguibile (il valore predefinito è 30 secondi).
  • EXECUTABLE_OUTPUT_FILE: (facoltativo) il percorso file delle credenziali 3PI generate dall'eseguibile. È utile per memorizzare le credenziali nella cache. Le librerie di autenticazione ne verificano l'esistenza prima di eseguire l'eseguibile.
  • WORKFORCE_POOL_USER_PROJECT: il numero di progetto utilizzato per la quota e la fatturazione. L'entità deve avere l'autorizzazione serviceusage.services.use in questo progetto.

L'esecuzione del comando produce un file di configurazione 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 origini eseguibili per la modalità interattiva di gcloud

Un 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 segnala 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 corretta, ad eccezione di expiration_time. L'assenza di expiration_time verrà considerata come l'indicatore dell'esecuzione dell'eseguibile in qualsiasi modo.

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. Il codice e i campi dei messaggi vengono utilizzati dalle librerie client per segnalare l'errore appropriato.

I campi di restituzione del comando per un'esecuzione riuscita sono esattamente gli stessi dei normali risultati di credenziali provenienti da eseguibili riportati sopra.

Le variabili di ambiente sono anche le stesse delle normali credenziali provenienti da eseguibili.

Per generare una credenziale interattiva generata da 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 oggetto, formattato come segue: --executable-command="/path/to/command --foo=bar").
  • EXECUTABLE_INTERACTIVE_TIMEOUT: una durata in millisecondi di attesa dell'esecuzione dell'eseguibile.
  • EXECUTABLE_OUTPUT_FILE: un percorso file delle credenziali di terze parti generate dall'eseguibile. Ciò è utile per memorizzare le credenziali nella cache. Le librerie di autenticazione controllano il percorso prima di eseguire l'eseguibile.
  • WORKFORCE_POOL_USER_PROJECT: il numero o l'ID del progetto utilizzato per la quota e la fatturazione. L'entità ha impostato l'autorizzazione serviceusage.services.use in questo progetto.

L'esecuzione del comando produce un file di configurazione 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 questo comando:

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

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

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

Ora puoi eseguire i comandi gcloud utilizzando gcloud CLI.

Utilizzare le librerie client di Google Cloud

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

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

Per utilizzare le librerie client con questi servizi o linguaggi, procedi nel seguente modo:

bq

Per eseguire l'autenticazione con la federazione delle identità per la 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 per la federazione delle identità per la forza lavoro in bq è disponibile nella versione 390.0.0 e versioni 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 mediante l'utilizzo di un oggetto ChannelCredentials, creato chiamando grpc::GoogleDefaultCredentials(). Per inizializzare questa credenziale, devi creare le librerie client con la versione 1.42.0 o successiva di gRPC.

La libreria client di Cloud Storage per C++ utilizza l'API REST, non gRPC, quindi non supporta la federazione delle identità per la forza lavoro.

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 eseguire l'autenticazione con la federazione delle identità per la 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 versioni successive di Google Cloud CLI.

Go

Le librerie client di Go supportano la federazione delle identità per la forza lavoro se utilizzano la versione v0.0.0-20211005180243-6b3c2da341f1 o successiva 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)
}

gsutil

Per eseguire l'autenticazione con la federazione delle identità per la forza lavoro, utilizza uno dei seguenti metodi:

Quando utilizzi gsutil insieme a gcloud, accedi normalmente:

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

Quando utilizzi gsutil come applicazione a riga di comando autonoma, modifica il file .boto in modo da includere la seguente sezione:

[Credentials]
gs_external_account_file = FILEPATH

In entrambi i casi, FILEPATH è il percorso del file di configurazione delle credenziali.

Il supporto per la federazione delle identità per la forza lavoro in gsutil è disponibile nella versione 379.0.0 e versioni successive di Google Cloud CLI.

Java

Le librerie client per Java supportano la federazione delle identità per la forza lavoro se utilizzano la versione 1.2.0 o successiva dell'artefatto 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à per la forza lavoro. Devi utilizzare la versione 7.10.0 o successive del pacchetto google-auth-library. A differenza dei pool di identità per i carichi di lavoro, 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 documento README per il 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à per la 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 rilevare automaticamente questo elemento. Puoi passarlo esplicitamente quando utilizzi un'istanza di servizio (come nell'esempio del client di archiviazione) o impostare tramite la variabile di ambiente GOOGLE_CLOUD_PROJECT.

Per maggiori dettagli, vedi 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 di 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 provider che emette il token oggetto.
  • PROVIDER_ID: l'ID provider

  • SUBJECT_TOKEN_TYPE: impostato su uno dei seguenti valori:

    • 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 del progetto utilizzato per la quota e la fatturazione. L'entità deve disporre dell'autorizzazione serviceusage.services.use in 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
}

Gestisci le sessioni utilizzando gcloud CLI

I token temporanei di Google Cloud che gcloud riceve dall'endpoint di 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 dall'IdP. Se le tue credenziali sono ancora valide, gcloud procede all'ottenimento di un nuovo token di accesso a Google Cloud in modo trasparente e la sessione corrente viene eseguita senza interruzioni.

Se le tue credenziali sono scadute, non verranno emessi nuovi token Google Cloud e tutte le chiamate che effettui con queste credenziali non andranno a buon fine. A questo punto, devi eseguire nuovamente l'autenticazione.

Puoi terminare la sessione eseguendo questo comando:

gcloud auth revoke

gcloud supporta più sessioni utente. Per ottenere l'elenco delle sessioni, inclusa quella attualmente attiva, esegui questo 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 questo comando:

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

Passaggi successivi