This guide describes how to use Workload Identity Federation to letworkloads that run on Azure Kubernetes Service (AKS), Amazon Elastic KubernetesService, or on a self-hosted Kubernetes cluster authenticate to Google Cloud.

Kubernetes lets you configure a cluster so that workloads can obtain KubernetesServiceAccount tokensfrom a projected volume.By setting up Workload Identity Federation, you can let workloads use theseKubernetes ServiceAccount tokens to authenticate to Google Cloud.

If you're using GKE, useWorkload Identity Federation for GKEinstead of configuring Workload Identity Federation.

Before you begin

Before you configure Workload Identity Federation, make sure that yourKubernetes cluster meets the following criteria:

Configure Workload Identity Federation

You only need to perform these steps once for each Kubernetes cluster. You can then usethe same workload identity pool and provider for multiple Kubernetes pods and acrossmultiple Google Cloud projects.

To start configuring Workload Identity Federation, do the following:

1. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Roles required to select or create a project

   • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
   • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.create permission.Learn how to grant roles.

   Go to project selector

We recommend that youuse a dedicated project to manage workload identity pools and providers.

2. Verify that billing is enabled for your Google Cloud project.

Enable the IAM, Resource Manager, Service Account Credentials, and Security Token Service APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enable permission.Learn how to grant roles.

Enable the APIs

Define an attribute mapping and condition

Kubernetes ServiceAccount tokens contain multiple claims, including the following:

• sub: Contains the namespace and name of the ServiceAccount-for example,system:serviceaccount:NAMESPACE:KSA_NAME,whereNAMESPACE is the namespace of theServiceAccount andKSA_NAME is the name of theServiceAccount.
• "kubernetes.io".namespace: Contains the namespace of the ServiceAccount.
• "kubernetes.io".serviceaccount.name: Contains the name of the ServiceAccount.
• "kubernetes.io".pod.name: Contains the name of the pod.

To usesub as subject identifier (google.subject) in Google Cloud,use the following mapping:

google.subject=assertion.sub

Optionally, you canmap additional attributes.You can then refer to these attributes when granting access to resources.For example:

google.subject=assertion.sub,attribute.namespace=assertion['kubernetes.io']['namespace'],attribute.service_account_name=assertion['kubernetes.io']['serviceaccount']['name'],attribute.pod=assertion['kubernetes.io']['pod']['name']

Optionally, define anattribute condition.Attribute conditions are CEL expressions that can check assertion attributes andtarget attributes. If the attribute condition evaluates totrue for a givencredential, the credential is accepted. Otherwise, the credential is rejected.

You can use an attribute condition to restrict which Kubernetes ServiceAccountscan use Workload Identity Federation to obtain short-lived Google Cloudtokens.For example, the following condition restricts access to KubernetesServiceAccounts from thebackend andmonitoring namespaces:

assertion['kubernetes.io']['namespace'] in ['backend', 'monitoring']

Create the workload identity pool and provider

To create a workload identity pool and provider, do the following:

Grant access to a Kubernetes workload

This section describes how to configure a Kubernetes workload to accessGoogle Cloud APIs by using either Workload Identity Federation directresource access or service account impersonation.

You must perform these steps once for each Kubernetes workload that needs accessto Google Cloud.

We recommend that you useWorkload Identity Federation. However,when using identity federation, certain API methods might have limitations. Fora list of limitations, seeIdentity federation: products and limitations.

If the methods that your workload uses have such limitations, you can insteaduseIAM impersonation.

Use Workload Identity Federation to grant direct resource access

In this section, you use Workload Identity Federation to grant anIAM role to a Kubernetes ServiceAccount so that it can directlyaccess Google Cloud resources.

To create a Kubernetes ServiceAccount and grant it a role, do the following:

1. Create a Kubernetes ServiceAccount:

   kubectl create serviceaccountKSA_NAME --namespaceNAMESPACE

   Replace the following:

   • KSA_NAME: A name of the ServiceAccount.
   • NAMESPACE: The namespace in which to create theServiceAccount.

2. Grant IAM access to the Kubernetes ServiceAccount for aGoogle Cloud resource.

   Following theprinciple of least privilege,we recommend that you grant only roles that are specific to the resourcesthat your application must access.

   In the following example, the command grants theKubernetes Engine Cluster Viewer(roles/container.clusterViewer) role to the ServiceAccount that youcreated. The command uses the subject that you mapped earlier in thisdocument.

   gcloudprojectsadd-iam-policy-bindingprojects/PROJECT_ID\--role=roles/container.clusterViewer\--member=principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/MAPPED_SUBJECT\--condition=None

   Replace the following:

   • PROJECT_NUMBER: the numericalGoogle Cloud project number that is associated with your projectID.

   • POOL_ID: the workload identity pool ID.

   • MAPPED_SUBJECT: the Kubernetes ServiceAccountfrom the claim in your ID token that you mapped togoogle.subject. For example, if you mappedgoogle.subject=assertions.suband your ID token contains"sub": "system:serviceaccount:default:my-kubernetes-serviceaccount",thenMAPPED_SUBJECT issystem:serviceaccount:default:my-kubernetes-serviceaccount.

   You can grant roles on any Google Cloud resource that supportsIAM allow policies. The syntax of the principal identifierdepends on the Kubernetes resource. For a list of supported identifiers, seePrincipal identifiers for Workload Identity Federation for GKE.

You can nowdeploy a workload that uses the KubernetesServiceAccount to access the Google Cloud resources to which you grantedaccess.

Alternative: Use IAM service account impersonation to grant access

To configure your Kubernetes ServiceAccount to use IAM serviceaccount impersonation, do the following:

1. Create a Kubernetes ServiceAccount, if you haven't already:

   kubectl create serviceaccountKSA_NAME --namespaceNAMESPACE

   Replace the following:

   • KSA_NAME: a name for the ServiceAccount
   • NAMESPACE: the namespace in which to createthe ServiceAccount

2. Create an IAMservice accountthat represents the workload.

   The service account doesn't need to be in the same project as the workloadidentity pool, but you must specify the project that contains the serviceaccount when referring to it.

   gcloud iam service-accounts createIAM_SA_NAME \    --project=IAM_SA_PROJECT_ID

   Replace the following:

   • IAM_SA_NAME: the name of the service account
   • IAM_SA_PROJECT_ID: the project ID of the serviceaccount

3. Grant your IAM service account accessto the specific Google Cloud resources that you want the Kubernetesworkload to access.

   gcloudprojectsadd-iam-policy-bindingIAM_SA_PROJECT_ID\--member="serviceAccount:IAM_SA_NAME@IAM_SA_PROJECT_ID.iam.gserviceaccount.com"\--role="ROLE"

   Replace the following:

   • IAM_SA_PROJECT_ID: the ID of the project whereyou created your service account
   • IAM_SA_NAME: the name of the service account
   • ROLE: with the name of the role—for example,roles/container.clusterViewer

4. Grant the Kubernetes ServiceAccount access to impersonate theIAM service account:

   gcloudiamservice-accountsadd-iam-policy-binding\IAM_SA_NAME@IAM_SA_PROJECT_ID.iam.gserviceaccount.com\--member="principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/MAPPED_SUBJECT"\--role=roles/iam.workloadIdentityUser

   Replace the following:

   • IAM_SA_NAME: the name of the service account
   • PROJECT_ID: the ID of the project where you run Kubernetes
   • IAM_SA_PROJECT_NUMBER: theproject numberof the project where you created your service account
   • POOL_ID: the workload identity pool ID.
   • MAPPED_SUBJECT: the Kubernetes ServiceAccountfrom the claim in your ID token that you mapped togoogle.subject. For example, if you mappedgoogle.subject=assertions.suband your ID token contains"sub": "system:serviceaccount:default:my-kubernetes-serviceaccount",thenMAPPED_SUBJECT issystem:serviceaccount:default:my-kubernetes-serviceaccount.
   Note: You must use the project number in the member identifier. Using theproject ID is not supported.

   For information on authorizing IAM service accounts to accessGoogle Cloud APIs, seeUnderstanding service accounts.

You can nowdeploy a workload that uses the Kubernetes ServiceAccountand the IAM service account to access the Google Cloudresources to which you granted access.

Deploy the Kubernetes workload

To deploy a Kubernetes workload that can access Google Cloud resources, dothe following:

1. Create a credential configuration file:

   gcloudiamworkload-identity-poolscreate-cred-config\projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/WORKLOAD_PROVIDER_ID\--service-account=SERVICE_ACCOUNT_EMAIL\--credential-source-file=/var/run/service-account/token\--credential-source-type=text\--sts-location=REGION\--output-file=credential-configuration.json

   Replace the following:

   • PROJECT_NUMBER: The project number of the project that contains the workload identity pool
   • POOL_ID: The ID of the workload identity pool
   • WORKLOAD_PROVIDER_ID: The ID of the workload identity pool provider
   • SERVICE_ACCOUNT_EMAIL: Email address of the service account, if you configured your Kubernetes ServiceAccount to use IAM service account impersonation. Omit this flag if you configured your Kubernetes ServiceAccount to use direct resource access.
   • REGION: Optional. Specify the region of theregional Security Token Service endpoints,if they are available.

   The credential configuration file lets theCloud Client Libraries, thegcloud CLI, and Terraform determine the following:

   • Where to obtain external credentials from
   • Which workload identity pool and provider to use
   • Which service account to impersonate
   Note: Unlike aservice account key,a credential configuration file doesn't contain a private key and doesn't needto be kept confidential. Details about the credential configuration file areavailable athttps://google.aip.dev/auth/4117.

2. Import the credential configuration file as aConfigMap

   kubectl create configmapCONFIGMAP_NAME \  --from-file credential-configuration.json \  --namespaceNAMESPACE

   Replace the following:

   • CONFIGMAP_NAME: The name of the ConfigMap.
   • NAMESPACE: The namespace in which to create the ConfigMap.

3. Deploy a workload and let it use the Kubernetes ServiceAccount and ConfigMap.

   Create a manifest and configure as follows:

   • Mount aprojected token volumeso that the workload can obtain a Kubernetes ServiceAccount tokenfrom a local file. Configure the volume so that the KubernetesServiceAccount token uses the audience expected by your workloadidentity pool provider.
   • Mount the ConfigMap that contains the credential configuration fileso that the workload can access the necessary configuration for usingWorkload Identity Federation.
   • Add an environment variableGOOGLE_APPLICATION_CREDENTIALS thatcontains the path of the credential configuration file so thatworkloads can find the file.

   The following is an example manifest that uses the Kubernetes ServiceAccountand ConfigMap to let the Google Cloud CLI authenticate to Google Cloud:

   apiVersion:v1kind:Podmetadata:name:examplenamespace:NAMESPACEspec:containers:-name:exampleimage:google/cloud-sdk:alpinecommand:["/bin/sh","-c","gcloud auth login --cred-file $GOOGLE_APPLICATION_CREDENTIALS && gcloud auth list && sleep 600"]volumeMounts:-name:tokenmountPath:"/var/run/service-account"readOnly:true-name:workload-identity-credential-configurationmountPath:"/etc/workload-identity"readOnly:trueenv:-name:GOOGLE_APPLICATION_CREDENTIALSvalue:"/etc/workload-identity/credential-configuration.json"serviceAccountName:KSA_NAMEvolumes:-name:tokenprojected:sources:-serviceAccountToken:audience:https://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/WORKLOAD_PROVIDER_IDexpirationSeconds:3600path:token-name:workload-identity-credential-configurationconfigMap:name:CONFIGMAP_NAME

   You can follow the same approach to let tools and workloads that use one of the followingclient librariesfind credentials automatically:

   C++

   TheGoogle Cloud Client Libraries for C++support Workload Identity Federation since versionv2.6.0.To use Workload Identity Federation, you must build the client librarieswith version 1.36.0 or later of gRPC.

   Go

   Client libraries for Go support Workload Identity Federation if they use versionv0.0.0-20210218202405-ba52d332ba99 or later of thegolang.org/x/oauth2 module.

   To check which version of this module your client library uses, run thefollowing commands:

   cd$GOPATH/src/cloud.google.com/gogolist-mgolang.org/x/oauth2

   Java

   Client libraries for Java support Workload Identity Federation if they use version 0.24.0or later of thecom.google.auth:google-auth-library-oauth2-http artifact.

   To check which version of this artifact your client library uses, run thefollowing Maven command in your application directory:

   mvndependency:list-DincludeArtifactIds=google-auth-library-oauth2-http

   Node.js

   Client libraries for Node.js support Workload Identity Federation if they use version7.0.2 or later of thegoogle-auth-library package.

   To check which version of this package your client library uses, run thefollowing command in your application directory:

   npmlistgoogle-auth-library

   When you create aGoogleAuth object, you can specify a project ID, or you canallowGoogleAuth to find the project ID automatically. To find the project IDautomatically, the service account in the configuration file must have theBrowser role (roles/browser), or a role with equivalent permissions, on yourproject. For details, see theREADME for thegoogle-auth-library package.

   Python

   Client libraries for Python support Workload Identity Federation if they use version1.27.0 or later of thegoogle-auth package.

   To check which version of this package your client library uses, run thefollowing command in the environment where the package is installed:

   pipshowgoogle-auth

   To specify a project ID for the authentication client, you can set theGOOGLE_CLOUD_PROJECT environment variable, or you can allow the client to findthe project ID automatically. To find the project ID automatically, the serviceaccount in the configuration file must have the Browser role (roles/browser),or a role with equivalent permissions, on your project. For details, see theuser guide for thegoogle-auth package.

   gcloud

   To authenticate using Workload Identity Federation, use thegcloud auth login command:

   gcloud auth login --cred-file=FILEPATH.json

   ReplaceFILEPATH with the path to thecredential configuration file.

   Support for Workload Identity Federation in gcloud CLI is available inversion 363.0.0 and later versions of the gcloud CLI.

   Terraform

   TheGoogle Cloud providersupports Workload Identity Federation if you use version 3.61.0 or later:

   terraform {  required_providers {    google = {      source  = "hashicorp/google"      version = "~> 3.61.0"    }  }}

   bq

   To authenticate using Workload Identity Federation, use thegcloud auth login command, as follows:

   gcloud auth login --cred-file=FILEPATH.json

   ReplaceFILEPATH with the path to thecredential configuration file.

   Support for Workload Identity Federation in bq is available inversion 390.0.0 and later versions of the gcloud CLI.

4. Optionally, verify that authentication works correctly by running the following command:

   kubectl exec example --namespaceNAMESPACE -- gcloud auth print-access-token

What's next

• Read more aboutWorkload Identity Federation.
• Learn aboutbest practices for using Workload Identity Federation.
• See how you canmanage workload identity pools and providers.