gh-oidc

GitHub OIDC

This module handles the opinionated creation of infrastructure necessary to configure Workload Identity pools and providers for authenticating to GCP using GitHub Actions OIDC tokens.

This includes:

• Creation of a Workload Identity pool
• Configuring a Workload Identity provider
• Granting external identities necessary IAM roles on Service Accounts

Example Usage

module "gh_oidc" {
  source      = "terraform-google-modules/github-actions-runners/google//modules/gh-oidc"
  project_id  = var.project_id
  pool_id     = "example-pool"
  provider_id = "example-gh-provider"
  sa_mapping = {
    "foo-service-account" = {
      sa_name   = "projects/my-project/serviceAccounts/[email protected]"
      attribute = "attribute.repository/${USER/ORG}/<repo>"
    }
  }
}

Below are some examples:

OIDC Simple

This example shows how to use this module along with a Service Account to access storage buckets.

GitHub Workflow

Once provisioned, you can use the google-github-actions/auth Action in a workflow as shown below

# Example workflow
# .github/workflows/example.yml

name: 'example oidc'
on:
  push:
    branches:
    - 'main'
jobs:
  run:
    name: 'example to list bucket contents'
    permissions:
      id-token: write
      contents: read
    runs-on: 'ubuntu-latest'
    steps:
    - id: 'auth'
      uses: 'google-github-actions/auth@v1'
      with:
        token_format: 'access_token'
        workload_identity_provider: ${{ secrets.PROVIDER_NAME }} # this is the output provider_name from the TF module
        service_account: ${{ secrets.SA_EMAIL }} # this is a SA email configured using the TF module with access to YOUR-GCS-BUCKET
    - id: 'list-buckets-contents'
      run: |-
        curl -sSf https://storage.googleapis.com/storage/v1/b/YOUR-GCS-BUCKET/o \
          --header "Authorization: Bearer ${{ steps.auth.outputs.access_token }}"

Inputs

Name	Description	Type	Default	Required
allowed_audiences	Workload Identity Pool Provider allowed audiences.	list(string)	[]	no
attribute_condition	Workload Identity Pool Provider attribute condition expression. More info	string	null	no
attribute_mapping	Workload Identity Pool Provider attribute mapping. More info	map(any)	{ "attribute.actor": "assertion.actor", "attribute.aud": "assertion.aud", "attribute.repository": "assertion.repository", "google.subject": "assertion.sub" }	no
issuer_uri	Workload Identity Pool Issuer URL	string	"https://token.actions.githubusercontent.com"	no
pool_description	Workload Identity Pool description	string	"Workload Identity Pool managed by Terraform"	no
pool_display_name	Workload Identity Pool display name	string	null	no
pool_id	Workload Identity Pool ID	string	n/a	yes
project_id	The project id to create Workload Identity Pool	string	n/a	yes
provider_description	Workload Identity Pool Provider description	string	"Workload Identity Pool Provider managed by Terraform"	no
provider_display_name	Workload Identity Pool Provider display name	string	null	no
provider_id	Workload Identity Pool Provider id	string	n/a	yes
sa_mapping	Service Account resource names and corresponding WIF provider attributes. If attribute is set to * all identities in the pool are granted access to SAs.	map(object({ sa_name = string attribute = string }))	{}	no

Outputs

Name	Description
pool_name	Pool name
provider_name	Provider name

Requirements

Before this module can be used on a project, you must ensure that the following pre-requisites are fulfilled:

1. Required APIs are activated

   "iam.googleapis.com",
   "cloudresourcemanager.googleapis.com",
   "iamcredentials.googleapis.com",
   "sts.googleapis.com",
   

2. Service Account used to deploy this module has the following roles

   roles/iam.workloadIdentityPoolAdmin
   roles/iam.serviceAccountAdmin