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:

  • 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 service account (gMSA).

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:

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

    To use SAML or WS-Trust, you create a relying party in AD FS and configure a workload identity pool to trust assertions issued for this relying party.

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

    Using SAML or WS-Trust requires AD FS 3.0, AD FS for Windows Server 2016, or a 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 OIDC resource (Web API) in AD FS. You then configure a workload identity pool to trust access tokens issued for the Web API.

    A workload can use its Active Directory user and the OAuth client_credentials grant to authenticate to AD FS. AD FS then issues an access token, but no ID token.

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

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

    Using OIDC requires AD FS for Windows Server 2016 or a newer version 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 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