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:
- Azure Active Directory
- On-premises Active Directory
- 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.
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
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
NAMEwith 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
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
For more details, see the API documentation for the
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
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:
|All identities in a group||
|All identities with a specific attribute value||
|All identities in a pool||
Learn how to manage workload identity pools using the
gcloudcommand-line tool or the REST API.