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), an OIDC-compatible identity provider, or a SAML 2.0-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 APIs.

    Enable the APIs

Required roles

To get the permissions that you need to configure workload identity federation, ask your administrator to grant you the following IAM roles on the project:

  • Workload Identity Pool Admin (roles/iam.workloadIdentityPoolAdmin)
  • Service Account Admin (roles/iam.serviceAccountAdmin)

For more information about granting roles, see Manage access.

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.

    When setting the Application ID URI, it will default to api://<appid>. Note the URI since you will need it later when creating the workload identity pool provider and the credential configuration file.

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.

GitHub Actions

You can let a GitHub Actions workflow use a GitHub OIDC token to impersonate a service account on Google Cloud.

To allow the use of these tokens, you must configure the workload identity pool to trust OIDC tokens issued by GitHub. ID tokens issued for workflows are then recognized by workload identity federation, and you can use the tokens to obtain short-lived service account credentials.

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 value of the issuer (iss) claim in the token. Google Cloud 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.

By default, workload identity federation expects tokens that use the following URL as audience (aud) claim:

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

Replace the following:

  • PROJECT_NUMBER: project number. of the Google Cloud project that you use to create workload identity pool.
  • POOL_ID: an 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: an 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.

You can specify a custom list of allowed audiences when you create the workload identity pool and provider.

OIDC (AD FS)

Active Directory users can use OIDC access tokens from Active Directory Federation Services (AD FS) to impersonate a service account on Google Cloud.

To let an application request AD FS access tokens and use these tokens to access Google Cloud, you need two application registrations in AD FS:

  1. An application registration of type native application or server application.

  2. An application registration of type Web API that corresponds to a workload identity pool provider on Google Cloud.

You then configure a workload identity provider to accept access tokens issued to the Web API.

Using Integrated Windows Authentication

You can combine workload identity federation with Integrated Windows Authentication (IWA). IWA lets Active Directory applications authenticate to AD FS by using Kerberos or NTLM credentials. By combining workload identity federation and IWA, you avoid having to store and manage AD FS client credentials and service account keys.

To use IWA, ensure that the following prerequisites are met:

Registering the client application

To register an application in AD FS for Windows Server 2019, do the following:

  1. Open the AD FS MMC snap-in and navigate to Application Groups.
  2. Click Add application group.
  3. On the Welcome page, enter a name for the client, select server application. Then click Next.
  4. On the Server application page, enter a client identifier (Client ID) and a redirect URI. If you're only planning to use the client_credentials grant type, the redirect URI won't be used and you can use a URI such as http://localhost/. Then click Next.
  5. On the Configure application credentials page, choose how the client will authenticate. To use IWA, set Windows Integrated Authentication to enabled and select the domain user that your application is configured to run as. Then click Next.
  6. On the Summary page, review the settings and click Next.
  7. Click Close to dismiss the dialog.

Creating a Web API application for the workload identity federation pool

Create another application registration of type Web API. This application corresponds to a workload identity pool provider and you use it to set up a trust relationship to Google Cloud.

To create the application in AD FS for Windows Server 2019, do the following:

  1. Open the AD FS MMC snap-in and navigate to Application Groups.
  2. Click Add application group.
  3. On the Welcome page, enter a name such as Workload Identity Federation (test environment) and select Web API. Then click Next.

  4. On the Configure Web API page, enter a relying party identifier for the Web API.

    Instead of defining a custom relying party identifier, you can use the following URI as relying party identifier:

    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 relying party identifier uniquely identifies a workload identity pool provider.

    You need the relying party identifier later when you configure the workload identity pool provider.

  5. Click Next.

  6. On the Apply access control policy page, select an appropriate access policy, then click Next.

  7. On the Configure application permissions page, add the client application that you created previously. Then click Next.

  8. On the Summary page, review the settings and click Next.

  9. Click Close to dismiss the dialog.

SAML

You can let users and applications impersonate a service account on Google Cloud by using assertions issued by a SAML 2.0-compliant identity provider. Federation using encrypted assertions is not supported.

Configure your SAML identity provider to issue assertions with the workload identity pool provider as audience in the format https://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID.

To allow the use of these assertions, you must then configure the workload identity pool to trust your external identity provider by providing it your SAML identity provider's metadata document.

Workload identity federation then recognizes assertions issued by the external identity provider, and you can use the tokens to obtain short-lived service account credentials.

SAML (AD FS)

You can let applications impersonate a service account on Google Cloud by using a SAML 2.0 assertion from Active Directory Federation Services (AD FS).

To let applications request a SAML assertion from AD FS that can be used for workload identity federation, you must create a relying party trust. To create a relying party trust in AD FS for Windows Server 2019, do the following:

  1. Open the AD FS MMC snap-in and navigate to Relying party trusts.
  2. Click Add relying party trust.
  3. On the Welcome page of the Add relying party trust wizard, select Claims aware and click Start.
  4. On the Select data source page, select Enter data about the relying party manually. Then click Next.
  5. On the Specify display name page, enter a name for the trust. Then click Next.
  6. On the Configure certificate page, click Next. An encryption certificate isn't required because workload identity federation doesn't support encrypted SAML assertions.
  7. On the Configure URL page, keep the default settings and click Next.

  8. On the Configure identifiers page, enter a relying party identifier.

    Instead of defining a custom relying party identifier, you can use the following URI as relying party identifier:

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

    Replace the following:

    • 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 relying party identifier uniquely identifies a workload identity pool provider.

    You need the relying party identifier later when you configure the workload identity pool provider.

  9. Click Next.

  10. On the Choose access control policy page, select an appropriate access control policy, then click Next.

  11. On the Ready to add trust page, review the settings and click Next.

  12. On the Finish page, click Close to dismiss the dialog.

To be compatible with workload identity federation, SAML assertions must contain at least one claim that uniquely identifies the Active Directory user. Typically, you use the Name ID claim for this purpose, which corresponds to the value of the NameID element in the SAML assertion.

To customize the SAML assertion's set of claims, you must edit the relying party trust's claim issuance policy. To edit the claim issuance policy, do the following:

  1. In the list of relying party trusts, select the trust that you just created and click Edit claim issuance policy.
  2. Click Add rule
  3. On the Choose rule type page of the Add transform claim rule wizard, select Transform an incoming claim. Then click Next.

  4. On the Configure claim rule page, configure the following settings:

    • Claim rule name: Name Identifier.
    • Incoming claim type: Select Primary SID, UPN, or a different claim to uniquely identify the subject.
    • Outgoing claim type: Name ID.
    • Outgoing name ID format: Unspecified.

  5. Select Pass through all claim values and click Finish.

  6. Optionally, configure additional rules to include more attributes in the SAML assertions.

  7. Click OK to close the claim issuance policy dialog.

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. 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 using the following identifiers:

Grant access to specific EC2 instance: 

principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/arn:aws:sts::ACCOUNT_ID:assumed-role/AWS_ROLE/AWS_ROLE_SESSION_NAME

Grant access by role: 

principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.aws_role/arn:aws:sts::ACCOUNT_ID:assumed-role/AWS_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.

GitHub Actions

Your attribute mappings can use the claims embedded in the OIDC token as source attributes. These include:

  • sub: Contains the repository name and Git reference, for example repo:username/reponame:ref:refs/heads/master.
  • repository: Contains the owner and repository name, for example username/reponame.
  • repository_owner: Contains the owner, which can be a username or the name of a GitHub organization.
  • ref: Contains the Git reference, for example refs/heads/main.

The following attribute mapping sets google.subject to the sub claim from the GitHub Actions OIDC token. Because the sub claim contains both, the repository name and Git reference, this mapping lets you control access by repository and branch:

google.subject=assertion.sub

Controlling access by repository and branch can be useful if certain branches (for example, main) need different access to resources than other branches (for example, feature branches).

If you don't plan to differentiate access by branch, you can use the following attribute mapping, which sets google.subject to the repository claim:

google.subject=assertion.repository

Optionally, you can use an attribute condition to define additional requirements ID tokens have to meet. For example, the following condition limits access to ID tokens for workflows that use the Git branch main:

assertion.ref=='refs/heads/main'

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

OIDC (AD FS)

Your attribute mappings can use the claims embedded in AD FS access tokens as source attributes.

To authenticate an application, you can use the following attribute mapping:

google.subject=assertion.appid

This mapping sets google.subject to the value of the appid claim, which contains the Client ID of the AD FS application.

Optionally, you can use an attribute condition to define additional requirements AD FS access tokens have to meet. For example, the following condition defines that applications have to use IWA to authenticate to AD FS:

assertion.authmethod=='http://schemas.microsoft.com/ws/2008/06/identity/authenticationmethod/windows'

To control the list of applications can obtain short-lived credentials for Google Cloud, do not define attribute conditions. Instead, use client permissions in AD FS to define which applications are allowed.

SAML

Your attribute mappings can use the <Subject> and <Attribute> elements embedded in the assertion issued by the external identity provider. SAML attributes can be referred to using the following keywords:

  • assertion.subject contains the NameID of the authenticated user found in the <Subject> element.
  • assertion.attributes['ATTRIBUTE_NAME'] contains a list of values for the like-named <Attribute>.

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 NameId with a unique and immutable ID. For these identity providers, consider mapping the NameId attribute to google.subject:

google.subject=assertion.subject

Avoid using an attribute like http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress 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 assertions that contain a custom https://example.com/SAML/Attributes/AllowGcpFederation attribute with a value true:

assertion.attributes['https://idp.com/SAML/Attributes/AllowGcpFederation'][0]=='true'

SAML (AD FS)

Your attribute mappings can use the claims embedded in the assertion issued by AD FS, as described earlier in this guide.

Use the following mapping to let workload identity federation use the Name ID claim from the SAML assertion to uniquely identify the user:

google.subject=assertion.subject

If you've configured your claim issuance policy to include additional claims in SAML assertions, you can add additional mappings. For example:

google.groups=assertion.attributes['http://schemas.microsoft.com/ws/2008/06/identity/claims/groupsid']
attribute.userip=['http://schemas.microsoft.com/2014/09/requestcontext/claims/userip'][0]

Optionally, you can use an attribute condition that all SAML assertions must satisfy. For example, the following condition only permits SAML assertions that include a certain group membership claim:

"S-1-5-6" in google.groups

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 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 Azure, GitHub Actions, or another OIDC-compatible provider.
    • You cannot configure workload identity federation from a SAML 2.0 identity provider using the console. You must use the gcloud CLI to configure workload identity federation from a SAML 2.0 identity provider.

  5. Under Provider details, enter details for your identity provider:

    AWS

    • Provider name: Name for the provider. The name is also used as the provider ID. You cannot change the provider ID later.

    Azure

    • Provider name: Name for the provider. The name is also used as the provider ID. You cannot change the provider ID later.
    • Issuer URL: https://sts.windows.net/TENANT_ID where TENANT_ID is the Tenant ID (GUID) of your Azure AD tenant.
    • Allowed audiences: Application ID URI that you used when you registered the application in Azure AD.

    GitHub Actions

    • Provider name: Name for the provider. The name is also used as the provider ID. You cannot change the provider ID later.
    • Issuer URL: https://token.actions.githubusercontent.com/

    OIDC

    • Provider name: Name for the provider. The name is also used as the provider ID. You cannot change the provider ID later.
    • Issuer URL: Issuer URL of your identity provider.
    • Allowed audiences: Expected audience of ID Tokens.

    OIDC (AD FS)

    • Provider name: Name for the provider. The name is also used as the provider ID. You cannot change the provider ID later.
    • Issuer URL: https://ADFS_DOMAIN/adfs where ADFS_DOMAIN is the public domain name of the AD FS server or farm.

  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"

    GitHub Actions 

    gcloud iam workload-identity-pools providers create-oidc PROVIDER_ID \
    --location="global" \
    --workload-identity-pool="POOL_ID" \
    --issuer-uri="https://token.actions.githubusercontent.com/" \
    --attribute-mapping="MAPPINGS" \
    --attribute-condition="CONDITIONS"

    Replace the following values:

    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:

    OIDC (AD FS) 

    gcloud iam workload-identity-pools providers create-oidc PROVIDER_ID \
    --location="global" \
    --workload-identity-pool="POOL_ID" \
    --issuer-uri="https://ADFS_DOMAIN/adfs" \
    --allowed-audiences="RELYING_PARTY_ID" \
    --attribute-mapping="MAPPINGS" \
    --attribute-condition="CONDITIONS"

    Replace the following values:

    SAML 

    gcloud iam workload-identity-pools providers create-saml PROVIDER_ID \
    --location="global" \
    --workload-identity-pool="POOL_ID" \
    --idp-metadata-path="IDP_METADATA_PATH" \
    --attribute-mapping="MAPPINGS" \
    --attribute-condition="CONDITIONS"

    Replace the following values:

    Example:

    gcloud iam workload-identity-pools providers create-saml example-provider \
    --location="global" \
    --workload-identity-pool="pool-1" \
    --idp-metadata-path="/path/to/idp_metadata.xml" \
    --attribute-mapping="google.subject=assertion.subject,google.groups=assertion.attributes.groups"

    SAML (AD FS) 

    curl -O https://DOMAIN/federationmetadata/2007-06/federationmetadata.xml

gcloud iam workload-identity-pools providers create-saml PROVIDER_ID \
    --location="global" \
    --workload-identity-pool="POOL_ID" \
    --idp-metadata-path="federationmetadata.xml" \
    --attribute-mapping="MAPPINGS" \
    --attribute-condition="CONDITIONS"

    Replace the following:

    Example:

    gcloud iam workload-identity-pools providers create-saml example-provider \
    --location="global" \
    --workload-identity-pool="pool-1" \
    --idp-metadata-path="federationmetadata.xml" \
    --attribute-mapping=google.subject=assertion.subject"

What's next