Obtain short-lived tokens for Workforce Identity Federation

OIDC

You can source the credentials that you use to set up your configuration file from the following sources:

• File-sourced credentials
• URL-sourced credentials
• Non-interactive executable-sourced credentials
• Interactive executable-sourced credentials

File-sourced credentials

When you use file-sourced credentials, tokens are loaded from a file. Another process must refresh this file with a new OIDC token before the old token expires. For example, if the token has a lifetime of one hour, you must refresh the file before it is one hour old.

To generate the configuration file with a file-sourced credential, execute the following command:

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

Replace the following:

• WORKFORCE_POOL_ID: the workforce identity pool ID
• WORKFORCE_PROVIDER_ID: the workforce identity pool provider ID
• PATH_TO_OIDC_TOKEN: the path to the OIDC IdP credential file
• WORKFORCE_POOL_USER_PROJECT: the project number or ID associated with the workforce pools user project.

The principal must have serviceusage.services.use permission on this project.

Running the command produces an OIDC IdP config file similar to the following:

{
  "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"
  }
}

URL-sourced credentials

When you use URL-sourced credentials, tokens are loaded from a local server with an endpoint that responds to HTTP GET requests. The response must be an OIDC ID token, either in plain text or in JSON format.

To generate a configuration file with a URL-sourced credential, execute the following command:

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

Replace the following:

• WORKFORCE_POOL_ID: the workforce identity pool ID.
• WORKFORCE_PROVIDER_ID: the workforce identity pool provider ID.
• URL_TO_RETURN_OIDC_ID_TOKEN: the URL to call to retrieve the OIDC credentials, such as an OIDC ID token—for example: http://localhost:5000/token.
• WORKFORCE_POOL_USER_PROJECT: the project number used for quota and billing. The principal needs to have serviceusage.services.use permission on this project.

Running the command produces an OIDC IdP config file similar to the following:

{
  "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"
  }
}

Non-interactive executable-sourced credentials

When you use non-interactive executable-sourced credentials, tokens are loaded from a local executable. The executable must provide a valid, unexpired OIDC ID token in JSON format to stdout:

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

These fields are required for a successful response, with the exception of expiration_time. The expiration_time field is only required when an output file has been specified in the credential configuration.

The executable must surface any errors to stdout in the following JSON format:

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

These fields are all required for an error response. The code and message fields are used by the client libraries when raising the appropriate error.

The command can return the following fields:

• version: the version of the JSON output. Only version 1 is supported.

• success: the status of the response. When the status is true, the executable must exit with exit code 0 and the response must contain the following fields:

  • token_type: id_token
  • expiration_time field, if an output file is specified in the credential configuration

  When the status is false, the executable must exit with a non-zero value and the response must contain the following fields:

  • code
  • message

• token_type: the third-party subject token type, which must be urn:ietf:params:oauth:token-type:id_token

• id_token: the third-party OIDC token

• expiration_time: the third-party OIDC token expiration time in seconds (Unix epoch time)

• code: the error code string

• message: the error message

The client libraries set the following environment variables when the executable is run:

• GOOGLE_EXTERNAL_ACCOUNT_AUDIENCE: the audience field from the credential configuration. This variable is always set.
• GOOGLE_EXTERNAL_ACCOUNT_TOKEN_TYPE: the expected subject token type. This variable is always set.
• GOOGLE_EXTERNAL_ACCOUNT_OUTPUT_FILE: the output file location from the credential configuration. This variable is only present when it is specified in the credential configuration.

These environment variables can be used by the executable to avoid hardcoding these values.

To enable this credential sourcing method with the client libraries, the GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES environment variable must be set to 1.

To generate the configuration file with an executable-sourced credential, run the following command:

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

Replace the following:

• WORKFORCE_POOL_ID: the workforce identity pool ID.
• WORKFORCE_PROVIDER_ID: the workforce identity pool provider ID.
• EXECUTABLE_COMMAND: the full command, including arguments, to run to retrieve the subject token, such as an OIDC ID token, in the following format: --executable-command="/path/to/command --foo=bar".
• EXECUTABLE_TIMEOUT: Optional. A duration, in milliseconds, to wait for the executable to run (defaults to 30s).
• EXECUTABLE_OUTPUT_FILE: Optional. A path to the third-party credentials generated by the executable. This is useful for caching the credentials. The Auth libraries first check for this path before running the executable.
• WORKFORCE_POOL_USER_PROJECT: the project number or ID that is used for quota and billing. The principal must have the serviceusage.services.use permission set on this project.

Running the command produces an OIDC IdP config file similar to the following:

{
  "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"
    }
  }
}

Interactive executable-sourced credentials

When you use interactive executable-sourced credentials, you can provide an executable that interacts with the user through stdin and stdout. If the user successfully signs in, the executable writes a valid, unexpired credential to the specified file.

To use this mode, the following flags are required:

• --executable-output-file: the file that the executable writes the credential information to
• --exeutable-interactive-timeout-millis: a non-zero value that indicates interactive mode and sets the timeout—for example, 6000 for a 60-second timeout

The following fields are required for a successful response, with the exception of expiration_time:

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

The executable must write any errors to the file specified in --executable-output-file in the following JSON format. The following fields are all required when returning an error response.

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

The code and message fields must indicate the appropriate error. These fields are used by the client libraries when raising the error.

Upon successful execution, the command returns the same fields for interactive and non-interactive executable-sourced credentials.

The environment variables are also the same for interactive and non-interactive executable-sourced credentials.

To generate an interactive executable-sourced credential, add the parameter --executable-interactive-timeout-millis and the parameter --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

Replace the following:

• WORKFORCE_POOL_ID: the workforce identity pool ID.
• WORKFORCE_PROVIDER_ID: the workforce identity pool provider ID.
• EXECUTABLE_COMMAND: the full command, including arguments, to run to retrieve the subject token, formatted as follows: --executable-command="/path/to/command --arg1=val1 --arg2=val2"
• EXECUTABLE_INTERACTIVE_TIMEOUT: a duration, in milliseconds, to wait for the executable to run.
• EXECUTABLE_OUTPUT_FILE: a path to the third-party credentials generated by the executable. This path is useful for caching the credentials. The authentication libraries first check for this path before running the executable.
• WORKFORCE_POOL_USER_PROJECT: the project number or ID used for quota and billing. The principal must have the serviceusage.services.use permission on this project.

Running the command produces an OIDC IdP config file similar to the following:

{
  "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",
    }
  }
}

The timeout_millis field is returned because an interactive executable can also run in non-interactive mode, in some cases. In interactive mode, the command returns a default timeout.

SAML

You can source the credentials that you use to set up your configuration file from the following sources:

• File-sourced credentials
• URL-sourced credentials
• Executable-sourced credentials
• Executable-sourced credentials for gcloud interactive mode

File-sourced credentials

Assertions are loaded from a file. Another process must refresh this file with a new base64-encoded SAML assertion before the old assertion expires. For example, if the assertion has a lifetime of one hour, you must refresh the file before it is one hour old.

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

Replace the following:

• WORKFORCE_POOL_ID: the workforce identity pool ID.
• WORKFORCE_PROVIDER_ID: the workforce identity pool provider ID.
• CREDENTIAL_FILE: the path to the credential file that is generated by the IdP.
• WORKFORCE_POOL_USER_PROJECT: the project number or ID that is used for quota and billing. The principal must have serviceusage.services.use permission on this project.

URL-sourced credentials

Executable-sourced credentials

Assertions are loaded from a local executable. The executable must provide a valid, unexpired SAML assertion in JSON format to stdout.

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

These fields are required for a successful response, with the exception of expiration_time. The expiration_time field is required only when an output file is specified in the credential configuration.

If an error occurs, it must be surfaced by the executable in the following JSON format to stdout:

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

These fields are all required for an error response. The code and message fields are used by the client libraries when raising the appropriate error.

The command can return the following fields:

• version: the version of the JSON output. Only version 1 is supported.

• success: the status of the response. When the status is true, the executable must exit with exit code 0 and the response must contain the following fields:

  • token_type: saml_response
  • expiration_time field, if an output file is specified in the credential configuration

  When the status is false, the executable must exit with a non-zero value and the response must contain the following fields: + code + message

• token_type: the third-party subject token type, which must be urn:ietf:params:oauth:token-type:saml2

• saml_response: the third-party SAML response

• expiration_time: the third-party SAML response expiration time in seconds (Unix epoch time)

• code: the error code string

• message: the error message

The client libraries set the following environment variables when the executable is run:

• GOOGLE_EXTERNAL_ACCOUNT_AUDIENCE: the audience field from the credential configuration. This variable is always set.
• GOOGLE_EXTERNAL_ACCOUNT_TOKEN_TYPE: the expected subject token type. This variable is always set.
• GOOGLE_EXTERNAL_ACCOUNT_OUTPUT_FILE: the output file location from the credential configuration. This variable is only present when it is specified in the credential configuration.

To enable this credential sourcing method with the client libraries, set the GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES environment variable to 1.

To generate the configuration file with a executable-sourced credential, execute the following command:

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

Replace the following:

• WORKFORCE_POOL_ID: the workforce identity pool ID.
• WORKFORCE_PROVIDER_ID: the workforce identity pool provider ID.
• EXECUTABLE_COMMAND: the full command, including arguments, to run to retrieve the subject token, in the following format: --executable-command="/path/to/command --foo=bar".
• EXECUTABLE_TIMEOUT: Optional. The duration in milliseconds to wait for the executable to run (defaults to 30s).
• EXECUTABLE_OUTPUT_FILE: Optional. The path to the third-party identity (3PI) credentials generated by the executable. This is useful for caching the credentials. The authorization libraries check for its existence before running the executable.
• WORKFORCE_POOL_USER_PROJECT: the project number used for quota and billing. The principal must have the serviceusage.services.use permission on this project.

Running the command produces a SAML IdP config file that is similar to the following:

{
  "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"
    }
  }
}

Executable-sourced credentials for gcloud interactive mode

When you use executable-sourced credentials for gcloud interactive mode, an executable interacts with the user through the command line interface.

In the previous command, replace the following:

• EXECUTABLE_OUTPUT_FILE: Required. The path to the file that provides the credentials generated by the executable.
• EXECUTABLE_TIMEOUT: Required. A non-zero timeout value also signals the command to use interactive mode.

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

These fields are required for a successful response, with the exception of expiration_time. When expiration_time is omitted, the executable is still run.

The executable must surface any errors to the executable-output-file in the following JSON format. When the executable reports an error, these fields are all required. The code and message fields are used by the client libraries when raising the appropriate error.

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

Successful command execution returns the same fields as non-interactive executable-sourced credentials.

The environment variables are also the same as a non-interactive executable-sourced credentials.

To generate an interactive executable-sourced credential, add the parameter --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

Replace the following:

• WORKFORCE_POOL_ID: the workforce identity pool ID.
• WORKFORCE_PROVIDER_ID: the workforce identity pool provider ID.
• EXECUTABLE_COMMAND: the full command, including arguments, to run to retrieve the subject token, formatted as follows: --executable-command="/path/to/command --foo=bar").
• EXECUTABLE_INTERACTIVE_TIMEOUT: a duration, in milliseconds, to wait for the executable to run.
• EXECUTABLE_OUTPUT_FILE: a path to the third-party credentials generated by the executable. This is useful for caching the credentials. The authentication libraries first check for this path before running the executable.
• WORKFORCE_POOL_USER_PROJECT: the project number or ID used for quota and billing. The principal must have the serviceusage.services.use permission on this project.

Running the command produces a SAML IdP config file similar to the following:

{
  "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>",
    }
  }
}

bq tool

To authenticate using Workforce Identity Federation, use the gcloud auth login command:

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

where FILEPATH is the path to the credential configuration file.

Support for Workforce Identity Federation in the bq tool is available in version 390.0.0 and later versions of the Google Cloud CLI.

C++

Most of the Google Cloud Client Libraries for C++ support Workforce Identity Federation by using a ChannelCredentials object, which is created by calling grpc::GoogleDefaultCredentials(). To initialize this credential, you must build the client libraries with version 1.42.0 or later of gRPC.

The Cloud Storage Cloud Client Libraries for C++ uses the REST API, not gRPC, so it doesn't support Workforce Identity Federation.

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

To authenticate using Workforce Identity Federation, use the gcloud auth login command:

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

Replace FILEPATH with the path to the credential configuration file.

Support for Workforce Identity Federation in the gcloud CLI is available in version 392.0.0 and later versions of the Google Cloud CLI.

Go

Cloud Client Libraries for Go support Workforce Identity Federation when you use version v0.0.0-20211005180243-6b3c2da341f1 or later of the golang.org/x/oauth2 module.

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

Cloud Client Libraries for Java support Workforce Identity Federation when you use version 1.2.0 or later of the com.google.auth:google-auth-library-oauth2-http artifact.

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

Cloud Client Libraries for Node.js support Workforce Identity Federation when you use version 7.10.0 or later of the google-auth-library package.

Unlike workload identity pools, workforce identity pools are associated with an organization and not a Google Cloud project. When you create a GoogleAuth object, you must specify a project ID. For more information, see the README for the google-auth-library package.

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

Cloud Client Libraries for Python support Workforce Identity Federation when you use version 2.3.0 or later of the google-auth package.

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)

In the example code, the project value can be None if the library is unable to automatically discover the project ID. You can pass the project ID explicitly when using a service instance, as the storage client example does, or set the project ID through the environment variable GOOGLE_CLOUD_PROJECT.

For details, see the user guide for the google-auth package.