Console
Start free

Configure Workload Identity Federation with Active Directory

This guide describes how to use Workload Identity Federation to let workloads use Active Directory credentials to authenticate to Google Cloud.

If you're running Windows Server workloads in an Active Directory environment, then these workloads might have access to Active Directory credentials. For example:

By using Workload Identity Federation in combination with Active Directory Federation Services (AD FS), you can let these workloads exchange their Active Directory Kerberos credentials for short-lived Google Cloud credentials. Workloads can use these short-lived credentials to access Google Cloud APIs.

Exchanging Active Directory credentials against short-lived Google Cloud credentials works by chaining two token exchanges:

  1. A workload uses OpenID Connect (OIDC), SAML-POST, or WS-Trust to request an OIDC token or SAML assertion from AD FS. To authenticate to AD FS, the workload uses integrated Windows authentication (IWA) and its existing Active Directory credentials.
  2. The workload then uses Workload Identity Federation to exchange the OIDC token or SAML assertion against an Security Token Service token and, optionally, to impersonate a Google Cloud service account.

This document shows you how you can automate this process in a way that doesn't require changes to your application by using the Workload Authenticator for Windows.

Prepare AD FS

You only need to perform these steps once.

Select a protocol

The way to prepare AD FS depends on which protocol you want to use:

For sign-in, your IdP must provide signed authentication information: OIDC IdPs must provide a JWT, and SAML IdP responses must be signed.

IWA prerequisites

This section describes IWA prerequisites that are required in order to use this guide.

If you haven't used IWA with AD FS before, make sure that you meet the following prerequisites:

Register the workload

To register your workload in AD FS, do the following:

OIDC

To let workloads use OIDC, you need two application registrations in AD FS:

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

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

Registering the client application

Create a client application that represents the workload. If you have multiple workloads that need access to Google Cloud, you might need to create multiple client applications.

To register a client application in AD FS, 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, do the following:

    1. In the text field, enter a name for the client.
    2. Select Server application.
    3. Click Next.

  4. On the Server application page, do the following:

    1. In the text-field text field, 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/.

    2. Click Next.

  5. On the Configure application credentials page, do the following:

    1. Choose how the client authenticates. To use IWA, set Windows Integrated Authentication to enabled.
    2. Select the domain user that your application is configured to run as.
    3. 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 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, 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/WORKLOAD_POOL_ID/providers/WORKLOAD_PROVIDER_ID

    Replace the following:

    • PROJECT_NUMBER: the project number of the Google Cloud project that you use to create workload identity pool.
    • WORKLOAD_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.
    • WORKLOAD_PROVIDER_ID: an ID of your choice that identifies the workload identity pool provider. You must use the same ID when you create the workload identity pool provider later.

    Formatting the URI this way 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 or WS-Trust

Create a relying party trust in AD FS:

  1. Open the AD FS MMC snap-in.
  2. Navigate to Relying party trusts.
  3. Click Add relying party trust.
  4. On the Welcome page of the Add relying party trust wizard, do the following:
    1. Select Claims aware
    2. Click Start.
  5. On the Select data source page, do the following:
    1. Select Enter data about the relying party manually.
    2. Click Next.

  6. On the Specify display name page, do the following:

    1. Enter a name for the trust.
    2. Click Next.

  7. On the Configure certificate page, click Next. While Workload Identity Federation supports encrypted SAML, it is not described in this procedure. To learn more, see the gcloud CLI instructions in Create the identity pool and provider, later in this guide.

  8. On the Configure URL page, do the following:

    SAML

    Use the following settings:

    • Set Enable support for the SAML 2.0 WebSSO protocol to enabled

    • In the Relying party SAML 2.0 SSO service URL field, enter the following URL:

      https://sts.googleapis.com/v1/token

    WS-Trust

    Keep the default settings

  9. Click Next.

  10. 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/WORKLOAD_POOL_ID/providers/WORKLOAD_PROVIDER_ID

    Replace the following:

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

    Formatting the URI this way 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.

  11. Click Next.

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

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

  14. 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, do the following:
    1. Select Transform an incoming claim.
    2. 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.

Configure Workload Identity Federation

You only need to perform these steps once for each Microsoft Active Directory domain that you want to federate with. You can then use the same workload identity pool and provider for multiple workloads and across multiple Google Cloud projects.

To start configuring Workload Identity Federation, do the following:

  1. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

    2. It's best to use a dedicated project to manage workload identity pools and providers.

  2. Verify that billing is enabled for your Google Cloud project.

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

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the APIs

Define an attribute mapping and condition

The environment-specific credentials of your Active Directory workload contain multiple attributes, and you must decide which attribute you want to use as the subject identifier (google.subject) in Google Cloud.

Optionally, you can map additional attributes. You can then refer to these additional attributes when granting access to resources.

OIDC

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.

SAML or WS-Trust

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, 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.

OIDC

You can use an attribute condition to restrict which clients can use Workload Identity Federation to obtain short-lived Google Cloud tokens.

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 that can obtain short-lived credential for Google Cloud, don't define attribute conditions. Instead, use client permissions in AD FS to define which applications are allowed.

SAML or WS-Trust

You can use an attribute condition to restrict which Active Directory users can use Workload Identity Federation to obtain short-lived Google Cloud tokens.

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

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:

For more information about granting roles, see Manage access to projects, folders, and organizations.

You might also be able to get the required permissions through custom roles or other predefined roles.

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.

Console

  1. In the Google 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. Configure provider settings:

    OIDC

    • Select a provider: OpenID Connect (OIDC).
    • Provider name: the name of 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.

    SAML

    To configure Workload Identity Federation from a SAML 2.0 compatible IdP, you can use the gcloud CLI instructions.

  5. Click Continue.

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

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

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

gcloud

  • Create a new workload identity pool:

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

    Replace the following:

    • Add a workload identity pool provider:

    OIDC 

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

    Replace the following:

    The prefix gcp- is reserved and can't be used in a workforce identity pool or workforce identity pool provider ID.

    SAML or WS-Trust 

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

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

    Replace the following:

    The prefix gcp- is reserved and can't be used in a workforce identity pool or workforce identity pool provider ID.

    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"

    Optional: Accept encrypted SAML assertions from your IdP

    To enable your SAML 2.0 IdP to produce encrypted SAML assertions that can be accepted by workload identity federation, do the following:

    Note that, even with SAML encryption provider keys configured, workload identity federation can still process a plaintext assertion.

    Create workload identity federation SAML assertion encryption keys

    This section guides you through creating an asymmetric key pair that enables workload identity federation to accept encrypted SAML assertions.

    Google Cloud uses the private key to decrypt the SAML assertions that your IdP issues. To create an asymmetric key pair for use with SAML encryption, run the following command. To learn more, see Supported SAML encryption algorithms. 

    gcloud iam workload-identity-pools providers keys create KEY_ID \
    --workload-identity-pool WORKLOAD_POOL_ID \
    --provider WORKLOAD_PROVIDER_ID \
    --location global \
    --use encryption \
    --spec KEY_SPECIFICATION

    Replace the following:

    After the key pair is created, to download the public key into a certificate file, execute the following command. Only workload identity federation has access to the private key. 

    gcloud iam workload-identity-pools providers keys describe KEY_ID \
    --workload-identity-pool WORKLOAD_POOL_ID \
    --provider WORKLOAD_PROVIDER_ID \
    --location global \
    --format "value(keyData.key)" \
    > CERTIFICATE_PATH

    Replace the following:

    Configure your SAML 2.0-compliant IdP to issue encrypted SAML assertions

  • Move the certificate file to your AD FS server.
  • On your AD FS server, right-click the Start button (or press Win+X) and click Windows PowerShell (Admin).
    • In PowerShell, run the following command to enable encryption: 
            Set-AdfsRelyingPartyTrust `
        -TargetName NAME `
        -SamlResponseSignature MessageAndAssertion `
        -EncryptionCertificate PATH `
        -EncryptClaims $True
    Replace the following:
  • NAME: the name of your relying party trust
    • PATH: the path of the certificate file

    WS-Trust users: This feature is only available when you use SAML.

    After you configure your IdP to encrypt SAML assertions, we recommend that you check to make sure that the assertions it generates are actually encrypted. Even with SAML assertion encryption configured, workload identity federation can still process plaintext assertions.

    Delete workload identity federation encryption keys

    To delete SAML encryption keys run the following command: 
      gcloud iam workload-identity-pools providers keys delete KEY_ID \
      --workload-identity-pool WORKLOAD_POOL_ID \
      --provider WORKLOAD_PROVIDER_ID \
      --location global

    Replace the following:

    Supported SAML encryption algorithms

    Workload identity federation supports the following key transport algorithms:

    Workload identity federation supports the following block encryption algorithms:

    Optional: Enable SAML encryption

    SAML assertions that are issued by AD FS are cryptographically signed and exchanged over an encrypted TLS channel. However, the SAML assertions themselves are not encrypted. By using SAML encryption, you can configure AD FS to encrypt assertions so that they can only be decrypted and read by your workload identity pool.

    OIDC

    This feature is only available when you use SAML.

    SAML or WS-Trust

  • Create an encryption key for your workload identity pool provider:

    gcloud iam workload-identity-pools providers keys create rsa2048 \
    --workload-identity-pool=POOL_ID \
    --provider=WORKLOAD_PROVIDER_ID \
    --location=global \
    --use=ENCRYPTION \
    --spec=RSA_2048

    Replace the following:

    The key pair is stored and managed by Workload Identity Federation. You can export the public key, but only Workload Identity Federation can access the private key.

  • Export a certificate that contains the public key:

    gcloud iam workload-identity-pools providers keys describe rsa2048 \
    --workload-identity-pool=POOL_ID \
    --provider=WORKLOAD_PROVIDER_ID \
    --location=global \
    --format="value(keyData.key)" > workload-identity-federation.cer

  • Move the certificate file to your AD FS server.

  • On your AD FS server, right-click Start, then click Windows PowerShell (Admin).

    • In PowerShell, modify the relying party trust so that it uses encryption:

    Set-AdfsRelyingPartyTrust `
  -TargetName NAME `
  -SamlResponseSignature MessageAndAssertion `
  -EncryptionCertificate PATH `
  -EncryptClaims $True

    Replace the following:

  • NAME: the name of your relying party trust
    • PATH: the path of the certificate file

    Authenticate a workload

    You must perform these steps once per workload.

    Allow your external workload to access Google Cloud resources

    To provide your workload with access to Google Cloud resources, we recommend that you grant direct resource access to the principal. In this case, the principal is the federated user. Some Google Cloud products have Google Cloud API limitations. If your workload calls an API endpoint that has a limitation, you can instead use service account impersonation. In this case, the principal is the Google Cloud service account, which acts as the identity. You grant access to the service account on the resource.

    Direct resource access

    You can grant access to a federated identity directly on resources by using the Google Cloud console or the gcloud CLI.

    Console

    To use the Google Cloud console to grant IAM roles directly on a resource, you must go to the resource's page, and then grant the role. The following example shows you how to go to the Cloud Storage page and grant the role Storage Object Viewer (roles/storage.objectViewer) to a federated identity directly on a Cloud Storage bucket.

    1. In the Google Cloud console, go to the Cloud Storage Buckets page.

      Go to Buckets

    2. In the list of buckets, click the name of the bucket for which you want to grant the role.

    3. Select the Permissions tab near the top of the page.

    4. Click the Grant access button.

      The Add principals dialog appears.

    5. In the New principals field, enter one or more identities that need access to your bucket.

      By subject 

      principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT

      Replace the following:

      • PROJECT_NUMBER: the project number
      • POOL_ID: the workload pool ID
      • SUBJECT: the individual subject mapped from your IdP—for example, administrator@example.com

      By group 

      principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/group/GROUP

      Replace the following:

      • PROJECT_NUMBER: the project number
      • WORKLOAD_POOL_ID: the workload pool ID
      • GROUP: the group mapped from your IdP—for example: administrator-group@example.com

      By attribute 

      principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE

      Replace the following:

      • PROJECT_NUMBER: the project number
      • WORKLOAD_POOL_ID: the workload pool ID
      • ATTRIBUTE_NAME: one of the attributes that was mapped from your IdP
      • ATTRIBUTE_VALUE: the value of the attribute

    6. Select a role (or roles) from the Select a role drop-down menu. The roles you select appear in the pane with a short description of the permissions they grant.

    7. Click Save.

    gcloud

    To use the gcloud CLI to grant IAM roles on a resource in a project, do the following:

    1. Obtain the project number of the project in which the resource is defined.

      gcloud projects describe $(gcloud config get-value core/project) --format=value\(projectNumber\)

    2. Grant access to the resource.

      To use the gcloud CLI to grant the role Storage Object Viewer (roles/storage.objectViewer) to external identities that meet certain criteria, run the following command.

      By subject

      gcloud storage buckets add-iam-policy-binding BUCKET_ID \
    --role=roles/storage.objectViewer \
    --member="principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT"

      By group

      gcloud storage buckets add-iam-policy-binding BUCKET_ID \
    --role=roles/storage.objectViewer \
    --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/group/GROUP"

      By attribute

      gcloud storage buckets add-iam-policy-binding BUCKET_ID \
    --role=roles/storage.objectViewer \
    --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE"

      Replace the following:

      • BUCKET_ID: the bucket on which to grant access
      • PROJECT_NUMBER: the project number. of the project that contains the workload identity pool
      • POOL_ID: the pool ID of the workload identity pool
      • SUBJECT: the expected value for the attribute that you've mapped to google.subject
      • GROUP: the expected value for the attribute that you've mapped to google.groups
      • ATTRIBUTE_NAME: the name of a custom attribute in your attribute mapping
      • ATTRIBUTE_VALUE: the value of the custom attribute in your attribute mapping

      You can grant roles on any Google Cloud resource that supports IAM allow policies.

    Service account impersonation

    1. To create a service account for the external workload, do the following:

      1. Enable the IAM, Security Token Service, and Service Account Credentials APIs.

        Roles required to enable APIs

        To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

        Enable the APIs

      2. Create a service account that represents the workload. We recommend that you use a dedicated service account for each workload. The service account doesn't need to be in the same project as the workload identity pool, but you must refer to the project that contains the service account.

      3. Grant the service account access to resources that you want external identities to access.

    2. To let the federated identity impersonate the service account, do the following:

    Console

    To use the Google Cloud console to grant IAM roles to a federated identity with service account, do the following:

    Service Account in the same project

    1. To grant access using service account impersonation for a service account in the same project, do the following:

      1. Go to the Workload Identity Pools page.

        Go to Workload Identity Pools

      2. Select Grant access.

      3. In the Grant access to service account dialog, select Grant access using Service Account impersonation.

      4. In the Service accounts list, select the service account for the external identities to impersonate, and do the following:

      5. To choose which identities in the pool can impersonate the service account, perform one of the following actions:

        • To allow only specific identities of the workload identity pool to impersonate the service account, select Only identities matching the filter.

        • In the Attribute name list, select the attribute that you want to filter on.

        • In the Attribute value field, enter the expected value of the attribute; for example, if you use an attribute mapping google.subject=assertion.sub, set Attribute name to subject and Attribute value to the value of the sub claim in tokens that are issued by your external identity provider.

      6. To save the configuration, click Save and then Dismiss.

    Service account in a different project

    1. To grant access using service account impersonation for a service account in a different project, do the following:

      1. Go to the Service Accounts page.

        Go to Service Accounts

      2. Select the service account that you want to impersonate.

      3. Click Manage access.

      4. Click Add principal.

      5. In the New principal field, enter one of the following principal identifiers for the identities in your pool that will impersonate the service account.

        By subject 

        principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT

        Replace the following:

        • PROJECT_NUMBER: the project number
        • POOL_ID: the workload pool ID
        • SUBJECT: the individual subject mapped from your IdP—for example, administrator@example.com

        By group 

        principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/group/GROUP

        Replace the following:

        • PROJECT_NUMBER: the project number
        • WORKLOAD_POOL_ID: the workload pool ID
        • GROUP: the group mapped from your IdP—for example: administrator-group@example.com

        By attribute 

        principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE

        Replace the following:

        • PROJECT_NUMBER: the project number
        • WORKLOAD_POOL_ID: the workload pool ID
        • ATTRIBUTE_NAME: one of the attributes that was mapped from your IdP
        • ATTRIBUTE_VALUE: the value of the attribute

        By pool

        principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/*

        Replace the following:

        • PROJECT_NUMBER: the project number
        • WORKLOAD_POOL_ID: the workload pool ID

      6. In Select a role, select the Workload Identity User role (roles/iam.workloadIdentityUser).

      7. To save the configuration, click Save.

    gcloud

    To grant the Workload Identity User role (roles/iam.workloadIdentityUser) to a federated principal or principal set, run the following command. To learn more about Workload Identity Federation principal identifiers, see Principal types.

    By subject

    gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_EMAIL \
    --role=roles/iam.workloadIdentityUser \
    --member="principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT"

    By group

    gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_EMAIL \
    --role=roles/iam.workloadIdentityUser \
    --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/group/GROUP"

    By attribute

    gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_EMAIL \
    --role=roles/iam.workloadIdentityUser \
    --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE"

    Replace the following:

    • SERVICE_ACCOUNT_EMAIL: the email address of the service account
    • PROJECT_NUMBER: the project number. of the project that contains the workload identity pool
    • POOL_ID: the pool ID of the workload identity pool
    • SUBJECT: the expected value for the attribute that you've mapped to google.subject
    • GROUP: the expected value for the attribute that you've mapped to google.groups
    • ATTRIBUTE_NAME: the name of a custom attribute in your attribute mapping
    • ATTRIBUTE_VALUE: the value of the custom attribute in your attribute mapping

    Create a credential configuration

    You can let Cloud Client Libraries and tools such as the gcloud CLI and Terraform use Active Directory credentials to authenticate to Google Cloud by using the Workload Authenticator for Windows.

    Workload Authenticator for Windows is an open-source tool that acts as a plugin for the Cloud Client Libraries and tools such as the gcloud CLI:

    1. When the tool or library needs a new credential, it launches the Workload Authenticator in the background.
    2. The Workload Authenticator uses OIDC, SAML, or WS-Trust to obtain a new token or SAML assertion from AD FS and passes it back to the tool or library.
    3. The tool or library then uses exchanges the token or SAML assertion against short-lived Google Cloud credentials by using Workload Identity Federation.

    To use the Workload Authenticator for Windows, you must create a credential configuration file. This file defines the following:

    To create a credential configuration file, do the following on the Windows Server that runs your workload:

    1. Right-click the Start button (or press Win+X) and click Windows PowerShell.

    2. Download the Workload Authenticator for Windows and save it to a location that's accessible by your workload:

      (New-Object Net.WebClient).DownloadFile(
  "https://github.com/GoogleCloudPlatform/iam-windows-authenticator/releases/latest/download/wwauth.exe",
  "${env:ProgramData}\wwauth.exe")

      If you create a credential configuration file by using the Workload Authenticator for Windows, the file contains the path to its executable. If you later delete or move the executable, workloads won't be able to find and use the executable.

    3. Launch wwauth.exe:

      & ${env:ProgramData}\wwauth.exe

      A configuration dialog opens:

      Workload Authenticator

    4. Select the AD FS tab and enter the following settings:

      The next settings depend on the protocol you want to use:

      OIDC

      • Protocol: AdfsOidc
      • Relying party ID: Keep the default.
      • Client ID Client identifier (Client ID) of the server application in AD FS.

      SAML

      • Protocol: AdfsSamlPost
      • Assertion consumer service URL: https://sts.googleapis.com/v1/token.
      • Sign requests using certificate: disabled

      WS-Trust

      • Protocol: AdfsWsTrust

    5. Select the Workload identity tab and enter the following settings:

    6. Select the AD FS tab and verify that the Relying Party ID field now contains the URL of your workload identity pool provider.

    7. Click Apply and choose a file location to save the credential configuration file to.

      Unlike a service account key, a credential configuration file doesn't contain any secrets and doesn't need to be kept confidential. Details about the credential configuration file are available at https://google.aip.dev/auth/4117.

    You're now ready to test your configuration:

    1. Select an Active Directory user to test with. This can be the Active Directory user of the workload or the user you're currently logged in with.

    2. To test the configuration with your current user, click Test.

      To test with a different user, select Test > Test configuration as user and enter the credentials for the user.

      The tool now tries to authenticate to Google Cloud by performing the following steps:

      1. Acquire an OIDC token or SAML assertion from AD FS.
      2. Obtain a Google Security Token Service token.
      3. Impersonate the service account, if you use service account impersonation.

      If the authentication succeeds, you see the message Test completed successfully:

      Test result

    Use the credential configuration to access Google Cloud

    To let tools and client libraries use your credential configuration, do the following on the Windows Server that runs your workload:

    1. Right-click the Start button and click Run.
    2. Enter sysdm.cpl and click OK.
    3. On the Advanced tab, click Environment variables.

    4. In the System variables section, add two new variables:

      Name Value
      GOOGLE_APPLICATION_CREDENTIALS Path to the credential configuration file
      GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES 1

      We highly recommended that you edit the credential configuration file, and use a regional Security Token Service endpoint, if it is available.

    5. Click OK.

    6. Use a client library or tool that supports Workload Identity Federation and can find credentials automatically:

      C++

      The Google Cloud Client Libraries for C++ support Workload Identity Federation since version v2.6.0. To use Workload Identity Federation, you must build the client libraries with version 1.36.0 or later of gRPC.

      Go

      Client libraries for Go support Workload Identity Federation if they use version v0.0.0-20210218202405-ba52d332ba99 or later of the golang.org/x/oauth2 module.

      To check which version of this module your client library uses, run the following commands:

      cd $GOPATH/src/cloud.google.com/go
go list -m golang.org/x/oauth2

      Java

      Client libraries for Java support Workload Identity Federation if they use version 0.24.0 or later of the com.google.auth:google-auth-library-oauth2-http artifact.

      To check which version of this artifact your client library uses, run the following Maven command in your application directory:

      mvn dependency:list -DincludeArtifactIds=google-auth-library-oauth2-http

      Node.js

      Client libraries for Node.js support Workload Identity Federation if they use version 7.0.2 or later of the google-auth-library package.

      To check which version of this package your client library uses, run the following command in your application directory:

      npm list google-auth-library

      When you create a GoogleAuth object, you can specify a project ID, or you can allow GoogleAuth to find the project ID automatically. To find the project ID automatically, the service account in the configuration file must have the Browser role (roles/browser), or a role with equivalent permissions, on your project. For details, see the README for the google-auth-library package.

      Python

      Client libraries for Python support Workload Identity Federation if they use version 1.27.0 or later of the google-auth package.

      To check which version of this package your client library uses, run the following command in the environment where the package is installed:

      pip show google-auth

      To specify a project ID for the authentication client, you can set the GOOGLE_CLOUD_PROJECT environment variable, or you can allow the client to find the project ID automatically. To find the project ID automatically, the service account in the configuration file must have the Browser role (roles/browser), or a role with equivalent permissions, on your project. For details, see the user guide for the google-auth package.

      gcloud

      To authenticate using Workload 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 Workload Identity Federation in gcloud CLI is available in version 363.0.0 and later versions of the gcloud CLI.

      Terraform

      The Google Cloud provider supports Workload Identity Federation if you use version 3.61.0 or later:

      terraform {
  required_providers {
    google = {
      source  = "hashicorp/google"
      version = "~> 3.61.0"
    }
  }
}

      bq

      To authenticate using Workload Identity Federation, use the gcloud auth login command, as follows:

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

      Replace FILEPATH with the path to the credential configuration file.

      Support for Workload Identity Federation in bq is available in version 390.0.0 and later versions of the gcloud CLI.

    What's next