Configure Workload Identity Federation with AWS or Azure VMs

This guide describes how to use Workload Identity Federation to let AWS and Azure VM workloads authenticate to Google Cloud without a service account key.

If you use Amazon Elastic Kubernetes Service (Amazon EKS) or Azure Kubernetes Service (AKS), see Configure Workload Identity Federation with Kubernetes to learn how to configure Workload Identity Federation for your clusters. This page covers only configuring Workload Identity Federation for AWS and Azure VMs.

By using Workload Identity Federation, workloads that run on AWS EC2 and Azure VMs can exchange their environment-specific credentials for short-lived Google Cloud Security Token Service tokens.

Environment-specific credentials include the following:

By setting up Workload Identity Federation, you can let these workloads exchange these environment-specific credentials against short-lived Google Cloud credentials. Workloads can use these short-lived credentials to access Google Cloud APIs.

Before you begin

  • Set up authentication.

    Select the tab for how you plan to use the samples on this page:

    Console

    When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

    gcloud

    In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

    Python

    To use the Python samples on this page in a local development environment, install and initialize the gcloud CLI, and then set up Application Default Credentials with your user credentials.

    1. Install the Google Cloud CLI.

    2. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

    3. If you're using a local shell, then create local authentication credentials for your user account: 

      gcloud auth application-default login

      You don't need to do this if you're using Cloud Shell.

      If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

    For more information, see Set up ADC for a local development environment in the Google Cloud authentication documentation.

Prepare your external identity provider

You only need to perform these steps once for each Microsoft Entra ID tenant or AWS account.

AWS

Google Cloud supports two mechanisms for federating with AWS workloads:

  • AWS outbound identity federation: AWS acts as an OpenID Connect (OIDC) identity provider and issues short-lived JSON Web Tokens (JWTs) to your workloads.

  • AWS IAM Credentials: Your workloads use AWS temporary security credentials (IAM roles or instance profiles), and Google Cloud verifies them using the AWS GetCallerIdentity API. You don't need to make any configuration changes in your AWS account for this option.

The remainder of this page describes how to configure federation using the AWS IAM Credentials mechanism.

After you configure a workload identity pool to trust your AWS account, you can let AWS users and AWS roles use permanent or temporary AWS security credentials to obtain short-lived Google Cloud credentials.

Azure

You must create a new Microsoft Entra ID application in your Microsoft Entra ID tenant and configure it so that it can be used for Workload Identity Federation.

After you configure a workload identity pool to trust the application, Azure users and service principals can request access tokens for this application and exchange these access tokens against short-lived Google Cloud credentials.

To create the application, do the following:

  1. Create a Microsoft Entra ID application and service principal.

  2. Set an Application ID URI for the application. You can use the default Application ID URI (APPID) or specify a custom URI.

    You need the Application ID URI later when you configure the workload identity pool provider.

To let an application obtain access tokens for the Microsoft Entra ID application, you can use managed identities:

  1. Create a managed identity. Note the Object ID of the managed identity. You need it later when you configure impersonation.

  2. Assign the managed identity to a virtual machine or another resource that runs your application.

Configure Workload Identity Federation

You only need to perform these steps once per AWS account or Microsoft Entra ID tenant. 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 AWS or Azure workload contain multiple attributes, and you must decide which attribute you want to use as subject identifier (google.subject) in Google Cloud.

Google Cloud uses the subject identifier in Cloud Audit Logs and in principal identifiers to uniquely identify an AWS or Azure user or role.

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

AWS

Your attribute mapping can use the response fields for GetCallerIdentity as source attributes. These fields include the following:

  • account: the AWS account number.
  • arn: the AWS ARN of the external entity.
  • userid: the unique identifier of the calling entity.

If your application runs on an Amazon Elastic Compute Cloud (EC2) instance with an attached role, you can use the following attribute mapping:

google.subject=assertion.arn
attribute.account=assertion.account
attribute.aws_role=assertion.arn.extract('assumed-role/{role_name}/')
attribute.aws_ec2_instance=assertion.arn.extract('assumed-role/{role_and_session}').extract('/{session}')

The mapping does the following:

  • Uses the ARN as subject identifier—for example: "arn:aws:sts::000000000000:assumed-role/ec2-my-role/i-00000000000000000
  • Introduces a custom attribute account and assigns it the AWS account ID
  • Introduces a custom attribute aws_role and assigns it the AWS role name—for example: ec2-my-role
  • Introduces a custom attribute aws_ec2_instance and assigns it the EC2 instance ID—for example: i-00000000000000000

Using this mapping, you can grant access to:

  • A specific EC2 instance: 

    principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.aws_ec2_instance/EC2_INSTANCE_ID

  • All users and instances in a role: 

    principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.aws_role/ROLE_NAME

Azure

Your attribute mappings can use the claims embedded in Azure access tokens, including custom claims, as source attributes. In most cases, it's best to use the sub claim as subject identifier:

google.subject=assertion.sub

When the sub claim surpasses the 127-character limit for google.subject, we recommend that you use the extract function to derive a subject identifier—for example:

google.subject=assertion.sub.extract('/eid1/c/pub/t/{sub_claim}')

For an access token issued to a managed identity, the sub claim contains the Object ID of the managed identity. If you use a different claim, make sure that the claim is unique and can't be reassigned.

If you're unsure about the list of claims you can reference, do the following:

  1. Connect to an Azure VM that has an assigned managed identity.

  2. Obtain an access token from the Azure Instance Metadata Service (IMDS):

    Bash

    curl \
  "http://169.254.169.254/metadata/identity/oauth2/token?resource=APP_ID_URI&api-version=2018-02-01" \
  -H "Metadata: true" | jq -r .access_token

    This command uses the jq tool. jq is available by default in Cloud Shell.

    PowerShell

    $SubjectTokenType = "urn:ietf:params:oauth:token-type:jwt"
$SubjectToken = (Invoke-RestMethod `
  -Uri "http://169.254.169.254/metadata/identity/oauth2/token?resource=APP_ID_URI&api-version=2018-02-01" `
  -Headers @{Metadata="true"}).access_token
Write-Host $SubjectToken

    Replace APP_ID_URI with the Application ID URI of the application that you've configured for Workload Identity Federation.

  3. In a web browser, go to https://jwt.ms/ and paste the access token into the field.

  4. Click Claims to view the list of claims embedded in the access token.

For service identities, it's typically not necessary to create a mapping for google.groups or any custom attributes.

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.

AWS

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

For example, the following condition restricts access to AWS roles and disallows other IAM identifiers:

assertion.arn.startsWith('arn:aws:sts::AWS_ACCOUNT_ID:assumed-role/')

Azure

You can use an attribute condition to restrict which users and service principals can use Workload Identity Federation to obtain short-lived Google Cloud tokens. Alternatively, you can configure your Microsoft Entra ID application to use app role assignments.

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.

You now have collected all of the information that you need to create a workload identity pool and provider:

Console

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

    Go to New workload provider and pool

  2. In the Create an identity pool section, 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:

    AWS

    Configure the following provider settings:

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

    Azure

    Configure the following provider settings:

    • Select a provider: OpenID Connect (OIDC).
    • Provider name: Name for the provider. The name is also used as the provider ID. You cannot change the provider ID later.
    • Issuer URL: https://sts.windows.net/TENANT_ID. Replace TENANT_ID with the tenant ID (GUID) of your Microsoft Entra ID tenant.
    • Allowed audiences: Application ID URI that you used when you registered the application in Microsoft Entra ID.

  5. Click Continue.

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

  7. In the Attribute conditions section, enter the attribute condition that you 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

  1. Create a new workload identity pool:

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

    Replace the following:

    • POOL_ID: the unique ID for the pool.
    • DISPLAY_NAME: the name of the pool.
    • DESCRIPTION: the description of the pool. This description appears when granting access to pool identities.

  2. Add a workload identity pool provider:

    AWS

    To create the workload identity pool provider for AWS, execute the following command:

    gcloud iam workload-identity-pools providers create-aws PROVIDER_ID \
  --location="global" \
  --workload-identity-pool="POOL_ID" \
  --account-id="ACCOUNT_ID" \
  --attribute-mapping="MAPPINGS" \
  --attribute-condition="CONDITIONS"

    Replace the following:

    Example:

    gcloud iam workload-identity-pools providers create-aws example-provider \
  --location="global" \
  --workload-identity-pool="pool-1" \
  --account-id="123456789000" \
  --attribute-mapping="google.subject=assertion.arn"

    Azure

    To create the workload identity pool provider for Azure, execute the following command:

    gcloud iam workload-identity-pools providers create-oidc PROVIDER_ID \
    --location="global" \
    --workload-identity-pool="POOL_ID" \
    --issuer-uri="ISSUER_URI" \
    --allowed-audiences="APPLICATION_ID_URI" \
    --attribute-mapping="MAPPINGS" \
    --attribute-condition="CONDITIONS"

    Replace the following:

    • PROVIDER_ID: The unique ID for the provider.
    • POOL_ID: The ID of the pool.
    • ISSUER_URI: The tenant ID (GUID) of your Microsoft Entra ID tenant, sometimes formatted as https://sts.windows.net/TENANT_ID. The issuer URI can vary, and to find your issuer URI, you can debug your JWT using JWT.io.
    • APPLICATION_ID_URI: Application ID URI that you used when you registered the application in Microsoft Entra ID.
    • MAPPINGS: The comma-separated list of attribute mappings that you previously identified.
    • CONDITIONS: (Optional) The attribute condition that you previously identified.

    Example:

    gcloud iam