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, or SAML 2.0 Preview.

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

You can use a workload identity pool to organize and manage 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 Security 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 (CEL), 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"

Mapped attributes can appear in the identifier for a principal in an IAM role binding. You can also use mapped attributes in the attribute condition for the workload identity pool provider, as explained on this page.

In each mapping, the key is the name of an attribute of a Google token. Each attribute must use one of the following names:

  • google.subject: The external identity that IAM is authenticating. This value also appears in audit logs.

  • google.groups: A list of groups that the external identity belongs to. You can grant access to all members of a group, using the syntax described in Service account impersonation on this page.

  • attribute.NAME: A custom attribute name. Replace NAME with a unique name for the attribute.

The value must be a CEL expression that evaluates to a valid CEL type. In the CEL expression, the assertion keyword refers to a map that represents the authentication credential issued by the identity provider. You can use dot notation to access the map's values. For example, AWS credentials include an arn value, which you can access as assertion.arn.

For more details, see the API documentation for the attributeMapping field.

Attribute conditions

An attribute condition lets you restrict which 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 attribute condition for a workload identity pool provider can use the assertion keyword, which refers to a map that represents the authentication credential issued by the identity provider. You can use dot notation to access the map's values. For example, AWS credentials include an arn value, which you can access as assertion.arn. In addition, the attribute condition can use any attribute that is defined in the provider's attribute mapping.

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

attribute.aws_role == "ROLE_MAPPING"

For more details, see the API documentation for the attributeCondition field.

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:

Identities Identifier 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 a specific attribute value 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