Configure workforce identity federation with Azure AD and sign in users

Stay organized with collections Save and categorize content based on your preferences.

This guide shows you how to configure workforce identity federation using Azure AD as an identity provider (IdP), manage access, and sign in users to access Google Cloud services that support workforce identity federation.

Before you begin

  1. You must have a Google Cloud organization set up.

  2. Identify a billing/quota project.

    To set the Google Cloud project that is billed and charged quota for operations performed in the gcloud CLI, execute the following command:

    gcloud config set billing/quota_project PROJECT_ID

    Replace PROJECT_ID with the project ID.

  3. Create a new app. As a best practice, we recommend that you create a new application in Azure AD and use only the application to obtain Google Cloud credentials. To create a web app for user sign-in with Azure AD and enable your app to receive tokens from Azure AD, see Register an app by using the Azure portal.

  4. Configure groups claims. To configure the groups claims passed in the ID token, see Configuring groups optional claims. The groups claims are used for access control in steps that are later in this guide. In this guide we use "Directory roles" as groups. Alternatively, Google Cloud supports arbitrary claims. To set up custom claims with Azure AD, see Customize claims emitted in tokens for a specific app in a tenant.

  5. Install the Google Cloud CLI, then initialize it by running the following command:

    gcloud init

Required roles

To get the permissions that you need to configure workforce identity federation, ask your administrator to grant you the Workforce Identity Pool Admin (roles/iam.workforcePoolAdmin) IAM role on the organization. For more information about granting roles, see Manage access.

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

Create the workforce identity federation pool

To create the workforce pool, run the following command:

gcloud iam workforce-pools create WORKFORCE_POOL_ID \
    --organization=ORGANIZATION_ID \
    --description="DESCRIPTION" \

Replace the following:

  • WORKFORCE_POOL_ID: the ID for your workforce pool
  • ORGANIZATION_ID: the numeric organization ID
  • DESCRIPTION: a description of the workforce pool

Get values from Azure AD

To configure the OIDC workforce pool provider in the workforce pool, get the following values from Azure AD:

  • Unique provider ID
  • Workforce pool ID to connect the IdP to
  • Client ID: The Application ID (client id) that the Azure portal - App registrations experience assigned to your app.
  • The issuer URI: Must be a valid URI format. Must start with https. You can find the issuer URI by accessing the OIDC metadata doc. You can find the metadata doc on Azure Portal of your app through "Endpoints" -> "OpenID Connect metadata document". Set --issuer-uri to the value of "issuer" in the JSON.
  • An optional user-friendly display name
  • An optional description

Define attribute mapping and attribute conditions

Azure AD issues credentials that contain one or more claims. An attribute mapping lets you map claims to attributes to the predefined target attributes recognized by workforce identity federation.

For more information, see Attribute mapping and Attribute conditions.

Create the Azure AD workforce pool provider

To create the OIDC workforce pool provider, execute the following command:

gcloud iam workforce-pools providers create-oidc PROVIDER_ID \
    --workforce-pool=WORKFORCE_POOL_ID \
    --display-name="DISPLAY_NAME" \
    --description="DESCRIPTION" \
    --issuer-uri="OIDC_ISSUER_URL" \
    --client-id="OIDC_CLIENT_ID" \
    --attribute-mapping="ATTRIBUTE_MAPPING" \
    --attribute-condition="ATTRIBUTE_CONDITION" \

Replace the following:

  • PROVIDER_ID: the provider ID
  • WORKFORCE_POOL_ID: the workforce pool ID
  • DISPLAY_NAME: the display name; for example, idp-eu-employees
  • DESCRIPTION: the description; for example, EU employees
  • OIDC_ISSUER_URL: the issuer URL of your IdP
  • OIDC_CLIENT_ID: the OIDC client ID
  • ATTRIBUTE_MAPPING: an attribute mapping; for example: google.subject=assertion.sub, google.groups=assertion.groups
  • ATTRIBUTE_CONDITION: optional attribute conditions, for example, to limit the ipaddr attribute to a certain IP range you can set the condition assertion.ipaddr.startsWith('98.11.12.').

Manage access

You can define IAM policies for single identities, group of identities, or an entire pool. For more information, see Represent workforce identity pool users in IAM policies.

To grant the Storage Admin (roles/storage.admin) role to all identities within the group GROUP_ID for project my-project, execute the following command:

gcloud projects add-iam-policy-binding my-project \
    --role="roles/storage.admin" \

Sign in to Azure AD with gcloud CLI

To sign in to Azure AD with the gcloud CLI, do the following:

  1. Follow the steps in Send the sign-in request. Sign the user into your app with Azure AD using OIDC.

  2. Copy the ID token from the id_token parameter of the redirect URL and save it to a file in a secure location on your local machine where. In later step, you set PATH_TO_OIDC_ID_TOKEN to the path to this file.

  3. Generate a configuration service file similar to the one below by running the following command:

    gcloud iam workforce-pools create-cred-config \
        locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \
        --subject-token-type=urn:ietf:params:oauth:token-type:id_token \
        --credential-source-file=PATH_TO_OIDC_ID_TOKEN \
        --workforce-pool-user-project=WORKFORCE_POOL_USER_PROJECT \

    Replace the following:

    • WORKFORCE_POOL_ID: the workforce pool ID.
    • PATH_TO_OIDC_ID_TOKEN: the path to the file location where the IdP token is stored.
    • WORKFORCE_POOL_USER_PROJECT: the project number or ID used for quota and billing. The principal must have permission on this project.

    When the command completes, the following config file is created by Azure AD:

      "type": "external_account",
      "audience": "//",
      "subject_token_type": "urn:ietf:params:oauth:token-type:id_token",
      "token_url": "",
      "workforce_pool_user_project": "WORKFORCE_POOL_USER_PROJECT",
      "credential_source": {
        "file": "PATH_TO_OIDC_CREDENTIALS"
  4. Open the gcloud CLI and run the following command:

    gcloud auth login --cred-file=PATH_TO_OIDC_CREDENTIALS

    Replace PATH_TO_OIDC_CREDENTIALS with the path to the output file from a previous step.

    The gcloud CLI transparently posts your credentials to the Security Token Service endpoint. In the endpoint, it is exchanged for temporary Google Cloud access tokens.

    You can now execute gcloud CLI commands to Google Cloud.

Test access

You now have access to Google Cloud products that support workforce identity federation and to which you are granted access. For example, you can list Cloud Storage buckets and objects in the project you have access to.

To demonstrate this, execute the following command:

gcloud alpha storage ls --project=my-project

The principal must have the permission on the billing/quota project: PROJECT_ID.

What's next