This guide describes how to use credentials issued by an external identity provider to impersonate a service account and access resources on Google Cloud. This process is called workload identity federation.
Common use cases for workload identity federation include:
- Enabling a background application or continuous integration/continuous delivery (CI/CD) pipeline that runs outside of Google Cloud to access Google Cloud resources and APIs
- Enabling users of a web application that runs outside of Google Cloud to access data stored in a Google Cloud service, such as Cloud Storage or BigQuery
To use workload identity federation, you configure Google Cloud to trust an external identity provider such as Amazon Web Services (AWS), Azure Active Directory (AD), an OIDC-compatible identity provider, or a SAML 2.0-compatible identity provider. Applications can then use credentials issued by the external identity provider to impersonate a service account by following these steps:
- Obtain a credential from the trusted identity provider.
- Exchange the credential for a token from the Security Token Service.
- Use the token from the Security Token Service to impersonate a service account and obtain a short-lived Google access token.
By using workload identity federation, you can avoid the need to store and manage service account keys.
Before you begin
-
Enable the IAM, Resource Manager, Service Account Credentials, and Security Token Service APIs.
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:
- Workload Identity Pool Admin (
roles/iam.workloadIdentityPoolAdmin
) - Service Account Admin (
roles/iam.serviceAccountAdmin
)
For more information about granting roles, see Manage access.
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.
Preparing the external identity provider
To use workload identity federation, you must configure a workload identity pool and a workload identity pool provider in your project:
AWS
AWS users and AWS roles can use permanent or temporary AWS security credential to impersonate a service account on Google Cloud.
To allow the use of AWS security credentials, you must configure the workload identity pool to trust your AWS account. Security credentials tokens issued for this AWS account are then recognized by workload identity federation, and you can use the tokens to obtain short-lived service account credentials.
Azure
Azure users and service principals can use Azure AD access tokens to impersonate a service account on Google Cloud.
To allow the use of Azure AD access tokens, you must configure the workload identity pool to trust an Azure AD application. Access tokens issued for this application are then recognized by workload identity federation, and you can use the tokens to obtain short-lived service account credentials.
As a best practice, you should create a new application in Azure AD and use the application only to obtain Google Cloud credentials:
Set an Application ID URI for the application.
When setting the Application ID URI, it will default to api://<appid>. Note the URI since you will need it later when creating the workload identity pool provider and the credential configuration file.
You need the Application ID URI later when you configure the workload identity pool provider.
To let an application obtain access tokens for the Azure AD application, you can use managed identities:
Create a managed identity. Note the Object ID of the managed identity. You need it later when you configure impersonation.
Assign the managed identity to a virtual machine or another resource that runs your application.
GitHub Actions
You can let a GitHub Actions workflow use a GitHub OIDC token to impersonate a service account on Google Cloud.
To allow the use of these tokens, you must configure the workload identity pool to trust OIDC tokens issued by GitHub. ID tokens issued for workflows are then recognized by workload identity federation, and you can use the tokens to obtain short-lived service account credentials.
OIDC
You can let users and applications impersonate a service account on Google Cloud by using ID tokens or JSON Web Token-formatted access token issued by an OIDC-compliant identity provider.
To allow the use of these tokens, you must configure the workload identity pool to trust your external identity provider. Tokens issued by the external identity provider are then recognized by workload identity federation, and you can use the tokens to obtain short-lived service account credentials.
To use workload identity federation, your identity provider's
OIDC metadata URI
must be publicly accessible over the internet and use the endpoint
ISSUER/.well-known/openid-configuration
,
where ISSUER
is the value of the issuer (iss
) claim
in the token. Google Cloud queries the metadata
endpoint to obtain your provider's JSON Web Key Set (JWKS) and then uses this key
set to validate tokens.
Typically, it's best to use ID tokens when performing a token exchange, because ID tokens reflect the user's identity. If you decide to use access tokens instead, configure a dedicated application or resource in your identity provider for the sole purpose of obtaining Google Cloud credentials.
By default, workload identity federation expects tokens that use the following
URL as audience (aud
) claim:
https://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID
Replace the following:
PROJECT_NUMBER
: project number. of the Google Cloud project that you use to create workload identity pool.POOL_ID
: an ID of your choice that identifies the workload identity pool. You must use the same ID when creating the workload identity pool later.PROVIDER_ID
: an ID of your choice that identifies the workload identity pool provider. You must use the same ID when creating the workload identity pool provider later.
You can specify a custom list of allowed audiences when you create the workload identity pool and provider.
OIDC (AD FS)
Active Directory users can use OIDC access tokens from Active Directory Federation Services (AD FS) to impersonate a service account on Google Cloud.
To let an application request AD FS access tokens and use these tokens to access Google Cloud, you need two application registrations in AD FS:
An application registration of type native application or server application.
An application registration of type Web API that corresponds to a workload identity pool provider on Google Cloud.
You then configure a workload identity provider to accept access tokens issued to the Web API.
Using Integrated Windows Authentication
You can combine workload identity federation with Integrated Windows Authentication (IWA). IWA lets Active Directory applications authenticate to AD FS by using Kerberos or NTLM credentials. By combining workload identity federation and IWA, you avoid having to store and manage AD FS client credentials and service account keys.
To use IWA, ensure that the following prerequisites are met:
- Your application uses a HTTP library that supports IWA.
- You've configured AD FS to allow Windows Authentication and to use the right service principal name.
- You've configured extended protection for authentication so that it's compatible with your AD FS deployment.
- You've enabled IWA for the user-agent that your application uses in HTTP requests.
Registering the client application
To register an application in AD FS for Windows Server 2019, do the following:
- Open the AD FS MMC snap-in and navigate to Application Groups.
- Click Add application group.
- On the Welcome page, enter a name for the client, select server application. Then click Next.
- On the Server application page, enter a client identifier (Client ID) and
a redirect URI. If you're only planning to use the
client_credentials
grant type, the redirect URI won't be used and you can use a URI such ashttp://localhost/
. Then click Next. - On the Configure application credentials page, choose how the client will authenticate. To use IWA, set Windows Integrated Authentication to enabled and select the domain user that your application is configured to run as. Then click Next.
- On the Summary page, review the settings and click Next.
- Click Close to dismiss the dialog.
Creating a Web API application for the workload identity federation pool
Create another application registration of type Web API. This application corresponds to a workload identity pool provider and you use it to set up a trust relationship to Google Cloud.
To create the application in AD FS for Windows Server 2019, do the following:
- Open the AD FS MMC snap-in and navigate to Application Groups.
- Click Add application group.
- On the Welcome page, enter a name such as
Workload Identity Federation (test environment)
and select Web API. Then click Next. On the Configure Web API page, enter a relying party identifier for the Web API.
Instead of defining a custom relying party identifier, you can use the following URI as relying party identifier:
https://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID
Replace the following values:
PROJECT_NUMBER
: Project number of the Google Cloud project that you use to create workload identity pool.POOL_ID
: ID of your choice that identifies the workload identity pool. You must use the same ID when creating the workload identity pool later.PROVIDER_ID
: ID of your choice that identifies the workload identity pool provider. You must use the same ID when creating the workload identity pool provider later.
This format ensures that the relying party identifier uniquely identifies a workload identity pool provider.
You need the relying party identifier later when you configure the workload identity pool provider.
Click Next.
On the Apply access control policy page, select an appropriate access policy, then click Next.
On the Configure application permissions page, add the client application that you created previously. Then click Next.
On the Summary page, review the settings and click Next.
Click Close to dismiss the dialog.
SAML
You can let users and applications impersonate a service account on Google Cloud by using assertions issued by a SAML 2.0-compliant identity provider. Federation using encrypted assertions is not supported.
Configure your SAML identity provider to issue assertions with the workload
identity pool provider as audience in the format
https://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID
.
To allow the use of these assertions, you must then configure the workload identity pool to trust your external identity provider by providing it your SAML identity provider's metadata document.
Workload identity federation then recognizes assertions issued by the external identity provider, and you can use the tokens to obtain short-lived service account credentials.
SAML (AD FS)
You can let applications impersonate a service account on Google Cloud by using a SAML 2.0 assertion from Active Directory Federation Services (AD FS).
To let applications request a SAML assertion from AD FS that can be used for workload identity federation, you must create a relying party trust. To create a relying party trust in AD FS for Windows Server 2019, do the following:
- Open the AD FS MMC snap-in and navigate to Relying party trusts.
- Click Add relying party trust.
- On the Welcome page of the Add relying party trust wizard, select Claims aware and click Start.
- On the Select data source page, select Enter data about the relying party manually. Then click Next.
- On the Specify display name page, enter a name for the trust. Then click Next.
- On the Configure certificate page, click Next. An encryption certificate isn't required because workload identity federation doesn't support encrypted SAML assertions.
- On the Configure URL page, keep the default settings and click Next.
On the Configure identifiers page, enter a relying party identifier.
Instead of defining a custom relying party identifier, you can use the following URI as relying party identifier:
https://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID
Replace the following:
PROJECT_NUMBER
: Project number of the Google Cloud project that you use to create workload identity pool.POOL_ID
: ID of your choice that identifies the workload identity pool. You must use the same ID when creating the workload identity pool later.PROVIDER_ID
: ID of your choice that identifies the workload identity pool provider. You must use the same ID when creating the workload identity pool provider later.
This format ensures that the relying party identifier uniquely identifies a workload identity pool provider.
You need the relying party identifier later when you configure the workload identity pool provider.
Click Next.
On the Choose access control policy page, select an appropriate access control policy, then click Next.
On the Ready to add trust page, review the settings and click Next.
On the Finish page, click Close to dismiss the dialog.
To be compatible with workload identity federation, SAML assertions must
contain at least one claim
that uniquely identifies the Active Directory user. Typically, you use
the Name ID claim for this purpose, which corresponds to the value of the
NameID
element in the SAML assertion.
To customize the SAML assertion's set of claims, you must edit the relying party trust's claim issuance policy. To edit the claim issuance policy, do the following:
- In the list of relying party trusts, select the trust that you just created and click Edit claim issuance policy.
- Click Add rule
- On the Choose rule type page of the Add transform claim rule wizard, select Transform an incoming claim. Then click Next.
On the Configure claim rule page, configure the following settings:
- Claim rule name:
Name Identifier
. - Incoming claim type: Select Primary SID, UPN, or a different claim to uniquely identify the subject.
- Outgoing claim type: Name ID.
- Outgoing name ID format: Unspecified.
- Claim rule name:
Select Pass through all claim values and click Finish.
Optionally, configure additional rules to include more attributes in the SAML assertions.
Click OK to close the claim issuance policy dialog.
Configuring federation
To federate with your external identity provider, you must do the following:
- Prepare a Google Cloud project that will contain the workload identity pool and provider.
- Define an attribute mapping and an optional attribute condition that map the identity provider's credentials to external identities.
- Create a workload identity pool and provider.
The following sections guide you through this process.
Prepare the project
Select and prepare the project that will contain the workload identity pool and provider:
Ensure that you have the Workload Identity Pool Admin (
roles/iam.workloadIdentityPoolAdmin
) and Service Account Admin (roles/iam.serviceAccountAdmin
) roles on the project.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.Update the organization policy for your organization to allow federation.
Enable the IAM, Resource Manager, Service Account Credentials, and Security Token Service (STS) APIs.
Define an attribute mapping and condition
Define an attribute mapping and an optional attribute condition that map the identity provider's credentials to external identities.
The credentials issued by your external identity provider contain one or more
attributes, also referred to as claims. Workload identity federation refers to
these attributes as assertion attributes and prefixes them with
assertion.
.
An attribute mapping lets you map assertion attributes to the predefined target attributes recognized by workload identity federation. These predefined target attributes are:
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 takes the form TARGET_ATTRIBUTE=SOURCE_EXPRESSION
.
See the following examples:
This mapping assigns the assertion attribute
sub
togoogle.subject
:google.subject=assertion.sub
This mapping uses a Common Expression Language (CEL) expression to concatenate multiple assertion attributes:
google.subject="myprovider::" + assertion.aud + "::" + assertion.sub
This mapping uses another CEL expression to map a GUID-valued assertion attribute
workload_id
to a name, and assigns 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]
This mapping uses 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"
This mapping uses 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
Optionally, you can also 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.
To choose the right attribute mappings and conditions for your use case, you need to decide whether to map service identities or user identities:
- By mapping service identities, you can enable an background application or CI/CD pipeline that runs outside of Google Cloud to obtain short-lived credentials for Google Cloud. The application obtains these short-lived credentials on its own behalf, without user involvement.
- By mapping user identities, you can enable users of an application that runs outside of Google Cloud to obtain short-lived credentials for Google Cloud. The application obtains these short-lived credentials on a user's behalf.
Mapping service identities
AWS
Your attribute mappings can use the
response fields for GetCallerIdentity
as source attributes. These fields include:
account
, containing the AWS account number.arn
, containing the AWS ARN of the external entity.userid
, containing 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.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
This mapping lets you grant the ability to impersonate a service account to specific EC2 instances or by role using the following identifiers:
Grant access to specific EC2 instance:
principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/arn:aws:sts::ACCOUNT_ID:assumed-role/AWS_ROLE/AWS_ROLE_SESSION_NAME
Grant access by role:
principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.aws_role/arn:aws:sts::ACCOUNT_ID:assumed-role/AWS_ROLE
Your AWS account might contain a large number of users and roles, but only a small subset of these might require access to Google Cloud resources. To limit the set of users and roles that can use workload identity federation, use an attribute condition. For example, the following condition allows a specific account to access Google Cloud resources:
assertion.arn.startsWith('arn:aws:sts::ACCOUNT-ID:assumed-role/')
Azure
Your attribute mappings can use the claims embedded in Azure access tokens, including custom claims, as source attributes.
To obtain a complete list of claims you can reference, connect to an Azure VM that has an assigned managed identity and do the following:
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.In a web browser, go to
https://jwt.ms/
and paste the access token into the text box.Click Claims to view the list of claims embedded in the access token.
To authenticate with a service principal, you can use the following attribute mapping:
google.subject=assertion.sub
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.
For service identities, it's typically not necessary to create a mapping
for google.groups
or any custom attributes.
To control which identities can obtain short-lived credentials for Google Cloud, do not define attribute conditions. Instead, configure your Azure AD application to use app role assignments.
GitHub Actions
Your attribute mappings can use the claims embedded in the OIDC token as source attributes. These include:
sub
: Contains the repository name and Git reference, for examplerepo:username/reponame:ref:refs/heads/master
.repository
: Contains the owner and repository name, for exampleusername/reponame
.repository_owner
: Contains the owner, which can be a username or the name of a GitHub organization.ref
: Contains the Git reference, for examplerefs/heads/main
.
The following attribute mapping sets google.subject
to the sub
claim
from the GitHub Actions OIDC token. Because the sub
claim contains
both, the repository name and Git reference, this mapping lets you control access
by repository and branch:
google.subject=assertion.sub
Controlling access by repository and branch can be useful if certain branches
(for example, main
) need different access to resources than other
branches (for example, feature branches).
If you don't plan to differentiate access by branch, you can use the following
attribute mapping, which sets google.subject
to the repository
claim:
google.subject=assertion.repository
Optionally, you can use an attribute condition to define additional requirements
ID tokens have to meet. For example, the following condition limits access
to ID tokens for workflows that use the Git branch main
:
assertion.ref=='refs/heads/main'
OIDC
Your attribute mappings can use the claims embedded in the ID token or access token issued by the external identity provider.
You must map one of these claims to google.subject
to uniquely identify
the user. To protect against spoofing threats, choose a claim with a unique
value that can't be changed.
Many identity providers populate the sub
claim with a unique and immutable
ID. For these identity providers, consider mapping the sub
claim to
google.subject
:
google.subject=assertion.sub
Avoid using a claim like email
for this purpose. Email addresses
can typically be reassigned or changed, so they don't uniquely and permanently
identify a user.
Your identity provider might contain a large number of users, but only a small subset of these might require access to Google Cloud resources. To limit the set of users and credentials that can use workload identity federation, you can optionally use an attribute condition.
For example, the following condition restricts access to tokens that
contain a custom service_account
claim with a value true
:
assertion.service_account==true
OIDC (AD FS)
Your attribute mappings can use the claims embedded in AD FS access tokens as source attributes.
To authenticate an application, you can use the following attribute mapping:
google.subject=assertion.appid
This mapping sets google.subject
to the value of the appid
claim, which
contains the Client ID of the AD FS application.
Optionally, you can use an attribute condition to define additional requirements AD FS access tokens have to meet. For example, the following condition defines that applications have to use IWA to authenticate to AD FS:
assertion.authmethod=='http://schemas.microsoft.com/ws/2008/06/identity/authenticationmethod/windows'
To control the list of applications can obtain short-lived credentials for Google Cloud, do not define attribute conditions. Instead, use client permissions in AD FS to define which applications are allowed.
SAML
Your attribute mappings can use the <Subject>
and <Attribute>
elements
embedded in the assertion issued by the external identity provider. SAML
attributes can be referred to using the following keywords:
assertion.subject
contains theNameID
of the authenticated user found in the<Subject>
element.assertion.attributes['ATTRIBUTE_NAME']
contains a list of values for the like-named<Attribute>
.
You must map one of these claims to google.subject
to uniquely
identify the user. To protect against spoofing threats, choose a claim with
a unique value that can't be changed.
Many identity providers populate the NameId
with a unique and
immutable ID. For these identity providers, consider mapping the
NameId
attribute to google.subject
:
google.subject=assertion.subject
Avoid using an attribute like
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
for this purpose. Email addresses can typically be reassigned or changed, so
they don't uniquely and permanently identify a user.
Your identity provider might contain a large number of users, but only a small subset of these might require access to Google Cloud resources. To limit the set of users and credentials that can use workload identity federation, you can optionally use an attribute condition.
For example, the following condition restricts access to assertions that
contain a custom https://example.com/SAML/Attributes/AllowGcpFederation
attribute with a value true
:
assertion.attributes['https://idp.com/SAML/Attributes/AllowGcpFederation'][0]=='true'
SAML (AD FS)
Your attribute mappings can use the claims embedded in the assertion issued by AD FS, as described earlier in this guide.
Use the following mapping to let workload identity federation use the Name ID claim from the SAML assertion to uniquely identify the user:
google.subject=assertion.subject
If you've configured your claim issuance policy to include additional claims in SAML assertions, you can add additional mappings. For example:
google.groups=assertion.attributes['http://schemas.microsoft.com/ws/2008/06/identity/claims/groupsid'] attribute.userip=['http://schemas.microsoft.com/2014/09/requestcontext/claims/userip'][0]
Optionally, you can use an attribute condition that all SAML assertions must satisfy. For example, the following condition only permits SAML assertions that include a certain group membership claim:
"S-1-5-6" in google.groups
Create the workload identity pool and provider
You've now collected all the information you need to create a workload identity pool and provider:
Console
In the console, go to the New workload provider and pool page.
Under Create an identity pool, 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.
Click Continue.
In the Select a provider drop-down list, select your provider:
- AWS if you're federating with AWS.
- OpenID Connect (OIDC) if you're federating with Azure, GitHub Actions, or another OIDC-compatible provider.
- You cannot configure workload identity federation from a SAML 2.0 identity provider using the console. You must use the gcloud CLI to configure workload identity federation from a SAML 2.0 identity provider.
Under Provider details, enter details for your identity provider:
AWS
- Provider name: Name for the provider. The name is also used as the provider ID. You cannot change the provider ID later.
Azure
- 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
whereTENANT_ID
is the Tenant ID (GUID) of your Azure AD tenant. - Allowed audiences: Application ID URI that you used when you registered the application in Azure AD.
GitHub Actions
- 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://token.actions.githubusercontent.com/
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: Issuer URL of your identity provider.
- Allowed audiences: Expected audience of ID Tokens.
OIDC (AD FS)
- 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://ADFS_DOMAIN/adfs
whereADFS_DOMAIN
is the public domain name of the AD FS server or farm.
Click Continue.
Under Configure provider attributes, add the attribute mappings that you've identified previously.
Under Attribute conditions, enter the attribute condition that you've identified previously. Leave the field blank if you don't have an attribute condition.
Click Save to create the workload identity pool and provider.
gcloud
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 values:
POOL_ID
: Unique ID for the pool.DISPLAY_NAME
: Name of the pool.DESCRIPTION
: Description of the pool. This description appears when granting access to pool identities.
Add a workload identity pool provider:
AWS
gcloud iam workload-identity-pools providers create-aws PROVIDER_ID \ --location="global" \ --workload-identity-pool="POOL_ID" \ --account-id="AWS_ACCOUNT_ID" \ --attribute-mapping="MAPPINGS" \ --attribute-condition="CONDITIONS"
Replace the following values:
PROVIDER_ID
: Unique ID for the provider.POOL_ID
: ID of the pool.AWS_ACCOUNT_ID
: 12-digit number that identifies your AWS account.MAPPINGS
: Comma-separated list of attribute mappings that you've identified previously.CONDITIONS
: Attribute condition that you've identified previously. Remove the parameter if you don't have an attribute condition.
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
gcloud iam workload-identity-pools providers create-oidc PROVIDER_ID \ --location="global" \ --workload-identity-pool="POOL_ID" \ --issuer-uri="
https://sts.windows.net/TENANT_ID
" \ --allowed-audiences="APPLICATION_ID_URI" \ --attribute-mapping="MAPPINGS" \ --attribute-condition="CONDITIONS"Replace the following values:
PROVIDER_ID
: Unique ID for the provider.POOL_ID
: ID of the pool.TENANT_ID
: Tenant ID (GUID) of your Azure AD tenant.APPLICATION_ID_URI
: Application ID URI that you used when you registered the application in Azure AD.MAPPINGS
: Comma-separated list of attribute mappings that you've identified previously.CONDITIONS
: Attribute condition that you've identified previously. Remove the parameter if you don't have an attribute condition.
Example:
gcloud iam workload-identity-pools providers create-oidc example-provider \ --location="global" \ --workload-identity-pool="pool-1" \ --issuer-uri="https://sts.windows.net/00000000-1111-2222-3333-444444444444" \ --allowed-audiences="api://my-app" \ --attribute-mapping="google.subject=assertion.sub,google.groups=assertion.groups"
GitHub Actions
gcloud iam workload-identity-pools providers create-oidc PROVIDER_ID \ --location="global" \ --workload-identity-pool="POOL_ID" \ --issuer-uri="https://token.actions.githubusercontent.com/" \ --attribute-mapping="MAPPINGS" \ --attribute-condition="CONDITIONS"
Replace the following values:
PROVIDER_ID
: Unique ID for the provider.POOL_ID
: ID of the pool.OWNER
: Name of the user or organization owning the repository.REPOSITORY
: Name of the repository.MAPPINGS
: Comma-separated list of attribute mappings that you've identified previously.CONDITIONS
: Attribute condition that you've identified previously. Remove the parameter if you don't have an attribute condition.
OIDC
gcloud iam workload-identity-pools providers create-oidc PROVIDER_ID \ --location="global" \ --workload-identity-pool="POOL_ID" \ --issuer-uri="ISSUER" \ --allowed-audiences="AUDIENCE" \ --attribute-mapping="MAPPINGS" \ --attribute-condition="CONDITIONS"
Replace the following values:
PROVIDER_ID
: Unique ID for the provider.POOL_ID
: ID of the pool.ISSUER
: Issuer URI as defined in OIDC metadata.AUDIENCE
: Expected audience of ID Tokens, for many providers the audience matches the client ID.MAPPINGS
: Comma-separated list of attribute mappings that you've identified previously.CONDITIONS
: Attribute condition that you've identified previously. Remove the parameter if you don't have an attribute condition.
OIDC (AD FS)
gcloud iam workload-identity-pools providers create-oidc PROVIDER_ID \ --location="global" \ --workload-identity-pool="POOL_ID" \ --issuer-uri="
https://ADFS_DOMAIN/adfs
" \ --allowed-audiences="RELYING_PARTY_ID" \ --attribute-mapping="MAPPINGS" \ --attribute-condition="CONDITIONS"Replace the following values:
POOL_ID
: ID of the pool.ADFS_DOMAIN
: Public domain name of the AD FS server or farm.RELYING_PARTY_ID
: Relying party identifier of the Web API application for the workload identity federation pool in AD FS. You only need this parameter if you use a custom relying party identifier.MAPPINGS
: Comma-separated list of attribute mappings that you've identified previously.CONDITIONS
: Attribute condition that you've identified previously. Remove the parameter if you don't have an attribute condition.
SAML
gcloud iam workload-identity-pools providers create-saml PROVIDER_ID \ --location="global" \ --workload-identity-pool="POOL_ID" \ --idp-metadata-path="IDP_METADATA_PATH" \ --attribute-mapping="MAPPINGS" \ --attribute-condition="CONDITIONS"
Replace the following values:
POOL_ID
: ID of the pool.IDP_METADATA_PATH
: Local file path to obtain the SAML identity provider's IdP metadata document.MAPPINGS
: Comma-separated list of attribute mappings that you've identified previously.CONDITIONS
: Attribute condition that you've identified previously. Remove the parameter if you don't have an attribute condition.
Example:
gcloud iam workload-identity-pools providers create-saml example-provider \ --location="global" \ --workload-identity-pool="pool-1" \ --idp-metadata-path="/path/to/idp_metadata.xml" \ --attribute-mapping="google.subject=assertion.subject,google.groups=assertion.attributes.groups"
SAML (AD FS)
curl -O https://DOMAIN/federationmetadata/2007-06/federationmetadata.xml gcloud iam workload-identity-pools providers create-saml PROVIDER_ID \ --location="global" \ --workload-identity-pool="POOL_ID" \ --idp-metadata-path="federationmetadata.xml" \ --attribute-mapping="MAPPINGS" \ --attribute-condition="CONDITIONS"
Replace the following:
DOMAIN
: Domain name of your AD FS server or server farm.POOL_ID
: ID of the pool.MAPPINGS
: Comma-separated list of attribute mappings that you've identified previously.CONDITIONS
: Attribute condition that you've identified previously. Remove the parameter if you don't have an attribute condition.
Example:
gcloud iam workload-identity-pools providers create-saml example-provider \ --location="global" \ --workload-identity-pool="pool-1" \ --idp-metadata-path="federationmetadata.xml" \ --attribute-mapping=google.subject=assertion.subject"
What's next
- Learn how to obtain short-lived credentials by using identity federation.
- Read more about workload identity federation.
- See how you can manage workload identity pools and providers.