Google Cloud Workload Identity for GitHub

This Terraform module creates a Workload Identity Pool and Provider for GitHub.

Service account keys are a security risk if compromised. Avoid service account keys and instead use the Workload Identity Federation. For more information about Workload Identity Federation and how to best authenticate service accounts on Google Cloud, please see my GitHub repo Cyclenerd/google-workload-identity-federation.

There are also a ready-to-use Terraform modules for GitLab and Bitbucket.

Example

Warning GitHub use a single issuer URL across all organizations and some of the claims embedded in OIDC tokens might not be unique to your organization. To help protect against spoofing threats, you must use an attribute condition that restricts access to tokens issued by your GitHub organization.

Create Workload Identity Pool and Provider:

# Create Workload Identity Pool Provider for GitHub and restrict access to GitHub organization
module "github-wif" {
  source     = "Cyclenerd/wif-github/google"
  version    = "~> 1.0.0"
  project_id = var.project_id
  # Restrict access to username or the name of a GitHub organization
  attribute_condition = "assertion.repository_owner == '${var.github_organization}'"
}

# Get the Workload Identity Pool Provider resource name for GitHub Actions configuration
output "github-workload-identity-provider" {
  description = "The Workload Identity Provider resource name"
  value       = module.github-wif.provider_name
}

An example of a working GitHub Actions configuration can be found here.

Allow service account to login via Workload Identity Provider and limit login only from the GitHub repository octo-org/octo-repo:

# Get existing service account for GitHub Actions
data "google_service_account" "github" {
  project    = var.project_id
  account_id = "existing-account-for-github-action"
}

# Allow service account to login via WIF and only from GitHub repository
module "github-service-account" {
  source     = "Cyclenerd/wif-service-account/google"
  version    = "~> 1.0.0"
  project_id = var.project_id
  pool_name  = module.github-wif.pool_name
  account_id = data.google_service_account.github.account_id
  repository = "octo-org/octo-repo"
}

Terraform module Cyclenerd/wif-service-account/google is used.

👉 More examples

OIDC Token Attribute Mapping

The attributes attribute.sub and attribute.repository are used in the Terrform module Cyclenerd/wif-service-account/google. Please do not remove these attributes.

Default attribute mapping:

Attribute	Claim	Description
google.subject	assertion.sub	Subject
attribute.sub	assertion.sub	Defines the subject claim that is to be validated by the cloud provider. This setting is essential for making sure that access tokens are only allocated in a predictable way.
attribute.repository	assertion.repository	The repository from where the workflow is running
attribute.aud	assertion.aud	Audience
attribute.iss	assertion.iss	The issuer of the OIDC token: https://token.actions.githubusercontent.com
attribute.actor	assertion.actor	The personal account that initiated the workflow run.
attribute.actor_id	assertion.actor_id	The ID of personal account that initiated the workflow run.
attribute.base_ref	assertion.base_ref	The target branch of the pull request in a workflow run.
attribute.environment	assertion.environment	The name of the environment used by the job.
attribute.event_name	assertion.event_name	The name of the event that triggered the workflow run.
attribute.head_ref	assertion.head_ref	The source branch of the pull request in a workflow run.
attribute.job_workflow_ref	assertion.job_workflow_ref	For jobs using a reusable workflow, the ref path to the reusable workflow. For more information, see Using OpenID Connect with reusable workflows.
attribute.job_workflow_sha	assertion.job_workflow_sha	For jobs using a reusable workflow, the commit SHA for the reusable workflow file.
attribute.ref	assertion.ref	(Reference) The git ref that triggered the workflow run.
attribute.ref_type	assertion.ref_type	The type of ref, for example: "branch".
attribute.repository_visibility	assertion.repository_visibility	The visibility of the repository where the workflow is running. Accepts the following values: internal, private, or public.
attribute.repository_id	assertion.repository_id	The ID of the repository from where the workflow is running.
attribute.repository_owner	assertion.repository_owner	The name of the organization in which the repository is stored.
attribute.repository_owner_id	assertion.repository_owner_id	The ID of the organization in which the repository is stored.
attribute.run_id	assertion.run_id	The ID of the workflow run that triggered the workflow.
attribute.run_number	assertion.run_number	The number of times this workflow has been run.
attribute.run_attempt	assertion.run_attempt	The number of times this workflow run has been retried.
attribute.runner_environment	assertion.runner_environment	The type of runner used by the job. Accepts the following values: github-hosted or self-hosted.
attribute.workflow	assertion.workflow	The name of the workflow.
attribute.workflow_ref	assertion.workflow_ref	The ref path to the workflow. For example, octocat/hello-world/.github/workflows/my-workflow.yml@refs/heads/my_branch.
attribute.workflow_sha	assertion.workflow_sha	The commit SHA for the workflow file.

Providers

Name	Version
google	4.62.0

Inputs

Name	Description	Type	Default	Required
attribute_condition	(Optional) Workload Identity Pool Provider attribute condition expression	string	null	no
attribute_mapping	Workload Identity Pool Provider attribute mapping	map(string)	{ "attribute.actor": "assertion.actor", "attribute.actor_id": "assertion.actor_id", "attribute.aud": "attribute.aud", "attribute.base_ref": "assertion.base_ref", "attribute.environment": "assertion.environment", "attribute.event_name": "assertion.event_name", "attribute.head_ref": "assertion.head_ref", "attribute.iss": "attribute.iss", "attribute.job_workflow_ref": "assertion.job_workflow_ref", "attribute.job_workflow_sha": "assertion.job_workflow_sha", "attribute.ref": "assertion.ref", "attribute.ref_type": "assertion.ref_type", "attribute.repository": "assertion.repository", "attribute.repository_id": "assertion.repository_id", "attribute.repository_owner": "assertion.repository_owner", "attribute.repository_owner_id": "assertion.repository_owner_id", "attribute.repository_visibility": "assertion.repository_visibility", "attribute.run_attempt": "assertion.run_attempt", "attribute.run_id": "assertion.run_id", "attribute.run_number": "assertion.run_number", "attribute.runner_environment": "assertion.runner_environment", "attribute.sub": "attribute.sub", "attribute.workflow": "assertion.workflow", "attribute.workflow_ref": "assertion.workflow_ref", "attribute.workflow_sha": "assertion.workflow_sha", "google.subject": "assertion.sub" }	no
issuer_uri	Workload Identity Pool Provider issuer URI	string	"https://token.actions.githubusercontent.com"	no
pool_description	Workload Identity Pool description	string	"Workload Identity Pool for GitHub (Terraform managed)"	no
pool_disabled	Workload Identity Pool disabled	bool	false	no
pool_display_name	Workload Identity Pool display name	string	"github.com"	no
pool_id	Workload Identity Pool ID	string	"github-com"	no
project_id	The ID of the project	string	n/a	yes
provider_description	Workload Identity Pool Provider description	string	"Workload Identity Pool Provider for GitHub (Terraform managed)"	no
provider_disabled	Workload Identity Pool Provider disabled	bool	false	no
provider_display_name	Workload Identity Pool Provider display name	string	"github.com OIDC"	no
provider_id	Workload Identity Pool Provider ID	string	"github-com-oidc"	no

Outputs

Name	Description
pool_id	Identifier for the pool
pool_name	Name for the pool
pool_state	State of the pool
provider_id	Identifier for the provider
provider_name	The resource name of the provider
provider_state	State of the provider

License

All files in this repository are under the Apache License, Version 2.0 unless noted otherwise.

Based on Terraform module for workload identity federation on GCP by Michael S.