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/foo-service-account@my-project.iam.gserviceaccount.com"
      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:

Required APIs are activated

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

Service Account used to deploy this module has the following roles

roles/iam.workloadIdentityPoolAdmin
roles/iam.serviceAccountAdmin