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 (IdP) that supports OpenID Connect (OIDC), such as Microsoft Azure, or SAML 2.0.
Why identity federation?
Traditionally, applications running outside Google Cloud can use service account keys to access Google Cloud resources. However, service account keys are powerful credentials, and can present 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 approach eliminates the maintenance and security burden associated with service account keys.
Workload identity pools
A workload identity pool is an entity that lets you manage external identities.
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 pool providers
A workload identity pool provider is an entity that describes a relationship between Google Cloud and your IdP, including the following:
- AWS
- Azure Active Directory
- On-premises Active Directory Federation Services (AD FS)
- Okta
- Kubernetes clusters
Workload identity federation follows the OAuth 2.0 token exchange specification. You provide a credential from your IdP to the Security Token Service, which verifies the identity on the credential, and then returns a federated token in exchange.
OIDC provider with local JWKs
The workload identity pool provider can access JSON web keys (JWKs)
that are provided by your IdP in the jwks_uri
field in the
/.well-known/openid-configuration
document. If your OIDC provider doesn't
provide this information, or your issuer is not publicly accessible, you can
manually upload the JWKs when you create the oidc provider.
Attribute mappings
The tokens issued by your external identity provider contain one or more attributes. Some identity providers refer to these attributes as claims.
Google STS tokens also contain one or more attributes, as listed in the following table:
Attribute | Description |
---|---|
google.subject |
Required. A unique identifier for the user. This attribute is used in IAM
principal:// role bindings and appears in Cloud Logging logs.
The value must be unique and can't exceed 127 characters.
|
google.groups |
Optional. A set of groups that the identity belongs to. This attribute is used in IAM
principalSet:// role bindings to grant access to all members of a group.
|
attribute.NAME |
Optional. You can define up to 50 custom attributes and use these
attributes in IAM principalSet:// role bindings to grant access to
all identities with a certain attribute.
|
An attribute mapping defines how to derive the value of the Google STS token attribute from an external token. For each Google STS token attribute, you can define an attribute mapping, formatted as follows:
TARGET_ATTRIBUTE=SOURCE_EXPRESSION
Replace the following:
TARGET_ATTRIBUTE
is an attribute of the Google STS tokenSOURCE_EXPRESSION
is a Common Expression Language (CEL) expression that transforms one or more attributes from the tokens issued by your external identity provider
The following list provides attribute mapping examples:
Assign the assertion attribute
sub
togoogle.subject
:google.subject=assertion.sub
Concatenate multiple assertion attributes:
google.subject="myprovider::" + assertion.aud + "::" + assertion.sub
Map a GUID-valued assertion attribute
workload_id
to a name, and assign the result to a custom attribute namedattribute.my_display_name
:attribute.my_display_name={ "8bb39bdb-1cc5-4447-b7db-a19e920eb111": "Workload1", "55d36609-9bcf-48e0-a366-a3cf19027d2a": "Workload2" }[assertion.workload_id]
Use CEL logical operators and functions to set a custom attribute named
attribute.environment
to eitherprod
ortest
, depending on the identity's Amazon Resource Name (ARN):attribute.environment=assertion.arn.contains(":instance-profile/Production") ? "prod" : "test"
Use the
extract
function to populate a custom attributeaws_role
with the name of the assumed role or, if no role has been assumed, with the identity's ARN.attribute.aws_role=assertion.arn.contains('assumed-role') ? assertion.arn.extract('{account_arn}assumed-role/') + 'assumed-role/' + assertion.arn.extract('assumed-role/{role_name}/') : assertion.arn
split
function splits a string on the provided separator value. For example, to extract the attributeusername
from an email address attribute by splitting its value at the@
and using the first string, use the following attribute mapping:attribute.username=assertion.email.split("@")[0]
join
function joins a list of strings on the provided separator value. For example, to populates the custom attributedepartment
by concatenating a list of strings with.
as a separator, use the following attribute mapping:attribute.department=assertion.department.join(".")
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.
For more details, see the API documentation for the
attributeMapping
field.
Attribute conditions
An attribute condition is a CEL expression 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.
You can use an attribute condition to restrict which identities can authenticate using your workload identity pool.
Attribute conditions are useful in scenarios such as the following:
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/
|
All identities in a group |
principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/
|
All identities with a specific attribute value |
principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/
|
All identities in a pool |
principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/
|
What's next
Use identity federation to access resources from AWS, access resources from Microsoft Azure, access resources from an OIDC provider, or access resources from a SAML 2.0 provider.
Learn how to manage workload identity pools using the Google Cloud CLI or the REST API.