Configure Workload Identity Federation with Active Directory

This guide describes how to use Workload Identity Federation to let workloadsuse 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:

  • A Windows Service might be configured to log on as a domain user.
  • An IIS application might be configured to run as a group managed serviceaccount (gMSA).

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

Exchanging Active Directory credentials against short-lived Google Cloudcredentials works bychaining two token exchanges:

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

This document shows you how you can automate this process in a way that doesn'trequire changes to your application by using theWorkload 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:

  • SAML: You can let workloads use SAML or WS-Trust to obtain SAML assertions.

    To use SAML or WS-Trust, you create arelying party in AD FS andconfigure a workload identity pool to trust assertions issued for thisrelying party.

    A workload can use its Active Directory user to authenticate to AD FSeither by using the SAML-POST binding or WS-Trust. AD FS then issues a SAMLassertion that contains information about the workload's Active Directoryuser and additional information such as group memberships.

    Using SAML or WS-Trust requires AD FS 3.0, AD FS for Windows Server 2016, ora newer version of AD FS.

  • OIDC: You can let workloads use OIDC to obtain OIDC tokens.

    To use OIDC, you create an OIDC client (native application) and an OIDCresource (Web API) in AD FS. You then configure a workload identity poolto trust access tokens issued for theWeb API.

    A workload can use its Active Directory user and the OAuthclient_credentialsgrant to authenticate to AD FS. AD FS then issues an access token, but no IDtoken.

    The access token contains information about the OIDC client application,but doesn't include any information about the workload's Active Directoryuser or its group memberships.

    Because access tokens don't contain any information about the ActiveDirectory user, using OIDC can be less flexible than using SAML or WS-Trust.

    Using OIDC requires AD FS for Windows Server 2016 or a newerversion of AD FS.

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

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

Register the workload

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

OIDC

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

  • An application registration of typenative application orserver application.

  • An application registration of typeWeb API that corresponds toa workload identity pool provider on Google Cloud.

Registering the client application

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

To register a client application in AD FS, do the following:

  1. Open the AD FS MMC snap-in and navigate toApplication Groups.
  2. ClickAdd application group.

  3. On theWelcome page, do the following:

    1. In the text field, enter a name for the client.
    2. SelectServer application.
    3. ClickNext.

  4. On theServer application page, do the following:

    1. In thetext-field text field, enter a client identifier(Client ID) and a redirect URI.

      If you're only planning to use theclient_credentialsgrant type, the redirect URI won't be used and you can use a URIsuch ashttp://localhost/.

    2. ClickNext.

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

    1. Choose how the client authenticates. To use IWA, setWindows Integrated Authentication toenabled.
    2. Select the domain user that your application is configured torun as.
    3. ClickNext.

  6. On theSummary page, review the settings and clickNext.

  7. ClickClose to dismiss the dialog.

Creating a Web API application for the workload identity pool

Create another application registration of typeWeb API. Thisapplication corresponds to a workload identity pool provider, and you use itto 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 toApplication Groups.
  2. ClickAdd application group.
  3. On theWelcome page, enter a name such asWorkload Identity Federation (test environment)and selectWeb API. Then clickNext.

  4. On theConfigure Web API page, enter a relying party identifier forthe Web API.

    Instead of defining a custom relying party identifier, you can use thefollowing 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:theproject numberof the Google Cloud project that you use to create workload identitypool.
    • WORKLOAD_POOL_ID: an ID of your choice thatidentifies the workload identity pool. You must use the same IDwhen creating the workload identity pool later.
    • WORKLOAD_PROVIDER_ID: an ID of your choice thatidentifies the workload identity pool provider. You must use thesame ID when you create the workload identity pool provider later.

    Formatting the URI this way ensures that the relying party identifieruniquely identifies a workload identity pool provider.

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

  5. ClickNext.

  6. On theApply access control policy page, select an appropriateaccess policy,then clickNext.

  7. On theConfigure application permissions page, add the clientapplication that you created previously. Then clickNext.

  8. On theSummary page, review the settings and clickNext.

  9. ClickClose 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 toRelying party trusts.
  3. ClickAdd relying party trust.
  4. On theWelcome page of theAdd relying party trust wizard,do the following:
    1. SelectClaims aware
    2. ClickStart.
  5. On theSelect data source page, do the following:
    1. SelectEnter data about the relying party manually.
    2. ClickNext.

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

    1. Enter a name for the trust.
    2. ClickNext.

  7. On theConfigure certificate page, clickNext. WhileWorkload Identity Federation supports encrypted SAML, it is notdescribed in this procedure. To learn more, see thegcloud CLI instructions inCreate the identity pool and provider,later in this guide.

  8. On theConfigure URL page, do the following:

    SAML

    Use the following settings:

    • SetEnable support for the SAML 2.0 WebSSO protocol toenabled

    • In theRelying party SAML 2.0 SSO service URL field, enterthe following URL:

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

    WS-Trust

    Keep the default settings

  9. ClickNext.

  10. On theConfigure identifiers page, enter a relying party identifier.

    Instead of defining a custom relying party identifier, you can use the followingURI 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:theproject numberof the Google Cloud project that you use to create workload identitypool.
    • WORKLOAD_POOL_ID: an ID of your choice thatidentifies the workload identity pool. You must use the same IDwhen creating the workload identity pool later.
    • WORKLOAD_PROVIDER_ID: an ID of your choice thatidentifies the workload identity pool provider. You must use thesame ID when creating the workload identity pool provider later.

    Formatting the URI this way ensures that the relying party identifieruniquely identifies a workload identity pool provider.

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

  11. ClickNext.

  12. On theChoose access control policy page, select an appropriateaccess control policy,then clickNext.

  13. On theReady to add trust page, review the settings and clickNext.

  14. On theFinish page, clickClose to dismiss the dialog.

To be compatible with Workload Identity Federation, SAML assertions mustcontain at least oneclaim that uniquely identifies the Active Directory user. Typically, you usetheName ID claim for this purpose, which corresponds to the value oftheNameID element in the SAML assertion.

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

  1. In the list of relying party trusts, select the trust that you justcreated and clickEdit claim issuance policy.
  2. ClickAdd rule
  3. On theChoose rule type page of theAdd transform claim rulewizard, do the following:
    1. SelectTransform an incoming claim.
    2. ClickNext.

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

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

  5. SelectPass through all claim values and clickFinish.

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

  7. ClickOK to close the claim issuance policy dialog.

Configure Workload Identity Federation

You only need to perform these steps once for each Microsoft Active Directorydomain that you want to federate with. You can then use the same workloadidentity pool and provider for multiple workloads and across multipleGoogle 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 theresourcemanager.projects.create permission.Learn how to grant roles.

    Go to project selector

    2. It's best touse 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 Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enable permission.Learn how to grant roles.

    Enable the APIs

Define an attribute mapping and condition

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

Optionally, you canmap additional attributes.You can then refer to these additional attributes when granting access toresources.

OIDC

Your attribute mappings can use theclaims embedded in AD FS access tokensas source attributes.

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

google.subject=assertion.appid

This mapping setsgoogle.subject to the value of theappid claim, whichcontains the Client ID of the AD FS application.

SAML or WS-Trust

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

Use the following mapping to let Workload Identity Federation use theName 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 claimsin 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 anattribute condition. Attribute conditionsare CEL expressions that can check assertion attributes and target attributes.If the attribute condition evaluates totrue for a given credential, thecredential is accepted. Otherwise, the credential is rejected.

OIDC

You can use an attribute condition to restrict which clientscan use Workload Identity Federation to obtain short-livedGoogle Cloud tokens.

For example, the following condition defines that applications have to useIWA 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 credentialfor Google Cloud, don't define attribute conditions. Instead,useclient permissionsin AD FS to define which applications are allowed.

SAML or WS-Trust

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

For example, the following condition only permits SAMLassertions 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, seeManage access to projects, folders, and organizations.

You might also be able to get the required permissions throughcustom roles or otherpredefined roles.

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

Console

  1. In the Google Cloud console, go to theNew workload provider and pool page.

    Go to New workload provider and pool

  2. UnderCreate 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. ClickContinue.

  4. Configure provider settings:

    OIDC

    • Select a provider:OpenID Connect (OIDC).
    • Provider name: the name of the provider. The name is alsoused as the provider ID. You cannot change the provider IDlater.
    • Issuer URL:https://ADFS_DOMAIN/adfswhereADFS_DOMAIN is the public domainname of the AD FS server or farm.

    SAML

    To configure Workload Identity Federation from aSAML 2.0compatible IdP, you can use the gcloud CLIinstructions.

  5. ClickContinue.

  6. UnderConfigure provider attributes, addtheattribute mappings that you've identified previously.

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

  8. ClickSave to create the workload identity pool and provider.

gcloud

  1. Create a new workload identity pool:

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

    Replace the following:

    • WORKLOAD_POOL_ID: Unique ID for the pool.
    • DISPLAY_NAME: Name of the pool.
    • DESCRIPTION: Description of the pool. Thisdescription appears when granting access to pool identities.

  2. Add a workload identity pool provider:

    OIDC

    gcloud iam workload-identity-pools providers create-oidcWORKLOAD_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 prefixgcp- 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.xmlgcloud iam workload-identity-pools providers create-samlWORKLOAD_PROVIDER_ID \    --location="global" \    --workload-identity-pool="POOL_ID" \    --idp-metadata-path="federationmetadata.xml" \    --attribute-mapping="MAPPINGS" \    --attribute-condition="CONDITIONS"

    Replace the following:

    The prefixgcp- 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:

    • In workload identity federation, do the following:
      • Create an asymmetric key pair for your workload identity pool provider.
      • Download a certificate file that contains the public key.
      • Configure your SAML IdP to use the public key to encrypt SAML assertions it issues.
    • In your IdP, do the following:
      • Enable assertion encryption, also known as token encryption.
      • Upload the public key that you created in workload identity federation.
      • Confirm that your IdP produces encrypted SAML assertions.
    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, seeSupported SAML encryption algorithms.

    gcloudiamworkload-identity-poolsproviderskeyscreateKEY_ID\--workload-identity-poolWORKLOAD_POOL_ID\--providerWORKLOAD_PROVIDER_ID\--locationglobal\--useencryption\--specKEY_SPECIFICATION

    Replace the following:

    • KEY_ID: a key name of your choice
    • WORKLOAD_POOL_ID: the pool ID
    • WORKLOAD_PROVIDER_ID: the workforce identity pool provider ID
    • KEY_SPECIFICATION: the key specification, which can be one ofrsa-2048,rsa-3072, andrsa-4096.

    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.

    gcloudiamworkload-identity-poolsproviderskeysdescribeKEY_ID\--workload-identity-poolWORKLOAD_POOL_ID\--providerWORKLOAD_PROVIDER_ID\--locationglobal\--format"value(keyData.key)"\>CERTIFICATE_PATH

    Replace the following:

    • KEY_ID: the key name
    • WORKLOAD_POOL_ID: the pool ID
    • WORKLOAD_PROVIDER_ID: the workforce identity pool provider ID
    • CERTIFICATE_PATH: the path to write the certificate to—for example,saml-certificate.cer orsaml-certificate.pem

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

    1. Move the certificate file to your AD FS server.
    2. On your AD FS server, right-click theStart button (or pressWin+X) and clickWindows PowerShell (Admin).
    3. In PowerShell, run the following command to enable encryption:
              Set-AdfsRelyingPartyTrust `        -TargetNameNAME `        -SamlResponseSignature MessageAndAssertion `        -EncryptionCertificatePATH `        -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:
    gcloudiamworkload-identity-poolsproviderskeysdeleteKEY_ID\--workload-identity-poolWORKLOAD_POOL_ID\--providerWORKLOAD_PROVIDER_ID\--locationglobal

    Replace the following:

    • KEY_ID: the key name
    • WORKLOAD_POOL_ID: the pool ID
    • WORKLOAD_PROVIDER_ID: the workforce identity pool provider ID

    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 signedand exchanged over an encrypted TLS channel. However, the SAMLassertions themselves are not encrypted. By using SAML encryption, you canconfigure AD FS to encrypt assertions so that they can only be decryptedand read by your workload identity pool.

OIDC

This feature is only available when you use SAML.

SAML or WS-Trust

  1. 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:

    • WORKLOAD_PROVIDER_ID: ID of the provider.
    • POOL_ID: the ID of the pool.

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

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

  3. Move the certificate file to your AD FS server.

  4. On your AD FS server, right-clickStart, then clickWindows PowerShell (Admin).

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

    Set-AdfsRelyingPartyTrust `  -TargetNameNAME `  -SamlResponseSignature MessageAndAssertion `  -EncryptionCertificatePATH `  -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, werecommend that you grant direct resource access to the principal. In this case,the principal is the federated user. Some Google Cloud products haveGoogle Cloud API limitations.If your workload calls an API endpoint that has a limitation, you can insteaduse service account impersonation. In this case, the principal is theGoogle Cloud service account, which acts as the identity. You grant accessto the service account on the resource.

Direct resource access

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

Console

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

  1. In the Google Cloud console, go to the Cloud StorageBuckets page.

    Go to Buckets

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

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

  4. Click theGrant access button.

    TheAdd principals dialog appears.

  5. In theNew principals field, enter one or more identitiesthat 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 projectnumber
    • POOL_ID: the workloadpool ID
    • SUBJECT: the individualsubject 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 projectnumber
    • WORKLOAD_POOL_ID: the workloadpool ID
    • GROUP: the groupmapped 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 projectnumber
    • WORKLOAD_POOL_ID: the workloadpool ID
    • ATTRIBUTE_NAME: one of theattributes that was mapped from your IdP
    • ATTRIBUTE_VALUE: the valueof the attribute

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

  7. ClickSave.

gcloud

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

  1. Obtain the project number of the project in which the resourceis 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-bindingBUCKET_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-bindingBUCKET_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-bindingBUCKET_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: theproject 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 thatyou've mappedtogoogle.subject
    • GROUP: the expected value for the attribute thatyou've mappedtogoogle.groups
    • ATTRIBUTE_NAME: the name of a custom attribute inyour attribute mapping
    • ATTRIBUTE_VALUE: the value of the custom attribute in your attribute mapping

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

    Note: You must use the project number, not the project ID, in themember identifier.

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 Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enable permission.Learn how to grant roles.

      Enable the APIs

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

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

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

Console

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

Service Account in the same project

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

    1. Go to theWorkload Identity Pools page.

      Go to Workload Identity Pools

    2. SelectGrant access.

    3. In theGrant access to service account dialog, selectGrant access using Service Account impersonation.

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

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

      • To allow only specific identities of the workloadidentity pool to impersonate the service account, selectOnly identities matching the filter.

      • In theAttribute name list, select the attributethat you want to filter on.

      • In theAttribute value field, enter the expectedvalue of the attribute; for example, if you use anattribute mappinggoogle.subject=assertion.sub, setAttribute name tosubject andAttribute valueto the value of thesub claim in tokens that areissued by your external identity provider.

    6. To save the configuration, clickSave and thenDismiss.

Service account in a different project

Note: Service accounts from different projects won't appear in the"CONNECTED SERVICE ACCOUNTS" section of yourWorkload Identity Pool.

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

    1. Go to theService Accounts page.

      Go to Service Accounts

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

    3. ClickManage access.

    4. ClickAdd principal.

    5. In theNew principal field, enter one of the followingprincipal identifiersfor the identities in your pool that will impersonate theservice account.

      By subject

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

      Replace the following:

      • PROJECT_NUMBER: the projectnumber
      • POOL_ID: the workloadpool ID
      • SUBJECT: the individualsubject 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 projectnumber
      • WORKLOAD_POOL_ID: the workloadpool ID
      • GROUP: the groupmapped 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 projectnumber
      • WORKLOAD_POOL_ID: the workloadpool ID
      • ATTRIBUTE_NAME: one of theattributes that was mapped from your IdP
      • ATTRIBUTE_VALUE: the valueof the attribute

      By pool

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

      Replace the following:

      • PROJECT_NUMBER: the projectnumber
      • WORKLOAD_POOL_ID: the workloadpool ID

    6. InSelect a role, select the Workload Identity Userrole (roles/iam.workloadIdentityUser).

    7. To save the configuration, clickSave.

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

By subject

gcloud iam service-accounts add-iam-policy-bindingSERVICE_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-bindingSERVICE_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-bindingSERVICE_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: theproject 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 thatyou've mappedtogoogle.subject
  • GROUP: the expected value for the attribute thatyou've mappedtogoogle.groups
  • ATTRIBUTE_NAME: the name of a custom attribute inyour attribute mapping
  • ATTRIBUTE_VALUE: the value of the custom attribute in your attribute mapping

Note: You must use the project number, not the project ID, in themember identifier.

Create a credential configuration

You can letCloud Client Libraries and toolssuch as the gcloud CLI and Terraform use Active Directory credentialsto authenticate to Google Cloud by using theWorkload Authenticator for Windows.

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

  1. When the tool or library needs a new credential, it launches the WorkloadAuthenticator in the background.
  2. The Workload Authenticator uses OIDC, SAML, or WS-Trust to obtain a new tokenor 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 againstshort-lived Google Cloud credentials by usingWorkload Identity Federation.

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

  • Where to find the Workload Authenticator for Windows executable (wwauth.exe),and which parameters to run it with
  • Which workload identity pool and provider to use
  • Which service account to impersonate

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

  1. Right-click theStart button (or pressWin+X) and clickWindows PowerShell.

  2. Download theWorkload Authenticator for Windowsand 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 WorkloadAuthenticator for Windows, the file contains the path to its executable. Ifyou later delete or move the executable, workloads won't be able to find anduse the executable.

  3. Launchwwauth.exe:

    & ${env:ProgramData}\wwauth.exe

    A configuration dialog opens:

    Workload Authenticator

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

    • Issuer URI of AD FS server: Public URI of your AD FS server or farm.

      https://ADFS_DOMAIN/adfs/

      ReplaceADFS_DOMAIN with the public domain nameof your AD FS server or server farm.

    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 theserver 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 theWorkload identity tab and enter the following settings:

    • Project number: Project number of the projectthat contains the workload identity pool
    • Pool ID: ID of the workload identity pool
    • Provider ID: ID of the workload identity pool provider
    • Impersonate service account:enabled, if you use service accountimpersonation
    • Email address: Email address of the service account, if you useservice account impersonation

  6. Select theAD FS tab and verify that theRelying Party ID fieldnow contains the URL of your workload identity pool provider.

  7. ClickApply and choose a file location to save the credential configurationfile to.

    Unlike aservice account key,a credential configuration file doesn't contain any secrets and doesn't needto be kept confidential. Details about the credential configuration file areavailable athttps://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 ActiveDirectory user of the workload or the user you're currently logged in with.

  2. To test the configuration with your current user, clickTest.

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

    The tool now tries to authenticate to Google Cloud by performingthe 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 accountimpersonation.

    If the authentication succeeds, you see the messageTest completed successfully:

    Test result

Use the credential configuration to access Google Cloud

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

  1. Right-click theStart button and clickRun.
  2. Entersysdm.cpl and clickOK.
  3. On theAdvanced tab, clickEnvironment variables.

  4. In theSystem variables section, add two new variables:

    NameValue
    GOOGLE_APPLICATION_CREDENTIALSPath to the credential configuration file
    GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES1

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

  5. ClickOK.

  6. Use a client library or tool that supports Workload Identity Federationand canfind credentials automatically:

    C++

    TheGoogle Cloud Client Libraries for C++support Workload Identity Federation since versionv2.6.0.To use Workload Identity Federation, you must build the client librarieswith version 1.36.0 or later of gRPC.

    Go

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

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

    cd$GOPATH/src/cloud.google.com/gogolist-mgolang.org/x/oauth2

    Java

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

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

    mvndependency:list-DincludeArtifactIds=google-auth-library-oauth2-http

    Node.js

    Client libraries for Node.js support Workload Identity Federation if they use version7.0.2 or later of thegoogle-auth-library package.

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

    npmlistgoogle-auth-library

    When you create aGoogleAuth object, you can specify a project ID, or you canallowGoogleAuth to find the project ID automatically. To find the project IDautomatically, the service account in the configuration file must have theBrowser role (roles/browser), or a role with equivalent permissions, on yourproject. For details, see theREADME for thegoogle-auth-library package.

    Python

    Client libraries for Python support Workload Identity Federation if they use version1.27.0 or later of thegoogle-auth package.

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

    pipshowgoogle-auth

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

    gcloud

    To authenticate using Workload Identity Federation, use thegcloud auth login command:

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

    ReplaceFILEPATH with the path to thecredential configuration file.

    Support for Workload Identity Federation in gcloud CLI is available inversion 363.0.0 and later versions of the gcloud CLI.

    Terraform

    TheGoogle Cloud providersupports 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 thegcloud auth login command, as follows:

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

    ReplaceFILEPATH with the path to thecredential configuration file.

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

What's next

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2026-02-19 UTC.