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

Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Questa guida mostra come utilizzare un pool della federazione delle identità della forza lavoro e un provider del pool della federazione delle 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.

Otterrai token di breve durata seguendo questa procedura:

  1. Ottieni una credenziale dal provider di identità attendibile.
  2. Scambia le credenziali di un token dal Security Token Service.
  3. Utilizzare il token del Security Token Service per impersonare un account di servizio e ottenere un token di accesso di breve durata.

Prima di iniziare

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

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

  3. Assicurati di avere l'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 inizializzalo eseguendo questo comando: 

    gcloud init

Scambia credenziali esterne con un token di accesso a 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. Per farlo, utilizza l'interfaccia a riga di comando gcloud, 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 restituisce le credenziali.

Accesso basato su browser con gcloud CLI

Questa sezione descrive come configurare l'interfaccia a riga di comando gcloud per utilizzare un flusso di accesso basato sul browser. A questo scopo, crea un file di configurazione di accesso, quindi 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 dell'accesso, esegui questo comando:

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 dall'interfaccia a riga di comando gcloud per abilitare il flusso di autenticazione basato sul 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",
}

Crea il file di configurazione dell'accesso e attivalo

Per creare il file di configurazione dell'accesso interattivo e attivarlo come file predefinito per l'interfaccia a riga di comando gcloud da utilizzare quando esegui gcloud auth login, procedi come segue: 

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

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:

  • Per accedere specificando la posizione del file di configurazione, esegui il comando seguente: 
        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.
  • Se non viene specificato nessuno dei metodi precedenti, gcloud CLI tenta di leggere la configurazione dalla proprietà auth/LOGIN_CONFIG_FILE dell'interfaccia a riga di comando gcloud. Per impostare la proprietà sul percorso di configurazione, esegui il comando seguente: 
        gcloud config set auth/login_config_file LOGIN_CONFIG_FILE

Disattiva l'accesso basato su browser

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

  • Se hai utilizzato il flag --activate durante la creazione del file di configurazione o se hai attivato il file di configurazione con gcloud config set auth/LOGIN_CONFIG_FILE, devi eseguire questo comando per annullare l'impostazione: 
    •     gcloud config unset auth/login_config_file
  • Cancella la variabile di ambiente CLOUDSDK_AUTH_LOGIN_CONFIG_FILE, se impostata.

Genera un file di configurazione per l'accesso non interattivo

Genera un file di configurazione come descritto di seguito. Questo comando non richiede l'accesso.

OIDC

Credenziali provenienti da file: i token vengono caricati da un file. Un altro processo deve aggiornare questo file con un nuovo token OIDC prima che il vecchio token scada. Ad esempio, se il token ha una durata di un'ora, devi aggiornare il file prima che abbia un'ora.

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

L'entità deve avere l'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/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 dall'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 il file di configurazione con una credenziale generata da un 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 del provider.
  • URL_TO_RETURN_OIDC_ID_TOKEN: l'URL da richiamare per recuperare le credenziali OIDC, come 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 genera 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 non interattive e provenienti da fonti eseguibili: i token vengono caricati da un eseguibile locale. L'eseguibile deve fornire a stdout un token ID OIDC valido e non scaduto in formato JSON:

{
  "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 visualizzare gli errori in stdout nel seguente formato JSON:

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

Questi campi sono tutti obbligatori per la risposta agli errori. I campi Codice e Messaggio vengono utilizzati dalle librerie client quando generano l'errore appropriato.

Il comando può restituire i seguenti campi:

  • version: 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 e uno tra saml_response o 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 dell'oggetto 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 di Unix epoch)

  • code: la stringa del codice di errore

  • message: il messaggio di errore

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

  • GOOGLE_EXTERNAL_ACCOUNT_AUDIENCE: il campo del pubblico della configurazione delle credenziali. Sempre presente.
  • GOOGLE_EXTERNAL_ACCOUNT_TOKEN_TYPE: il tipo di token dell'oggetto previsto. Sempre presente.
  • GOOGLE_EXTERNAL_ACCOUNT_OUTPUT_FILE: 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'impostazione come 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 proveniente da origine eseguibile, 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 del provider.
  • EXECUTABLE_COMMAND: il comando completo, inclusi gli argomenti, per eseguire il recupero del token dell'oggetto, ad esempio un token ID OIDC, nel seguente formato: --executable-command="/path/to/command --foo=bar".
  • EXECUTABLE_TIMEOUT: (facoltativo) 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. Ciò è utile per la memorizzazione nella cache delle credenziali. Prima di eseguire il file eseguibile, le librerie di autenticazione verificano questo percorso.
  • WORKFORCE_POOL_USER_PROJECT: il numero di progetto o l'ID 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 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 sorgente di eseguibili interattive: 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 delle 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 gli eventuali errori nel file specificato nel formato --executable-output-file nel seguente formato JSON. I seguenti campi sono 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 si verifica l'errore.

Al termine dell'esecuzione, il comando restituisce gli stessi campi, indipendentemente dal fatto che le credenziali di origine eseguibili interattive o non interattive siano precedenti.

Le variabili di ambiente sono uguali alle normali credenziali provenienti dall'eseguibile.

Per generare una credenziale interattiva di origine 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/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 del provider.
  • EXECUTABLE_COMMAND: il comando completo, inclusi gli argomenti, per eseguire il recupero del token dell'oggetto, formattato come segue: --executable-command="/path/to/command --arg1=val1 --arg2=val2"
  • EXECUTABLE_INTERACTIVE_TIMEOUT: una durata, in millisecondi, per attendere l'esecuzione dell'eseguibile.
  • EXECUTABLE_OUTPUT_FILE: un percorso del file alle credenziali di terze parti generate dall'eseguibile. Questo percorso è utile per memorizzare le credenziali nella cache. Prima di eseguire il file eseguibile, le librerie di autenticazione verificano questo percorso.
  • WORKFORCE_POOL_USER_PROJECT: il numero di progetto o l'ID utilizzato per la quota e la fatturazione. L'entità deve impostare l'autorizzazione serviceusage.services.use 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/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

Credenziali sorgente: le asserzioni vengono caricate da un file. Un altro processo deve aggiornare questo file con una nuova asserzione SAML con codifica base64 prima che scada la precedente. Ad esempio, se la asserzione ha una durata di un'ora, devi aggiornare il file prima che abbia 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 del 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 provenienti dall'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 file JSON contenente un'asserzione 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:id_token \
    --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 del provider.
  • CREDENTIAL_URL: l'URL dell'endpoint del server locale.
  • WORKFORCE_POOL_USER_PROJECT: il numero o l'ID del progetto utilizzato per quota e fatturazione. L'entità deve avere serviceusage.services.use permission in questo progetto.

Credenziali di origine eseguibili: le asserzioni vengono caricate da un'esecuzione 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 corretta, ad eccezione di expiration_time. Il campo expiration_time è obbligatorio solo quando è specificato un file di output nella configurazione delle credenziali.

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

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

Questi campi sono tutti obbligatori per la risposta agli errori. I campi Codice e Messaggio vengono utilizzati dalle librerie client quando generano l'errore appropriato.

Il comando può restituire i seguenti campi:

  • version: 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 e uno tra saml_response o 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 dell'oggetto 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 di scadenza della risposta SAML di terze parti in secondi (tempo Unix di epoca Unix)

  • code: la stringa del codice di errore

  • message: il messaggio di errore

Durante l'esecuzione, le librerie client completano le seguenti variabili di ambiente:

  • GOOGLE_EXTERNAL_ACCOUNT_AUDIENCE: il campo del 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 proveniente da origine eseguibile, 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 del provider.
  • EXECUTABLE_COMMAND: il comando completo, inclusi gli argomenti, per eseguire il recupero del token dell'oggetto nel seguente formato: --executable-command="/path/to/command --foo=bar".
  • EXECUTABLE_TIMEOUT: (facoltativo) la durata in millisecondi nell'attesa dell'esecuzione dell'eseguibile (il valore predefinito è 30 secondi).
  • EXECUTABLE_OUTPUT_FILE: (facoltativo) il percorso del file alle credenziali 3PI generate dall'eseguibile. Ciò è utile per memorizzare nella cache le credenziali. Le librerie di autenticazione ne verificano l'esistenza prima di eseguire il file eseguibile.
  • WORKFORCE_POOL_USER_PROJECT: il numero di progetto utilizzato per la quota e la fatturazione. L'entità deve impostare l'autorizzazione serviceusage.services.use 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/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 eseguibili per la modalità interattiva 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 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. La mancanza di expiration_time verrà considerata come il segnale sull'esecuzione del comando eseguibile in qualsiasi modo.

L'eseguibile deve visualizzare eventuali errori per executable-output-file nel seguente formato JSON:

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

Questi campi sono tutti obbligatori per la risposta agli errori. I campi Codice e Messaggio vengono utilizzati dalle librerie client quando generano l'errore appropriato.

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

Le variabili di ambiente sono uguali alle normali credenziali provenienti dall'eseguibile.

Per generare una credenziale interattiva di origine eseguibile, eseguiamo lo stesso comando gcloud iam. Dobbiamo solo aggiungere 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: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 del provider.
  • EXECUTABLE_COMMAND: il comando completo, inclusi gli argomenti, per eseguire il token del oggetto, formattato come segue: --executable-command="/path/to/command --foo=bar").
  • EXECUTABLE_INTERACTIVE_TIMEOUT: una durata in millisecondi per attendere l'esecuzione dell'eseguibile.
  • EXECUTABLE_OUTPUT_FILE: un percorso del file alle credenziali di terze parti generate dall'eseguibile. Ciò è utile per la memorizzazione nella cache delle credenziali. Prima di eseguire il file eseguibile, le librerie di autenticazione verificano questo percorso.
  • WORKFORCE_POOL_USER_PROJECT: il numero di progetto o l'ID 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 IdP OIDC 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 al momento le interfacce a riga di comando (gcloud, bq, gsutil) non supportano tipi di credenziali eseguibili.

Per i flussi headless, gcloud utilizza automaticamente il seguente ambito: https://www.googleapis.com/auth/cloud-platform. gcloud quindi 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 l'interfaccia a riga di comando gcloud.

Utilizza le librerie client di Google Cloud

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

Il supporto delle librerie 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 lingue, procedi nel seguente modo:

bq

Per eseguire l'autenticazione 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 per la federazione delle identità della 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à della forza lavoro utilizzando un oggetto ChannelCredentials, creato chiamando grpc::GoogleDefaultCredentials(). Per inizializzare questa credenziale, devi creare le librerie client con la versione 1.42.0 o successive di gRPC.

La libreria client di Cloud Storage per C++ utilizza l'API REST, non gRPC, quindi non supporta 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à 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 per la federazione delle identità della forza lavoro in gcloud è disponibile nella versione 392.0.0 e successive di Google Cloud CLI.

Go

Le librerie client per Go supportano la federazione delle identità della forza lavoro se utilizzano la versione 0.0.0-20211005180243-6b3c2da341f1 o versioni 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)
}

gsutil

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

Quando utilizzi gsutil in combinazione con gcloud, accedi come di consueto:

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à della forza lavoro in gsutil è disponibile nella versione 379.0.0 e successive di Google Cloud CLI.

Java

Le librerie client per Java supportano la federazione delle identità della forza lavoro se utilizzano 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 per Node.js supportano la federazione delle identità della forza lavoro. Devi utilizzare la versione 7.10.0 o successive del pacchetto google-auth-library. A differenza dei pool di Workload Identity, 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 maggiori informazioni, consulta il 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à 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 trasmetterlo esplicitamente quando utilizzi un'istanza di servizio (come nell'esempio del client di archiviazione) oppure impostarla tramite la variabile di ambiente GOOGLE_CLOUD_PROJECT.

Per informazioni dettagliate, 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 a 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 dell'oggetto.
  • PROVIDER_ID: l'ID provider

  • SUBJECT_TOKEN_TYPE: imposta 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 è 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 quota e 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 temporanei di Google Cloud che gcloud ottiene dall'endpoint del servizio token di sicurezza scadono dopo un intervallo di tempo specificato. Quando il token sta per scadere, gcloud esamina il file delle credenziali che hai fornito e la validità delle credenziali che hai ricevuto dall'IdP. Se le credenziali continueranno a essere valide, gcloud procederà a ottenere in modo trasparente un nuovo token di accesso a Google Cloud e la sessione attuale verrà eseguita senza interruzioni.

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

Puoi terminare la sessione eseguendo questo comando:

gcloud auth revoke

gcloud supporta più sessioni utente. Per ottenere l'elenco delle sessioni, compresa quella attuale, 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 impostarlo come attivo, esegui questo comando:

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

Passaggi successivi