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

Puoi utilizzare un pool di identità per la forza lavoro e un provider di pool di identità per la forza lavoro per ottenere token di breve durata da Security Token Service o dall'API Cloud OAuth. Questi token ti consentono di accedere alle risorse Google Cloud che supportano la federazione delle identità per la forza lavoro e per le quali disponi delle autorizzazioni.

Puoi utilizzare i metodi descritti in questo documento su macchine headless.

Per ottenere token di breve durata, segui questa procedura generale:

  1. Ottieni una credenziale dal provider di identità (IdP) attendibile o reindirizza gli utenti all'endpoint di autorizzazione (https://auth.cloud.google/authorize) per accedere con l'IdP e ottenere un codice di autorizzazione.
  2. Scambia la credenziale o il codice di autorizzazione con un token di Security Token Service o dell'API Cloud OAuth.

Prima di iniziare

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

    Prendi nota dell'ID pool di identità della forza lavoro e dell'ID provider del pool di identità della forza lavoro.

  2. Assicurati che ogni entità per cui vengono scambiati token utilizzando Security Token Service disponga 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).

  3. Abilita le API IAM, Security Token Service e Cloud OAuth API, se non sono già abilitate.

    Ruoli richiesti per abilitare le API

    Per abilitare le API, devi disporre dell'autorizzazione serviceusage.services.enable. Se hai creato il progetto, probabilmente hai già questa autorizzazione tramite il ruolo Proprietario (roles/owner). In caso contrario, puoi ottenere questa autorizzazione tramite il ruolo Amministratore Service Usage (roles/serviceusage.serviceUsageAdmin). Scopri come concedere i ruoli.

    Abilita le API

  4. Installa Google Cloud CLI. Dopo l'installazione, inizializza Google Cloud CLI eseguendo il comando seguente: 

    gcloud init

    Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.

Scambia le credenziali esterne con un token di accesso Google Cloud

Questa sezione mostra come utilizzare Security Token Service o l'API Cloud OAuth per scambiare le tue credenziali esterne con un token di accesso che concede l'accesso a Google Cloud. Puoi farlo utilizzando gcloud CLI, l'API REST e le librerie client di Cloud, come descritto più avanti in questo documento.

Per istruzioni su come ottenere un codice di autorizzazione dall'endpoint di autorizzazione (https://auth.cloud.google/authorize) e scambiare codici di autorizzazione e token di aggiornamento utilizzando l'API Cloud OAuth, consulta Scambia token con l'API Cloud OAuth.

Se hai bisogno di un accesso di lunga durata, puoi configurare un processo di lunga durata per aggiornare continuamente le credenziali su quella 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. Per farlo, crea un file di configurazione di accesso e poi fai riferimento al file nelle chiamate a gcloud auth login o attiva il file in modo che venga utilizzato per impostazione predefinita.

Crea il file di configurazione di accesso

Esegui questo comando per creare un file di configurazione di accesso:

Linux e macOS

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

Windows (PowerShell)

gcloud iam workforce-pools create-login-config `
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID `
    --output-file=LOGIN_CONFIG_PATH

Sostituisci quanto segue:

  • WORKFORCE_POOL_ID: l'ID del pool di federazione delle identità per la forza lavoro.
  • WORKFORCE_PROVIDER_ID: l'ID provider della federazione delle identità per la forza lavoro.
  • LOGIN_CONFIG_PATH: il percorso in cui scrivere il file di configurazione di accesso. Ad esempio, login-config.json.

Il file di configurazione dell'accesso contiene gli endpoint utilizzati da gcloud CLI per abilitare il flusso di autenticazione basato su browser e impostare il pubblico sull'IdP configurato nel provider del pool di identità per la forza lavoro. Il file non contiene informazioni riservate.

I contenuti del file di configurazione di accesso sono simili ai seguenti:

{
  "universe_domain": "googleapis.com",
  "universe_cloud_web_domain": "cloud.google",
  "type": "external_account_authorized_user_login_config",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_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 su browser

Indica il file di configurazione di accesso con una variabile di ambiente, una proprietà nella configurazione gcloud CLI attiva o utilizzalo direttamente con il comando gcloud auth login:

Variabile di ambiente

Per utilizzare il file di configurazione di accesso con una variabile di ambiente, completa le seguenti istruzioni:

  1. Imposta la variabile di ambiente CLOUDSDK_AUTH_LOGIN_CONFIG_FILE sul percorso del file di configurazione di accesso.

  2. Esegui questo comando:

    gcloud auth login
  3. gcloud CLI fa riferimento alla variabile di ambiente per trovare il file di configurazione di accesso, quindi avvia il processo di autenticazione. Segui il flusso basato su browser per autenticare e autorizzare gcloud CLI ad accedere alle risorse per tuo conto per i comandi futuri.

Per interrompere l'utilizzo del file di configurazione di accesso per i comandi gcloud auth login, cancella la variabile di ambiente CLOUDSDK_AUTH_LOGIN_CONFIG_FILE.

Configurazione di gcloud CLI

Per utilizzare il file di configurazione di accesso con una proprietà di configurazione di gcloud CLI, completa le seguenti istruzioni:

  1. Imposta la proprietà auth/login_config_file della configurazione gcloud CLI attiva sul percorso del file di configurazione di accesso con il seguente comando: 

    gcloud config set auth/login_config_file LOGIN_CONFIG_PATH

  2. Esegui questo comando:

    gcloud auth login
  3. gcloud CLI fa riferimento alla proprietà di configurazione per trovare il file di configurazione di accesso, quindi avvia il processo di autenticazione. Segui il flusso basato su browser per autenticare e autorizzare gcloud CLI ad accedere alle risorse per tuo conto per i comandi futuri.

Per interrompere l'utilizzo del file di configurazione di accesso per i comandi gcloud auth login, annulla l'impostazione della proprietà con il seguente comando: 

gcloud config unset auth/login_config_file

gcloud auth login

Per utilizzare il file di configurazione di accesso direttamente con il comando gcloud auth login, completa le seguenti istruzioni:

  • Se hai utilizzato il flag --activate durante la creazione del file di configurazione di accesso, esegui questo comando: 

    gcloud auth login

  • Se non hai utilizzato il flag --activate durante la creazione del file di configurazione di accesso, esegui questo comando:

    Linux e macOS

    gcloud auth login \
    --login-config=LOGIN_CONFIG_PATH

    Windows (PowerShell)

    gcloud auth login `
    --login-config=LOGIN_CONFIG_PATH

    Sostituisci LOGIN_CONFIG_PATH con il percorso del file di configurazione di accesso.

Il comando gcloud auth login memorizza le credenziali di accesso nella tua home directory. L'entità autenticata diventa l'entità attiva nella configurazione dell'interfaccia alla gcloud CLI attiva. A meno che non venga eseguito l'override, gcloud CLI utilizza queste credenziali archiviate per accedere a Google Cloud.

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 alle azioniGoogle Cloud autenticate. Per configurare i file di configurazione, non è necessario aver eseguito l'accesso a gcloud CLI.

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

OIDC

Puoi ottenere le credenziali che utilizzi per impostare il file di configurazione dalle seguenti fonti:

Credenziali provenienti da file

Quando utilizzi le credenziali basate su file, i token vengono caricati da un file. Un altro processo deve aggiornare questo file con un nuovo token OIDC prima che il token precedente scada. Ad esempio, se il token ha una durata di un'ora, devi aggiornare il file prima che sia trascorsa un'ora.

Per generare il file di configurazione con una credenziale proveniente da un file, esegui il seguente comando:

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_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 identità della forza lavoro
  • WORKFORCE_PROVIDER_ID: l'ID provider del pool di identità della forza lavoro
  • PATH_TO_OIDC_TOKEN: il percorso del file delle credenziali IdP OIDC
  • WORKFORCE_POOL_USER_PROJECT: il numero o l'ID progetto associato al progetto utente dei pool di forza lavoro.

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

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

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_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 provenienti da URL

Quando utilizzi le credenziali provenienti da un 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 testo normale o JSON.

Per generare un file di configurazione con una credenziale proveniente da un URL, esegui il comando seguente:

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_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 identità della forza lavoro.
  • WORKFORCE_PROVIDER_ID: l'ID provider del pool di identità della forza lavoro.
  • 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 disporre dell'autorizzazione serviceusage.services.use per questo progetto.

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

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_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 provenienti da un eseguibile

Quando utilizzi credenziali non interattive provenienti da un 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 corretta, ad eccezione di expiration_time. Il campo expiration_time è obbligatorio solo se è stato specificato un file di output nella configurazione delle credenziali.

L'eseguibile deve mostrare 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 code e message vengono utilizzati dalle librerie client quando generano 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 terminare con il codice di uscita 0 e la risposta deve contenere i seguenti campi:

    • token_type: id_token
    • Campo expiration_time, se nel file di 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 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 e l'ora di scadenza del token OIDC di terze parti in secondi (epoca di Unix)

  • code: la stringa del codice di errore

  • message: il messaggio di errore

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

  • GOOGLE_EXTERNAL_ACCOUNT_AUDIENCE: il campo audience della configurazione delle credenziali. Questa variabile è sempre impostata.
  • GOOGLE_EXTERNAL_ACCOUNT_TOKEN_TYPE: il tipo di token soggetto previsto. Questa variabile è sempre impostata.
  • GOOGLE_EXTERNAL_ACCOUNT_OUTPUT_FILE: la posizione del file di output dalla configurazione delle credenziali. Questa variabile è presente solo se è specificata nella configurazione delle credenziali.

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

Per abilitare questo metodo di approvvigionamento 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 proveniente da un eseguibile, esegui questo comando:

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_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 identità della forza lavoro.
  • WORKFORCE_PROVIDER_ID: l'ID provider del pool di identità della forza lavoro.
  • EXECUTABLE_COMMAND: il comando completo, inclusi gli argomenti, da eseguire per recuperare il token del soggetto, 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 per l'esecuzione dell'eseguibile (il valore predefinito è 30 secondi).
  • EXECUTABLE_OUTPUT_FILE: (Facoltativo) Un percorso alle credenziali di terze parti generate dall'eseguibile. Questa opzione è utile per memorizzare nella cache le credenziali. Le librerie di autenticazione 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 disporre del serviceusage.services.use set di autorizzazioni impostato su questo progetto.

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

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_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 provenienti da un eseguibile

Quando utilizzi credenziali interattive provenienti da un eseguibile, puoi fornire un 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 richiesti 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 60000 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 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.

In caso di esecuzione riuscita, il comando restituisce gli stessi campi per le credenziali interattive e non interattive provenienti dall'eseguibile.

Le variabili di ambiente sono le stesse anche per le credenziali interattive e non interattive provenienti da un eseguibile.

Per generare una credenziale interattiva proveniente da un eseguibile, 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/WORKFORCE_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 identità della forza lavoro.
  • WORKFORCE_PROVIDER_ID: l'ID provider del pool di identità della forza lavoro.
  • EXECUTABLE_COMMAND: il comando completo, inclusi gli argomenti, da eseguire per recuperare il token dell'oggetto, formattato come segue: --executable-command="/path/to/command --arg1=val1 --arg2=val2"
  • EXECUTABLE_INTERACTIVE_TIMEOUT: un periodo di tempo, in millisecondi, di attesa per l'esecuzione dell'eseguibile.
  • EXECUTABLE_OUTPUT_FILE: un percorso alle credenziali di terze parti generate dall'eseguibile. Questo percorso è utile per memorizzare nella cache le credenziali. Le librerie di autenticazione 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 disporre dell'autorizzazione serviceusage.services.use per questo progetto.

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

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_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",
    }
  }
}

Il campo timeout_millis viene restituito perché un eseguibile interattivo può anche essere eseguito in modalità non interattiva, in alcuni casi. In modalità interattiva, il comando restituisce un timeout predefinito.

SAML

Puoi ottenere le credenziali che utilizzi per impostare il file di configurazione dalle seguenti fonti:

Credenziali provenienti da file

Le asserzioni vengono caricate da un file. Un altro processo deve aggiornare questo file con una nuova asserzione SAML con codifica base64 prima che l'asserzione precedente scada. Ad esempio, se l'asserzione ha una durata di un'ora, devi aggiornare il file prima che sia trascorsa un'ora.

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_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 identità della forza lavoro.
  • WORKFORCE_PROVIDER_ID: l'ID provider del pool di identità della forza lavoro.
  • 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 disporre dell'autorizzazione serviceusage.services.use per questo progetto.

Credenziali provenienti da 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 [codificata in base64](https://toolbox.googleapps.com/apps/encode_decode/) o un JSON contenente un'asserzione SAML codificata in base64. Per utilizzare le credenziali provenienti da un URL, utilizza il flag `--credential-source-url`: ```sh gcloud iam workforce-pools create-cred-config \ locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_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 identità della forza lavoro. * WORKFORCE_PROVIDER_ID: l'ID provider del pool di identità della forza lavoro. * 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 disporre dell'autorizzazione "serviceusage.services.use" per 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 a 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 nella configurazione delle credenziali è specificato un file di output.

Se si verifica un errore, l'eseguibile deve visualizzarlo nel seguente formato JSON in stdout:

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

Questi campi sono tutti obbligatori per una risposta di errore. I campi code e message vengono utilizzati dalle librerie client quando generano 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 terminare con il codice di uscita 0 e la risposta deve contenere i seguenti campi:

    • token_type: saml_response
    • Campo expiration_time, se nel file di 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 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: la data e l'ora di scadenza della risposta SAML di terze parti in secondi (epoca di Unix)

  • code: la stringa del codice di errore

  • message: il messaggio di errore

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

  • GOOGLE_EXTERNAL_ACCOUNT_AUDIENCE: il campo audience della configurazione delle credenziali. Questa variabile è sempre impostata.
  • GOOGLE_EXTERNAL_ACCOUNT_TOKEN_TYPE: il tipo di token soggetto previsto. Questa variabile è sempre impostata.
  • GOOGLE_EXTERNAL_ACCOUNT_OUTPUT_FILE: la posizione del file di output dalla configurazione delle credenziali. Questa variabile è presente solo se è specificata nella configurazione delle credenziali.

Per abilitare questo metodo di approvvigionamento 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 proveniente da un eseguibile, esegui questo comando:

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_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 identità della forza lavoro.
  • WORKFORCE_PROVIDER_ID: l'ID provider del pool di identità della forza lavoro.
  • EXECUTABLE_COMMAND: il comando completo, inclusi gli argomenti, da eseguire per recuperare il token dell'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 delle credenziali di identità di terze parti (3PI) generate dall'eseguibile. Questa opzione è utile per memorizzare nella cache le credenziali. Le librerie di autorizzazione 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 disporre dell'autorizzazione serviceusage.services.use per questo progetto.

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

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_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

Quando utilizzi le credenziali di origine eseguibile per la modalità interattiva di gcloud, un eseguibile interagisce con l'utente tramite l'interfaccia a 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 corretta, ad eccezione di expiration_time. Se expiration_time viene omesso, l'eseguibile viene comunque eseguito.

L'eseguibile deve mostrare eventuali errori alla executable-output-file nel seguente formato JSON. Quando l'eseguibile segnala un errore, questi campi sono tutti obbligatori. I campi code e message vengono utilizzati dalle librerie client quando generano l'errore appropriato.

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

L'esecuzione corretta del comando restituisce gli stessi campi delle credenziali non interattive provenienti da un eseguibile.

Anche le variabili di ambiente sono le stesse delle credenziali provenienti da un eseguibile non interattivo.

Per generare una credenziale interattiva proveniente da un eseguibile, aggiungi il parametro --executable-interactive-timeout-millis.

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_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 identità della forza lavoro.
  • WORKFORCE_PROVIDER_ID: l'ID provider del pool di identità della forza lavoro.
  • EXECUTABLE_COMMAND: il comando completo, inclusi gli argomenti, da eseguire per recuperare il token dell'oggetto, formattato come segue: --executable-command="/path/to/command --foo=bar").
  • EXECUTABLE_INTERACTIVE_TIMEOUT: un periodo di tempo, in millisecondi, di attesa per l'esecuzione dell'eseguibile.
  • EXECUTABLE_OUTPUT_FILE: un percorso alle credenziali di terze parti generate dall'eseguibile. Questa opzione è utile per memorizzare nella cache le credenziali. Le librerie di autenticazione 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 disporre dell'autorizzazione serviceusage.services.use per questo progetto.

L'esecuzione del comando genera 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>WORKFORCE_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 né gcloud CLI né lo strumento a riga di comando bq supportano i tipi di credenziali provenienti da eseguibili.

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

Ora puoi eseguire i comandi gcloud utilizzando gcloud CLI.

Utilizza le librerie client 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 autonomamente il processo di scambio dei token.

Le librerie clientGoogle Cloud supportano i pool di forza lavoro nei seguenti linguaggi: Node.js, Java, Python, Go e C++ (gRPC).

Per utilizzare le librerie client con questi servizi o linguaggi, segui questi passaggi:

Strumento bq

Per eseguire l'autenticazione utilizzando 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 nello strumento bq è disponibile nella versione 390.0.0 e successive di Google Cloud CLI.

C++

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

Le librerie client Cloud Storage per C++ utilizzano l'API REST, non gRPC, quindi non supportano la federazione delle identità della 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 utilizzando la federazione delle identità per la forza lavoro, utilizza il comando gcloud auth login:

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 la forza lavoro in gcloud CLI è disponibile nella versione 392.0.0 e successive di Google Cloud CLI.

Vai

Le librerie client Cloud per Go supportano la federazione delle identità per la forza lavoro quando utilizzi 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 di Cloud per Java supportano la federazione delle identità per la forza lavoro se utilizzi la versione 1.2.0 o successive 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 Cloud per Node.js supportano la federazione delle identità per la forza lavoro se utilizzi la versione 7.10.0 o successive del pacchetto google-auth-library.

A differenza dei pool di identità del workload, i pool di identità della 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 saperne di più, consulta il file 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 di Cloud per Python supportano la federazione delle identità per la forza lavoro se utilizzi 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)

Nel codice di esempio, il valore project può essere None se la libreria non è in grado di rilevare automaticamente l'ID progetto. Puoi passare l'ID progetto in modo esplicito quando utilizzi un'istanza di servizio, come nell'esempio del client di archiviazione, o impostare l'ID progetto 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

Per ottenere un codice di autorizzazione dall'endpoint di autorizzazione (https://auth.cloud.google/authorize) e scambiare i codici di autorizzazione o i token di aggiornamento utilizzando l'API Cloud OAuth (cloudoauth.googleapis.com), consulta Scambia i token con l'API Cloud OAuth.

Puoi anche chiamare l'API Security Token Service Google Cloud per scambiare le tue credenziali esterne con token di accesso Google Cloud eseguendo il seguente comando:

curl https://sts.googleapis.com/v1/token \
    --data-urlencode "audience=//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_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 dell'oggetto.
  • WORKFORCE_POOL_ID: l'ID del pool di identità della forza lavoro
  • WORKFORCE_PROVIDER_ID: l'ID provider del pool di identità della forza lavoro

  • SUBJECT_TOKEN_TYPE: imposta 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.

    Se hai configurato un provider OIDC, il token deve essere in formato JWT.

  • BILLING_PROJECT_NUMBER: il numero o l'ID progetto utilizzato per la quota e la fatturazione. L'entità deve disporre dell'autorizzazione serviceusage.services.use per 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 Google Cloud temporanei che gcloud CLI ottiene dall'endpoint di Security Token Service scadono dopo un intervallo di tempo specificato. Quando il token sta per scadere, gcloud CLI esamina il file delle credenziali che hai fornito e la validità delle credenziali che hai ricevuto dal tuo IdP. Se le tue credenziali sono ancora valide, l'gcloud CLI procede all'acquisizione trasparente di un nuovo token di accessoGoogle Cloud e la sessione corrente viene eseguita senza interruzioni.

Se le tue 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 ripetere l'autenticazione.

Puoi terminare la sessione eseguendo questo comando:

gcloud auth revoke
Per revocare tutte le sessioni attive e le credenziali di breve durata per un soggetto del pool di forza lavoro in tutti i client come amministratore, segui le istruzioni riportate in Revoca le sessioni utente di Workforce Identity Federation.

gcloud supporta più sessioni utente. Per visualizzare l'elenco delle sessioni, inclusa quella attualmente attiva, esegui questo comando:

gcloud auth list

L'output di questo 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