Workload identity federation

This document provides an overview of identity federation for external workloads. Using identity federation, you can grant on-premises or multi-cloud workloads access to Google Cloud resources, without using a service account key.

You can use identity federation with Amazon Web Services (AWS), or with any identity provider that supports OpenID Connect (OIDC), such as Microsoft Azure.

Why identity federation?

Traditionally, applications running outside Google Cloud have used service account keys to access Google Cloud resources. Service account keys are powerful credentials, and can represent a security risk if they are not managed correctly.

With identity federation, you can use Identity and Access Management (IAM) to grant external identities IAM roles, including the ability to impersonate service accounts. This lets you access resources directly, using a short-lived access token, and eliminates the maintenance and security burden associated with service account keys.

Workload identity pools

A workload identity pool is a container for a collection of external identities.

A project can contain multiple workload identity pools, and each pool can have access to different resources. This lets you follow the principle of least privilege by grouping related identities in the same pool, and then granting them fine-grained access to resources.

In general, we recommend creating a new pool for each non-Google Cloud environment that needs to access Google Cloud resources, such as development, staging, or production environments.

Workload identity providers

A workload identity provider is an entity that describes a relationship between Google Cloud and an external identity provider. Example providers include:

  • AWS
  • Azure Active Directory
  • On-premises Active Directory
  • Okta
  • Kubernetes clusters

Workload identity federation follows the OAuth 2.0 token exchange specification. You provide a credential from an external identity provider to the Secure Token Service, which verifies the identity on the credential, and then returns a federated token in exchange.

Attribute mappings

Credentials typically include attributes that provide information about the identity asserted by the credential, such as its name, email, or user ID. Attribute mapping applies the attributes from an external token to a Google token. This lets IAM use tokens from external providers to authorize access to Google Cloud resources.

For AWS, Google provides default mappings, which cover most common scenarios. You can also supply custom mappings.

For OIDC providers, you supply the mappings. To construct the mapping, consult the provider's documentation for a list of attributes on their credentials.

Attribute mapping supports Common Expression Language, which lets you formulate new, custom attributes based on the external credential, or make existing attributes more readable. For example, the following mapping defines an environment attribute based on whether an Amazon Resource Name (ARN) contains :instance-profile/Production:

attribute.environment=assertion.arn.contains(":instance-profile/Production") ? "prod" : "test"

Attribute conditions

An attribute condition lets you restrict what identities can authenticate using your workload identity pool. Using a CEL expression, you can examine the attributes on a request credential and choose whether to allow access.

Attribute conditions are useful in several scenarios:

  • If your workload uses an identity provider that's available to the general public, you can restrict access so only the identities you choose have access to your workload identity pool.

  • If you're using an identity provider with multiple cloud platforms, you can prevent credentials intended for use with another platform from being used with Google Cloud, and vice-versa. This helps avoid the confused deputy problem.

The following example only allows requests from identities that have a specific AWS role:

attribute.aws_role == "role-mapping"

Service account impersonation

The token exchange flow returns a federated access token. You can use this token to impersonate a service account and obtain a short-lived OAuth 2.0 access token. The short-lived access token lets you call any Google Cloud APIs that the service account has access to.

To impersonate a service account, grant your external identity the Workload Identity User role (roles/iam.workloadIdentityUser) on a service account with the roles required by your workload. You can grant a role to all the identities in a workload identity pool, or to specific external identities based on their attributes.

The following table describes common scenarios for granting roles:

Scenario Format
Single identity principal://iam.googleapis.com/projects/project-number/locations/global/workloadIdentityPools/pool-id/subject/subject-name
All identities in a group principalSet://iam.googleapis.com/projects/project-number/locations/global/workloadIdentityPools/pool-id/group/group-name
All identities with an attribute defined using attribute mapping principalSet://iam.googleapis.com/projects/project-number/locations/global/workloadIdentityPools/pool-id/attribute.attribute-name/attribute-value
All identities in a pool principalSet://iam.googleapis.com/projects/project-number/locations/global/workloadIdentityPools/pool-id/*

What's next