Configuring OpenID Connect in Google Cloud Platform

Use OpenID Connect within your workflows to authenticate with Google Cloud Platform.

Overview

OpenID Connect (OIDC) allows your GitHub Actions workflows to access resources in Google Cloud Platform (GCP), without needing to store the GCP credentials as long-lived GitHub secrets.

This guide gives an overview of how to configure GCP to trust GitHub's OIDC as a federated identity, and includes a workflow example for the google-github-actions/auth action that uses tokens to authenticate to GCP and access resources.

Prerequisites

  • To learn the basic concepts of how GitHub uses OpenID Connect (OIDC), and its architecture and benefits, see "About security hardening with OpenID Connect."

  • Before proceeding, you must plan your security strategy to ensure that access tokens are only allocated in a predictable way. To control how your cloud provider issues access tokens, you must define at least one condition, so that untrusted repositories can’t request access tokens for your cloud resources. For more information, see "Configuring the OIDC trust with the cloud."

Adding a Google Cloud Workload Identity Provider

To configure the OIDC identity provider in GCP, you will need to perform the following configuration. For instructions on making these changes, refer to the GCP documentation.

  1. Create a new identity pool.
  2. Configure the mapping and add conditions.
  3. Connect the new pool to a service account.

Additional guidance for configuring the identity provider:

Updating your GitHub Actions workflow

To update your workflows for OIDC, you will need to make two changes to your YAML:

  1. Add permissions settings for the token.
  2. Use the google-github-actions/auth action to exchange the OIDC token (JWT) for a cloud access token.

Adding permissions settings

The workflow will require a permissions setting with a defined id-token value. If you only need to fetch an OIDC token for a single job, then this permission can be set within that job. For example:

YAML
permissions:
  id-token: write

You may need to specify additional permissions here, depending on your workflow's requirements.

Requesting the access token

The google-github-actions/auth action receives a JWT from the GitHub OIDC provider, and then requests an access token from GCP. For more information, see the GCP documentation.

This example has a job called Get_OIDC_ID_token that uses actions to request a list of services from GCP.

  • <example-workload-identity-provider>: Replace this with the path to your identity provider in GCP. For example, projects/<example-project-id>/locations/global/workloadIdentityPools/<name-of-pool/providers/<name-of-provider>
  • <example-service-account>: Replace this with the name of your service account in GCP.
  • <project-id>: Replace this with the ID of your GCP project.

This action exchanges a GitHub OIDC token for a Google Cloud access token, using Workload Identity Federation.

YAML
name: List services in GCP
on:
  pull_request:
    branches:
      - main

permissions:
  id-token: write

jobs:
  Get_OIDC_ID_token:
    runs-on: ubuntu-latest
    steps:
    - id: 'auth'
      name: 'Authenticate to GCP'
      uses: 'google-github-actions/auth@v0.3.1'
      with:
          create_credentials_file: 'true'
          workload_identity_provider: '<example-workload-identity-provider>'
          service_account: '<example-service-account>'
    - id: 'gcloud'
      name: 'gcloud'
      run: |-
        gcloud auth login --brief --cred-file="${{ steps.auth.outputs.credentials_file_path }}"
        gcloud services list

Did this doc help you?

Privacy policy

Help us make these docs great!

All GitHub docs are open source. See something that's wrong or unclear? Submit a pull request.

Make a contribution

Or, learn how to contribute.