Authenticate to Google Cloud (GCP) from GitHub Actions Using OIDC and Workload Identity Federation

In this article, we will learn how to securely authenticate GitHub Actions to Google Cloud Platform (GCP) using OpenID Connect (OIDC) and Workload Identity Federation. This approach eliminates the need for long-lived service account keys by enabling short-lived, federated credentials, improving security and simplifying credential management in your CI/CD pipelines.

Architecture Overview of process to authenticate to Google Cloud (GCP) from GitHub Actions Using OIDC and Workload Identity Federation

Architecture Overview

1. GitHub Actions requests an OIDC token from GitHub.
2. GitHub exchanges the token with Google Cloud through Workload Identity Federation.
3. Google validates the token against the configured Workload Identity Provider.
4. Google issues short-lived credentials by impersonating the target Service Account.
5. GitHub Actions uses these credentials to access GCP resources securely without storing service account keys.

Prerequisites

Before you begin, ensure you have the following:

• A Google Cloud (GCP) project with billing enabled.
• Appropriate permissions to create and manage IAM resources in GCP.
• A GitHub repository where your GitHub Actions workflow will run.
• Google Cloud CLI (gcloud) installed and configured locally (optional but recommended for setup and verification).

Steps Involved

1. Enable Required Google Cloud APIs
2. Create a GCP Service Account
3. Grant Required IAM Roles to GCP Service Account
4. Create a Workload Identity Pool
5. Create a Workload Identity Provider
6. Allow GitHub to Impersonate the Service Account
7. Configure GitHub Actions Workflow to generate OIDC token and to Authenticate to GCP
8. Verify Access to GCP Resources

Enable Required Google Cloud APIs

• Login to Google Cloud using gcloud cli.
• Replace GCP_PROJECT_ID with your GCP Project ID.

gcloud auth login
gcloud config set project GCP_PROJECT_ID

• Enable the APIs required for Workload Identity Federation and service account impersonation such as IAM Service Account Credentials API, Cloud Resource Manager API.
• Enable other APIs as well as per your requirements.

gcloud services enable \
    iamcredentials.googleapis.com \
    cloudresourcemanager.googleapis.com \
    --project=GCP_PROJECT_ID

Create a GCP Service Account

• Create a dedicated service account that GitHub Actions will use to access Google Cloud resources securely.
• Replace SERVICE_ACCOUNT_NAME, SERVICE_ACCOUNT_DISPLAY_NAME, GCP_PROJECT_ID with your corresponding values.

gcloud iam service-accounts create "SERVICE_ACCOUNT_NAME" \
--project="GCP_PROJECT_ID" \
--display-name="SERVICE_ACCOUNT_DISPLAY_NAME"

Grant Required IAM Roles to GCP Service Account

• Assign only the necessary IAM roles to GCP Service Account following the principle of least privilege.

gcloud projects add-iam-policy-binding GCP_PROJECT_ID \
  --member="serviceAccount:SERVICE_ACCOUNT_NAME@GCP_PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/viewer"

Create a Workload Identity Pool

• Set up a Workload Identity Pool to establish a trust relationship between GitHub and Google Cloud.
• Replace WORKLOAD_IDENTITY_POOL_NAME, WORKLOAD_IDENTITY_POOL_DISPLAY_NAME, GCP_PROJECT_ID with your corresponding values.

gcloud iam workload-identity-pools create "WORKLOAD_IDENTITY_POOL_NAME" \
  --project="GCP_PROJECT_ID" \
  --location="global" \
  --display-name="WORKLOAD_IDENTITY_POOL_DISPLAY_NAME"

Create a Workload Identity Provider

• Configure GitHub’s OIDC provider and define attribute mappings that Google Cloud will use to validate incoming tokens.
• Replace GITHUB_OIDC_PROVIDER_NAME, GITHUB_OIDC_PROVIDER_DISPLAY_NAME, GCP_PROJECT_ID, WORKLOAD_IDENTITY_POOL_NAME values as per your configuration.
• YOUR_GITHUB_ORG & YOUR_REPO_NAME values can be obtained from your GitHub repo URL https://github.com/**YOUR_GITHUB_ORG/YOUR_REPO_NAME**

gcloud iam workload-identity-pools providers create-oidc "GITHUB_OIDC_PROVIDER_NAME" \
--project="GCP_PROJECT_ID" \
--location="global" \
--workload-identity-pool="WORKLOAD_IDENTITY_POOL_NAME" \
--display-name="GITHUB_OIDC_PROVIDER_DISPLAY_NAME" \
--issuer-uri="https://token.actions.githubusercontent.com" \
--attribute-mapping="google.subject=assertion.sub,attribute.repository=assertion.repository,attribute.actor=assertion.actor" \
--attribute-condition="assertion.repository == 'YOUR_GITHUB_ORG/YOUR_REPO_NAME'"

To configure OIDC authentication for mutiple GitHub repos, use below attribute-condition.

- attribute-condition="assertion.repository in ['your-org/repo-one', 'your-org/repo-two', 'your-org/repo-three']"

Allow GitHub to Impersonate the Service Account

• Grant the Workload Identity Provider permission to impersonate the target service account and obtain temporary credentials.
• Replace SERVICE_ACCOUNT_NAME, GCP_PROJECT_ID, GCP_PROJECT_NUMBER, WORKLOAD_IDENTITY_POOL_NAME, YOUR_GITHUB_ORG & YOUR_REPO_NAME values as per your configuration.

gcloud iam service-accounts add-iam-policy-binding "SERVICE_ACCOUNT_NAME@GCP_PROJECT_ID.iam.gserviceaccount.com" \
--project="GCP_PROJECT_ID" \
--role="roles/iam.workloadIdentityUser" \
--member="principalSet://iam.googleapis.com/projects/GCP_PROJECT_NUMBER/locations/global/workloadIdentityPools/WORKLOAD_IDENTITY_POOL_NAME/attribute.repository/YOUR_GITHUB_ORG/YOUR_REPO_NAME"

Configure GitHub Actions Workflow to generate OIDC token and to Authenticate to GCP

• Create a GitHub Actions workflow under the path .github/workflows/gcp-oidc-authentication.yml in the same repository that you have configured in Create a Workload Identity Provider step.
• Use below command to get workload_identity_provider value to be used with google-github-actions/auth@v3 action in the workflow.

gcloud iam workload-identity-pools providers describe GITHUB_OIDC_PROVIDER_NAME \
    --workload-identity-pool=WORKLOAD_IDENTITY_POOL_NAME \
    --location=global \
    --project=GCP_PROJECT_ID \
    --format="value(name)"

.github/workflows/gcp-oidc-authentication.yml

name: Authenticate to Google Cloud from GitHub Actions Using OIDC

on:
    # push:
    #     branches: [main]

    workflow_dispatch:

# Required for OIDC token generation
permissions:
    contents: read
    id-token: write

jobs:
    deploy:
        runs-on: ubuntu-latest

        steps:

            # Authenticate to GCP using Workload Identity Federation
            - name: Authenticate to Google Cloud
              id: auth
              uses: google-github-actions/auth@v3
              with:
                  token_format: "access_token"
                  workload_identity_provider: "projects/GCP_PROJECT_NUMBER/locations/global/workloadIdentityPools/WORKLOAD_IDENTITY_POOL_NAME/providers/GITHUB_OIDC_PROVIDER_NAME"
                  service_account: "SERVICE_ACCOUNT_NAME@project-GCP_PROJECT_ID.iam.gserviceaccount.com"

            # Now you can use gcloud, gsutil, etc.
            - name: Set up Cloud SDK
              uses: google-github-actions/setup-gcloud@v3

            - name: Get project list
              run: |
                  # Get the full provider resource name
                    gcloud config set project GCP_PROJECT_ID
                    gcloud projects list

• Commit your workflow changes to your GitHub Repo.

Verify Access to GCP Resources

• Test the authentication setup by running Google Cloud commands or accessing resources from the workflow.
• Go to your GitHub Repo (where you have created the workflow file .github/workflows/gcp-oidc-authentication.yml) and click on Actions tab.

Conclusion

By leveraging GitHub OIDC and Google Cloud Workload Identity Federation, you can securely authenticate GitHub Actions to GCP without storing long-lived service account keys. This keyless authentication approach improves security, simplifies credential management, and aligns with modern cloud security best practices.

In this article, we configured a Workload Identity Pool and Provider, granted the necessary IAM permissions, and integrated GitHub Actions with Google Cloud using federated identities. With this setup in place, your CI/CD pipelines can securely access GCP resources using short-lived credentials, reducing operational overhead and minimizing the risk of credential exposure.

If you found this article helpful, please give a clap 👏 and consider following me for more DevOps, Cloud, and Infrastructure related tutorials 😊.