Console

When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

gcloud

In the Google Cloud console, activate Cloud Shell.

Activate Cloud Shell

At the bottom of the Google Cloud console, aCloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

Python

To use the Python samples on this page in a local development environment, install and initialize the gcloud CLI, and then set up Application Default Credentials with your user credentials.

Install the Google Cloud CLI.

If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

If you're using a local shell, then create local authentication credentials for your user account:

gcloudauthapplication-defaultlogin

You don't need to do this if you're using Cloud Shell.

If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

For more information, see Set up ADC for a local development environment in the Google Cloud authentication documentation.

Azure DevOps

To let an Azure DevOps pipeline authenticate to Google Cloud, you firstconfigure a service connection for Azure Resource Manager. This connectionlets the pipeline obtain an ID token, which it can then exchange forGoogle Cloud credentials.

To create a service connection for Azure Resource Manager, do the following:

1. In Azure DevOps, open your project and go toProject Settings.
2. Go toPipelines> Service connections.
3. ClickCreate service connection.
4. SelectAzure Resource Manager.
5. ClickNext.

6. Configure the following settings:

   • Identity type:App registration (automatic)
   • Credential:Workload identity federation

   • Scope level:Subscription.

     You must select a subscription even if you're not planning to usethe service connection to access Azure resources.

   • Service connection name: Enter a name such asgoogle-cloud.

7. ClickSave.

In a later step, you'll need the issuer and subject identifier of theservice connection. To look up these details, do the following:

1. Click the service connection you just created.
2. ClickManage App registration.
3. SelectManage> Certificate & secrets> Federated credentials.
4. Click the federated credential.

5. On theEdit a credential page, find the following identifiers:

   • Issuer: uniquely identifies your Azure DevOps organization
   • Subject identifier: uniquely identifies the service connection

Azure DevOps automatically grants access on the subscription that you selectedas scope to the service principal associated with your new service connection.Because you're not planning to use the service connection to access Azureresources, you can revoke this access by doing the following:

1. In the Azure portal, open the subscription that you selected as scope.
2. Go toAccess control (IAM)> Role assignments.
3. Find the role assignment for the service connection and remove it.

GitHub Actions

You don't need to make any configuration changes in your GitHub account.

After youconfigure a workload identity pool to trust yourGitHub repository, you can let workflows in that repository use theirGitHub OIDC token to obtain short-lived Google Cloud credentials.

GitLab SaaS

You don't need to make any configuration changes in your GitLab account.

After youconfigure a workload identity pool to trustyour GitLab group, you can enable Workload Identity Federation for individualCI/CD jobs.

Terraform Cloud

You don't need to make any configuration changes in your Terraform Cloud account.

After youconfigure a workload identity pool to trustTerraform Cloud, you can enable Workload Identity Federation for individualworkspaces.

Azure DevOps

The Azure DevOps ID token includes asub claim that contains the subjectidentifier of your service connection. The subject identifier uses thefollowing format:

sc://ORGANIZATION/PROJECT/CONNECTION

Use the following attribute mapping to map this identifier togoogle.subject:

google.subject=assertion.sub

GitHub Actions

Your attribute mappings can use any of theclaims in the GitHub ActionsOIDC token. These token claim keys and their values are controlled byGitHub. At minimum, you should mapgoogle.subject toassertion.sub,which corresponds to the GitHub Actions OIDC token subject:

google.subject=assertion.sub

The value for the GitHub Actions OIDC token subjectcan vary depending on thesourceevent. Other claim attributes can include:

• repository: Contains the owner and repository name–for example"google/guava".

• repository_id: Contains the unique repository ID–for example"20300177".

• repository_owner: Contains the owner, which can be a username or thename of a GitHub organization–for example"google".

• repository_owner_id: Contains the unique owner ID–for example"1342004".

This list is a subset of the possible claims–see the GitHubdocumentation onexampleclaims for a complete list. Be sure to map any claims that youplan to use as attribute conditions or as part of a futureprincipalSetcondition.

GitLab SaaS

Your attribute mappings can use theclaims embedded in the GitLab ID token as source attributes, including the following:

• sub: the project name and Git reference—for example,project_path:groupname/projectname:ref_type:branch:ref:main.
• namespace_id: the unique group ID.
• project_id: the unique project ID.
• user_id: the unique user ID.
• environment: the environment that the job applies to.
• ref_path: the Git reference—for examplerefs/heads/main.

The following attribute mapping setsgoogle.subject to thesub claimfrom the GitLab ID token. Because thesub claim containsboth the project name and Git reference, this mapping lets you control accessby 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 otherbranches (for example, feature branches).

In some cases, it might be sufficient to only differentiate access by projector group. The following mapping therefore includes two additional attributesthat contain the GitLabproject_id andnamespace_id:

google.subject=assertion.subattribute.project_id=assertion.project_idattribute.namespace_id=assertion.namespace_id

Terraform Cloud

Your attribute mappings can use the claims embedded in the Terraform CloudOIDC token, including the following

• terraform_organization_id: Contains the unique ID of the organization—forexampleorg-xxxxxxxxxxxxxxxx.
• terraform_workspace_id: Contains theunique ID of the workspace—forexamplews-xxxxxxxxxxxxxxxx.
• terraform_workspace_name: Contains thedisplay name of the workspace.
• sub: Contains the display name of the organization, workspace, and phase—forexampleorganization:example-org:workspace:example-workspace:run_phase:apply.

The following attribute mapping setsgoogle.subject to theterraform_workspace_idclaim from the Terraform Cloud OIDC token:

google.subject=assertion.terraform_workspace_id

This mapping lets you control access to Google Cloud resources by workspace.

Azure DevOps

Optionally, use an attribute condition to restrict access tocertain service connections. For example, the following condition limitsaccess to connections in a certain Azure DevOps project:

assertion.sub.startsWith('sc://ORGANIZATION/PROJECT/')

Replace the following:

• ORGANIZATION: the name of your Azure DevOps organization.
• PROJECT: the name of your Azure DevOps project.

GitHub Actions

Use the following attribute condition to restrict access to tokens issued by yourGitHub organization:

assertion.repository_owner=='ORGANIZATION'

ReplaceORGANIZATION with the name of your GitHuborganization.

Optionally, extend the attribute condition to restrict access to a subset of workflowsor branches. For example, the following condition limits accessto workflows that use the Git branchmain:

assertion.repository_owner=='ORGANIZATION' && assertion.ref=='refs/heads/main'

GitLab SaaS

Use the following attribute condition to restrict access to tokens issued by yourGitLabgroup

assertion.namespace_id=='GROUP_ID'

ReplaceGROUP_ID with the group ID that's shown onyour GitLab group's home page.

Optionally, extend the attribute condition to restrict access to a subset ofprojects, branches, or environments. For example, the following condition limits accessto jobs that use the environmentproduction:

assertion.namespace_id=='GROUP_ID' && assertion.environment=='production'

Terraform Cloud

Use the following attribute condition to restrict access to tokens issued by yourTerraform Cloud organization:

assertion.terraform_organization_id=='ORGANIZATION_ID'

ReplaceORGANIZATION_ID with the unique ID of yourorganization—for exampleorg-xxxxxxxxxxxxxxxx.Optionally, extend the attribute condition to restrict access to a subset of workflowsor branches. For example, the following attribute condition limits accessto a specific workspace:

assertion.terraform_organization_id=='ORGANIZATION_ID' && assertion.terraform_workspace_id=='WORKSPACE_ID'

Console

1. In the Google Cloud console, go to theNew workload provider and poolpage.

   Go to New workload provider and pool

2. UnderCreate 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.

3. ClickContinue.

4. Configure provider settings:

   Azure DevOps

   • Select a provider:OpenID Connect (OIDC).
   • Provider name: the name of the Azure DevOps project, or acustom name.
   • Provider ID: the name of the Azure DevOps project, or acustom ID. You cannot change the provider ID later.
   • Issuer URL: the service connection issuer thatyou've looked up previously.

   • Audiences: SelectAllowed audiences and paste the following value

     api://AzureADTokenExchange

   GitHub Actions

   • Select a provider:OpenID Connect (OIDC).
   • Provider name: Name for the provider.
   • Provider ID: ID for the provider. You cannot change the provider ID later.
   • Issuer URL:https://token.actions.githubusercontent.com/
   • Audiences:Default audience

   GitLab SaaS

   • Select a provider:OpenID Connect (OIDC).
   • Provider name: Name for the provider.
   • Provider ID: ID for the provider. You cannot change the provider ID later.
   • Issuer URL:https://gitlab.com
   • Audiences:Default audience

   Terraform Cloud

   • Select a provider:OpenID Connect (OIDC).
   • Provider name: Name for the provider.
   • Provider ID: ID for the provider. You cannot change the provider ID later.
   • Issuer URL:https://app.terraform.io
   • Audiences:Default audience

5. ClickContinue.

6. UnderConfigure provider attributes, addtheattribute mappings that you've identified previously.

7. UnderAttribute conditions, enter theattribute condition that you've identified previously.

8. ClickSave to create the workload identity pool and provider.

gcloud

1. Create a new workload identity pool:

   gcloud iam workload-identity-pools createPOOL_ID \    --location="global" \    --description="DESCRIPTION" \    --display-name="DISPLAY_NAME"

   Replace the following values:

   • POOL_ID: the unique ID for the pool
   • DISPLAY_NAME: the name of the pool
   • DESCRIPTION: the description of the pool. This descriptionappears when granting access to pool identities

2. Add a workload identity pool provider:

   Azure DevOps

   gcloud iam workload-identity-pools providers create-oidcPROVIDER_ID \    --location="global" \    --workload-identity-pool="POOL_ID" \    --issuer-uri="ISSUER" \    --allowed-audiences="api://AzureADTokenExchange" \    --attribute-mapping="MAPPINGS" \    --attribute-condition="CONDITIONS"

   Replace the following values:

   • PROVIDER_ID: the name of the Azure DevOpsproject, or a custom ID for the provider.
   • POOL_ID: the ID of the pool
   • ISSUER: the service connection issuer thatyou've looked up previously.
   • MAPPINGS: a comma-separated list ofattribute mappings that you've identified previously
   • CONDITIONS: theattribute condition that you identified previously

   GitHub Actions

   gcloud iam workload-identity-pools providers create-oidcPROVIDER_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: the unique ID for the provider
   • POOL_ID: the ID of the pool
   • MAPPINGS: a comma-separated list ofattribute mappings that you've identified previously
   • CONDITIONS: theattribute condition that you identified previously

   GitLab SaaS

   gcloud iam workload-identity-pools providers create-oidcPROVIDER_ID \    --location="global" \    --workload-identity-pool="POOL_ID" \    --issuer-uri="https://gitlab.com" \    --attribute-mapping="MAPPINGS" \    --attribute-condition="CONDITIONS"

   Replace the following values:

   • PROVIDER_ID: the unique ID for the provider
   • POOL_ID: the ID of the pool
   • MAPPINGS: a comma-separated list ofattribute mappings that you've identified previously
   • CONDITIONS: theattribute condition that you identified previously

   Terraform Cloud

   gcloud iam workload-identity-pools providers create-oidcPROVIDER_ID \    --location="global" \    --workload-identity-pool="POOL_ID" \    --issuer-uri="https://app.terraform.io" \    --attribute-mapping="MAPPINGS" \    --attribute-condition="CONDITIONS"

   Replace the following values:

   • PROVIDER_ID: the unique ID for the provider.
   • POOL_ID: the ID of the pool.
   • MAPPINGS: a comma-separated list ofattribute mappings that you've identified previously.
   • CONDITIONS: theattribute condition that you've identified previously.

Console

1. In the Google Cloud console, go to theWorkload Identity Poolspage.

   Go to Workload Identity Pools

2. Find the workload identity pool that contains the provider, and then click thearrow_rightExpand node icon for thepool.

3. Find the workload identity pool provider that you want to edit and clickeditEdit.

4. InAttribute conditions, enter theattribute condition that you've identified previously.

5. To update the workload identity pool and provider, clickSave.

gcloud

To update the workload identity pool provider, run the following command:

gcloud iam workload-identity-pools providers update-oidcPROVIDER_ID \    --location="global" \    --workload-identity-pool="POOL_ID" \    --attribute-condition="CONDITIONS"

Replace the following values:

• PROVIDER_ID: the unique ID for the provider
• POOL_ID: the ID of the pool
• CONDITIONS: theattribute condition that you've identified previously

Direct resource access

You can grant access to a federated identity directly on resources by usingthe Google Cloud console or the gcloud CLI.

Service account impersonation

1. To create a service account for the external workload, do the following:

   1. Enable the IAM, Security Token Service, and Service Account Credentials 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

   2. Create a service accountthat represents the workload. We recommend that youuse a dedicated service account for each workload.The service account doesn't need to be in the same project as theworkload identity pool, but you must refer to the project thatcontains the service account.

   3. Grant the service account accessto resources that you want external identities to access.

2. To let the federated identity impersonate the service account, do thefollowing:

gcloud iam service-accounts add-iam-policy-bindingSERVICE_ACCOUNT_EMAIL \    --role=roles/iam.workloadIdentityUser \    --member="principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT"

gcloud iam service-accounts add-iam-policy-bindingSERVICE_ACCOUNT_EMAIL \    --role=roles/iam.workloadIdentityUser \    --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/group/GROUP"

gcloud iam service-accounts add-iam-policy-bindingSERVICE_ACCOUNT_EMAIL \    --role=roles/iam.workloadIdentityUser \    --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE"

Azure DevOps

Edit yourazure-pipelines.yml file and add the following to yourjob configuration:

variables:- name: Azure.WorkloadIdentity.Connection  value:CONNECTION- name: GoogleCloud.WorkloadIdentity.ProjectNumber  value:PROJECT_NUMBER- name: GoogleCloud.WorkloadIdentity.Pool  value:POOL_ID- name: GoogleCloud.WorkloadIdentity.Provider  value:PROVIDER_ID- name: GoogleCloud.WorkloadIdentity.ServiceAccount  value:SERVICE_ACCOUNT_EMAIL- name: GOOGLE_APPLICATION_CREDENTIALS  value: $(Pipeline.Workspace)/.workload_identity.wlconfigsteps:  - task: AzureCLI@2    inputs:      connectedServiceNameARM: $(Azure.WorkloadIdentity.Connection)      addSpnToEnvironment: true      scriptType: 'bash'      scriptLocation: 'inlineScript'      inlineScript: |        echo $idToken > $(Pipeline.Workspace)/.workload_identity.jwt        cat<< EOF > $GOOGLE_APPLICATION_CREDENTIALS        {          "type": "external_account",          "audience": "//iam.googleapis.com/projects/$(GoogleCloud.WorkloadIdentity.ProjectNumber)/locations/global/workloadIdentityPools/$(GoogleCloud.WorkloadIdentity.Pool)/providers/$(GoogleCloud.WorkloadIdentity.Provider)",          "subject_token_type": "urn:ietf:params:oauth:token-type:jwt",          "token_url": "https://sts.REGION.rep.googleapis.com/v1/token",          "credential_source": {            "file": "$(Pipeline.Workspace)/.workload_identity.jwt"          },          "service_account_impersonation_url": "https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/$(GoogleCloud.WorkloadIdentity.ServiceAccount):generateAccessToken"        }        EOF

Replace the following values:

• CONNECTION: The name of your service connection.
• PROJECT_NUMBER: The project number of the projectthat contains the workload identity pool.
• POOL_ID: The ID of the workload identity pool.
• PROVIDER_ID: The ID of the workload identitypool provider.
• SERVICE_ACCOUNT_EMAIL: The email address of theservice account, if you use service account impersonation. If you usedirect resource access, omitGoogleCloud.WorkloadIdentity.ServiceAccount andservice_account_impersonation_url.
• REGION: A region forregional STS endpoints,if they are available. If regional endpoints aren't available, you canuse https://sts.googleapis.com/v1/token.

The configuration does the following:

1. Uses theAzureCLI taskto obtain an ID token for the service connection, and makes it availablein a variable namedidToken.
2. Saves the ID token to a temporary file named.workload_identity.jwt.
3. Creates a credential configuration file that instructs client librariesto read the ID token from.workload_identity.jwt and uses it to impersonatea service account.
4. Sets the environment variableGOOGLE_APPLICATION_CREDENTIALS to pointto the credential configuration file.

GitHub Actions

Thegoogle-github-actions/auth action lets you automatically generate a credential configuration fileduring workflow execution. Client libraries and tools such asterraformcan then use this credential configuration file to automatically obtainGoogle credentials.

Edit your GitHub Actions YAML file and add the following:

• Allow the job to fetch a GitHub ID token by adding the followingconfiguration:

  permissions:  id-token: write  contents: read

• Add a step to create a credentials configuration file:

  - id: 'auth'  name: 'Authenticate to Google Cloud'  uses: 'google-github-actions/auth@v1'  with:    create_credentials_file: true    workload_identity_provider: 'projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID'    service_account: 'SERVICE_ACCOUNT_EMAIL'

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.
• PROVIDER_ID: The ID of the workload identity pool provider.
• SERVICE_ACCOUNT_EMAIL: The email address of the service account, if you use service account impersonation. If you use direct resource access, omitservice_account.

The following example configures the GitHub Action:

jobs:  build:    # Allow the job to fetch a GitHub ID token    permissions:      id-token: write      contents: read    runs-on: ubuntu-latest    steps:      - uses: actions/checkout@v3      - id: 'auth'        name: 'Authenticate to Google Cloud'        uses: 'google-github-actions/auth@v1'        with:          create_credentials_file: true          workload_identity_provider: 'projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID'          service_account: 'SERVICE_ACCOUNT_EMAIL'

For further details on using thegoogle-github-actions/auth action,seeSetting up Workload Identity Federation.

GitLab SaaS

Edit your.gitlab-ci.yml file and add the following to the jobconfiguration:

job:  variables:    WORKLOAD_IDENTITY_PROJECT_NUMBER:PROJECT_NUMBER    WORKLOAD_IDENTITY_POOL:POOL_ID    WORKLOAD_IDENTITY_PROVIDER:PROVIDER_ID    SERVICE_ACCOUNT:SERVICE_ACCOUNT_EMAIL    GOOGLE_APPLICATION_CREDENTIALS: $CI_BUILDS_DIR/.workload_identity.wlconfig  id_tokens:    WORKLOAD_IDENTITY_TOKEN:      aud: https://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID  script:    - |-      echo $WORKLOAD_IDENTITY_TOKEN > $CI_BUILDS_DIR/.workload_identity.jwt      cat<< EOF > $GOOGLE_APPLICATION_CREDENTIALS      {        "type": "external_account",        "audience": "//iam.googleapis.com/projects/$WORKLOAD_IDENTITY_PROJECT_NUMBER/locations/global/workloadIdentityPools/$WORKLOAD_IDENTITY_POOL/providers/$WORKLOAD_IDENTITY_PROVIDER",        "subject_token_type": "urn:ietf:params:oauth:token-type:jwt",        "token_url": "https://sts.REGION.rep.googleapis.com/v1/token",        "credential_source": {          "file": "$CI_BUILDS_DIR/.workload_identity.jwt"        },        "service_account_impersonation_url": "https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/$SERVICE_ACCOUNT:generateAccessToken"      }      EOF

Replace the following values:

• PROJECT_NUMBER: The project number of theproject that contains the workload identity pool.
• POOL_ID: The ID of the workload identity pool.
• PROVIDER_ID: The ID of the workload identitypool provider.
• SERVICE_ACCOUNT_EMAIL: The email address of theservice account, if you use service account impersonation. If youuse direct resource access, omitSERVICE_ACCOUNTandservice_account_impersonation_url.
• REGION: A region forregional STS endpoints,if they are available. If regional endpoints aren't available, you canuse https://sts.googleapis.com/v1/token.

The configuration does the following:

1. Instructs GitLab to issue an ID token, and makes it available in theenvironment variable namedWORKLOAD_IDENTITY_TOKEN. The ID tokenuses your workload identity pool provider as audience.
2. Saves the ID token to a temporary file named.workload_identity.jwt.
3. Creates a credential configuration file that instructs client librariesto read the ID token from.workload_identity.jwt and uses it toimpersonate a service account.
4. Sets the environment variableGOOGLE_APPLICATION_CREDENTIALS to pointto the credential configuration file.

Terraform Cloud

Configure your Terraform Cloud workspace so that it usesWorkload Identity Federation to authenticate to Google Cloud usingservice account impersonation:

1. In Terraform Cloud, open your workspace and go toVariables.

2. Add the following variables:

   Variable category	Key	Value
   Environment variable	TFC_GCP_PROVIDER_AUTH	true
   Environment variable	TFC_GCP_RUN_SERVICE_ACCOUNT_EMAIL	The email address of the service account, if you use service account impersonation—for example,terraform@my-project-123.iam.gserviceaccount.com. Omit this environment variable if you use direct resource access.
   Environment variable	TFC_GCP_PROJECT_NUMBER	The project number of the project that contains the workload identity pool
   Environment variable	TFC_GCP_WORKLOAD_POOL_ID	The ID of the workload identity pool
   Environment variable	TFC_GCP_WORKLOAD_PROVIDER_ID	The ID of the workload identity pool provider

   Optionally, if you use service account impersonation, you can addadditional environment variables to let Terraform Cloud use differentservice accounts for theplan andapply phases. For moreinformation about using environment variables in Terraformconfigurations, seeOptional Environment Variables.

3. In the list of variables, verify thatCategory is set toenv forthe five variables that you added in the previous step.

4. Verify that your Terraform configuration uses version4.48.0 or newerof the Google Cloud provider, and update it if necessary, as follows:

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

5. Submit the changes to your source code repository.