Configuring workload identity federation

This guide describes how to use credentials issued by an external identity provider to impersonate a service account and access resources on Google Cloud. This process is called workload identity federation.

Common use cases for workload identity federation include:

  • Enabling a background application or continuous integration/continuous delivery (CI/CD) pipeline that runs outside of Google Cloud to access Google Cloud resources and APIs
  • Enabling users of a web application that runs outside of Google Cloud to access data stored in a Google Cloud service, such as Cloud Storage or BigQuery

To use workload identity federation, you configure Google Cloud to trust an external identity provider such as Amazon Web Services (AWS), Azure Active Directory (AD), or an OIDC-compatible identity provider. Applications can then use credentials issued by the external identity provider to impersonate a service account by following these steps:

  1. Obtain a credential from the trusted identity provider.
  2. Exchange the credential for a token from the Security Token Service.
  3. Use the token from the Security Token Service to impersonate a service account and obtain a short-lived Google access token.

By using workload identity federation, you can avoid the need to store and manage service account keys.

Before you begin

  • Enable the IAM, Resource Manager, Service Account Credentials, and Security Token Service (STS) APIs.

    Enable the APIs

  • Ensure that you have the Workload Identity Pool Admin (roles/iam.workloadIdentityPoolAdmin) and Service Account Admin (roles/iam.serviceAccountAdmin) roles on the project.

    Alternatively, the IAM Owner (roles/owner) basic role also includes permissions to configure identity federation. You should not grant basic roles in a production environment, but you can grant them in a development or test environment.

Preparing the external identity provider

To use workload identity federation, you must configure a workload identity pool and a workload identity pool provider in your project:

AWS

AWS users and AWS roles can use permanent or temporary AWS security credential to impersonate a service account on Google Cloud.

To allow the use of AWS security credentials, you must configure the workload identity pool to trust your AWS account. Security credentials tokens issued for this AWS account are then recognized by workload identity federation, and you can use the tokens to obtain short-lived service account credentials.

Azure

Azure users and service principals can use Azure AD access tokens to impersonate a service account on Google Cloud.

To allow the use of Azure AD access tokens, you must configure the workload identity pool to trust an Azure AD application. Access tokens issued for this application are then recognized by workload identity federation, and you can use the tokens to obtain short-lived service account credentials.

As a best practice, you should create a new application in Azure AD and use the application only to obtain Google Cloud credentials:

  1. Create an Azure AD application and service principal.

  2. Set an Application ID URI for the application.

    Instead of defining a custom Application ID URI, you can use the following URI:

    https://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID

    Replace the following values:

    • PROJECT_NUMBER: Project number of the Google Cloud project that you use to create workload identity pool.
    • POOL_ID: ID of your choice that identifies the workload identity pool. You must use the same ID when creating the workload identity pool later.
    • PROVIDER_ID: ID of your choice that identifies the workload identity pool provider. You must use the same ID when creating the workload identity pool provider later.

    This format ensures that the Application ID URI uniquely identifies a workload identity pool provider.

You need the Application ID URI later when you configure the workload identity pool provider.

To let an application obtain access tokens for the Azure AD application, you can use managed identities:

  1. Create a managed identity. Note the Object ID of the managed identity. You need it later when you configure impersonation.

  2. Assign the managed identity to a virtual machine or another resource that runs your application.

OIDC

You can let users and applications impersonate a service account on Google Cloud by using ID tokens or JSON Web Token-formatted access token issued by an OIDC-compliant identity provider.

To allow the use of these tokens, you must configure the workload identity pool to trust your external identity provider. Tokens issued by the external identity provider are then recognized by workload identity federation, and you can use the tokens to obtain short-lived service account credentials.

To use workload identity federation, your identity provider's OIDC metadata URI must be publicly accessible over the internet and use the endpoint ISSUER/.well-known/openid-configuration, where ISSUER is the Issuer URL that uniquely identifies your provider. Google queries the metadata endpoint to obtain your provider's JSON Web Key Set (JWKS) and then uses this key set to validate tokens.

Typically, it's best to use ID tokens when performing a token exchange, because ID tokens reflect the user's identity. If you decide to use access tokens instead, configure a dedicated application or resource in your identity provider for the sole purpose of obtaining Google Cloud credentials.

Configuring federation

To federate with your external identity provider, you must do the following:

  1. Prepare a Google Cloud project that will contain the workload identity pool and provider.
  2. Define an attribute mapping and an optional attribute condition that map the identity provider's credentials to external identities.
  3. Create a workload identity pool and provider.

The following sections guide you through this process.

Prepare the project

Select and prepare the project that will contain the workload identity pool and provider:

  1. Ensure that you have the Workload Identity Pool Admin (roles/iam.workloadIdentityPoolAdmin) and Service Account Admin (roles/iam.serviceAccountAdmin) roles on the project.

    Alternatively, the IAM Owner (roles/owner) basic role also includes permissions to configure identity federation. You should not grant basic roles in a production environment, but you can grant them in a development or test environment.

  2. Update the organization policy for your organization to allow federation.

  3. Enable the IAM, Resource Manager, Service Account Credentials, and Security Token Service (STS) APIs.

    Enable the APIs

Define an attribute mapping and condition

Define an attribute mapping and an optional attribute condition that map the identity provider's credentials to external identities.

The credentials issued by your external identity provider contain one or more attributes, also referred to as claims. Common attribute names include sub, email, aud, or iat. Workload identity federation refers to these attributes as assertion attributes and prefixes them with assertion..

An attribute mapping lets you map assertion attributes to the predefined target attributes recognized by workload identity federation. These predefined target attributes are:

Attribute Description
google.subject Required. A unique identifier for the user. This attribute is used in IAM principal:// role bindings and appears in Cloud Logging logs. The value must be unique and can't exceed 127 characters.
google.groups Optional. A set of groups that the identity belongs to. This attribute is used in IAM principalSet:// role bindings to grant access to all members of a group.
attribute.NAME Optional. You can define up to 50 custom attributes and use these attributes in IAM principalSet:// role bindings to grant access to all identities with a certain attribute.

An attribute mapping takes the form TARGET_ATTRIBUTE=SOURCE_EXPRESSION. See the following examples:

  • This mapping assigns the assertion attribute sub to google.subject:

    google.subject=assertion.sub

  • This mapping uses a Common Expression Language (CEL) expression to concatenate multiple assertion attributes:

    google.subject="myprovider::" + assertion.aud + "::" + assertion.sub

  • This mapping uses another CEL expression to map a GUID-valued assertion attribute workload_id to a name, and assigns the result to a custom attribute named attribute.my_display_name:

    attribute.my_display_name={
  "8bb39bdb-1cc5-4447-b7db-a19e920eb111": "Workload1",
  "55d36609-9bcf-48e0-a366-a3cf19027d2a": "Workload2"
}[assertion.workload_id]

  • This mapping uses CEL logical operators and functions to set a custom attribute named attribute.environment to either prod or test, depending on the identity's Amazon Resource Name (ARN):

    attribute.environment=assertion.arn.contains(":instance-profile/Production") ? "prod" : "test"

  • This mapping uses the extract function to populate a custom attribute aws_role with the name of the assumed role or, if no role has been assumed, with the identity's ARN.

    attribute.aws_role=assertion.arn.contains('assumed-role') ? assertion.arn.extract('{account_arn}assumed-role/') + 'assumed-role/' + assertion.arn.extract('assumed-role/{role_name}/') : assertion.arn

Optionally, you can also define an attribute condition. Attribute conditions are CEL expressions that can check assertion attributes and target attributes. If the attribute condition evaluates to true for a given credential, the credential is accepted. Otherwise, the credential is rejected.

To choose the right attribute mappings and conditions for your use case, you need to decide whether to map service identities or user identities:

  • By mapping service identities, you can enable an background application or CI/CD pipeline that runs outside of Google Cloud to obtain short-lived credentials for Google Cloud. The application obtains these short-lived credentials on its own behalf, without user involvement.
  • By mapping user identities, you can enable users of an application that runs outside of Google Cloud to obtain short-lived credentials for Google Cloud. The application obtains these short-lived credentials on a user's behalf.

Mapping service identities

AWS

Your attribute mappings can use the response fields for GetCallerIdentity as source attributes. These fields include:

  • account, containing the AWS account number.
  • arn, containing the AWS ARN of the external entity.
  • userid, containing the unique identifier of the calling entity.

If your application runs on an Amazon Elastic Compute Cloud (EC2) instance with an attached role, you can use the following attribute mapping:

google.subject=assertion.arn
attribute.aws_role=assertion.arn.contains('assumed-role') ? assertion.arn.extract('{account_arn}assumed-role/') + 'assumed-role/' + assertion.arn.extract('assumed-role/{role_name}/') : assertion.arn

This mapping lets you grant the ability to impersonate a service account to specific EC2 instances or by role.

Your AWS account might contain a large number of users and roles, but only a small subset of these might require access to Google Cloud resources. To limit the set of users and roles that can use workload identity federation, use an attribute condition. For example, the following condition allows a specific account to access Google Cloud resources:

assertion.arn.startsWith('arn:aws:sts::ACCOUNT-ID:assumed-role/')

Azure

Your attribute mappings can use the claims embedded in Azure access tokens, including custom claims, as source attributes.

To obtain a complete list of claims you can reference, connect to an Azure VM that has an assigned managed identity and do the following:

  1. Obtain an access token from the Azure Instance Metadata Service (IMDS):

    Bash

    curl \
  "http://169.254.169.254/metadata/identity/oauth2/token?resource=APP_ID_URI&api-version=2018-02-01" \
  -H "Metadata: true" | jq -r .access_token

    This command uses the jq tool. jq is available by default in Cloud Shell.

    PowerShell

    $SubjectTokenType = "urn:ietf:params:oauth:token-type:jwt"
$SubjectToken = (Invoke-RestMethod `
  -Uri "http://169.254.169.254/metadata/identity/oauth2/token?resource=APP_ID_URI&api-version=2018-02-01" `
  -Headers @{Metadata="true"}).access_token
Write-Host $SubjectToken

    Replace APP_ID_URI with the Application ID URI of the application that you've configured for workload identity federation.

  2. In a web browser, go to https://jwt.ms/ and paste the access token into the text box.

  3. Click Claims to view the list of claims embedded in the access token.

To authenticate with a service principal, you can use the following attribute mapping:

google.subject=assertion.sub

For an access token issued to a managed identity, the sub claim contains the Object ID of the managed identity. If you use a different claim, make sure that the claim is unique and can't be reassigned.

For service identities, it's typically not necessary to create a mapping for google.groups or any custom attributes.

To control which identities can obtain short-lived credentials for Google Cloud, do not define attribute conditions. Instead, configure your Azure AD application to use app role assignments.

OIDC

Your attribute mappings can use the claims embedded in the ID token or access token issued by the external identity provider.

You must map one of these claims to google.subject to uniquely identify the user. To protect against spoofing threats, choose a claim with a unique value that can't be changed.

Many identity providers populate the sub claim with a unique and immutable ID. For these identity providers, consider mapping the sub claim to google.subject:

google.subject=assertion.sub

Avoid using a claim like email for this purpose. Email addresses can typically be reassigned or changed, so they don't uniquely and permanently identify a user.

Your identity provider might contain a large number of users, but only a small subset of these might require access to Google Cloud resources. To limit the set of users and credentials that can use workload identity federation, you can optionally use an attribute condition.

For example, the following condition restricts access to tokens that contain a custom service_account claim with a value true:

assertion.service_account==true

Create the workload identity pool and provider

You've now collected all the information you need to create a workload identity pool and provider:

Console

  1. In the Cloud Console, go to the New workload provider and pool page.

    Go to New workload provider and pool

  2. Under Create an identity pool, enter the following:

    • Name: Name for the pool. The name is also used as the pool ID. You can't change the pool ID later.
    • Description: Text that describes the purpose of the pool.

  3. Click Continue.

  4. In the Select a provider drop-down list, select your provider:

    • AWS if you're federating with AWS.
    • OpenID Connect (OIDC) if you're federating with an OIDC-compatible provider, such as Microsoft Azure.

  5. Under Provider details, enter the following:

    • Provider name: Name for the provider. The name is also used as the provider ID. You cannot change the provider ID later.
    • AWS Account ID (AWS only): Your AWS account ID
    • Issuer URL (OIDC only): The issuer URI. See this page's instructions for finding the issuer URI.

  6. Click Continue.

  7. Under Configure provider attributes, add the attribute mappings that you've identified previously.

  8. Under Attribute conditions, enter the attribute condition that you've identified previously. Leave the field blank if you don't have an attribute condition.

  9. Click Save to create the workload identity pool and provider.

gcloud

  1. Create a new workload identity pool:

    gcloud iam workload-identity-pools create POOL_ID \
    --location="global" \
    --description="DESCRIPTION" \
    --display-name="DISPLAY_NAME"

    Replace the following values:

    • POOL_ID: Unique ID for the pool.
    • DISPLAY_NAME: Name of the pool.
    • DESCRIPTION: Description of the pool. This description appears when granting access to pool identities.

  2. Add a workload identity pool provider:

    AWS 

    gcloud iam workload-identity-pools providers create-aws PROVIDER_ID \
  --location="global"  \
  --workload-identity-pool="POOL_ID" \
  --account-id="AWS_ACCOUNT_ID" \
  --attribute-mapping="MAPPINGS" \
  --attribute-condition="CONDITIONS"

    Replace the following values:

    Example:

    gcloud iam workload-identity-pools providers create-aws example-provider \
  --location="global"  \
  --workload-identity-pool="pool-1" \
  --account-id="123456789000" \
  --attribute-mapping="google.subject=assertion.arn"

    Azure 

    gcloud iam workload-identity-pools providers create-oidc PROVIDER_ID \
    --location="global" \
    --workload-identity-pool="POOL_ID" \
    --issuer-uri="https://sts.windows.net/TENANT_ID" \
    --allowed-audiences="APPLICATION_ID_URI" \
    --attribute-mapping="MAPPINGS" \
    --attribute-condition="CONDITIONS"

    Replace the following values:

    Example:

    gcloud iam workload-identity-pools providers create-oidc example-provider \
    --location="global" \
    --workload-identity-pool="pool-1" \
    --issuer-uri="https://sts.windows.net/00000000-1111-2222-3333-444444444444" \
    --allowed-audiences="api://my-app" \
    --attribute-mapping="google.subject=assertion.sub,google.groups=assertion.groups"

    OIDC 

    gcloud iam workload-identity-pools providers create-oidc PROVIDER_ID \
    --location="global" \
    --workload-identity-pool="POOL_ID" \
    --issuer-uri="ISSUER" \
    --allowed-audiences="AUDIENCE" \
    --attribute-mapping="MAPPINGS" \
    --attribute-condition="CONDITIONS"

    Replace the following values:

What's next