Skip to content

Latest commit

 

History

History
112 lines (89 loc) · 4.77 KB

README.md

File metadata and controls

112 lines (89 loc) · 4.77 KB

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