Google Cloud Workload Identity for GitLab

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

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 GitHub and Bitbucket.

Example

Warning GitLab SaaS 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 GitLab group.

Create Workload Identity Pool and Provider:

# Create Workload Identity Pool Provider for GitLab and restrict access to GitLab group
module "gitlab-wif" {
  source     = "Cyclenerd/wif-gitlab/google"
  version    = "~> 2.0.0"
  project_id = var.project_id
  # Restrict access to username or the name of a GitLab group
  attribute_condition = "assertion.namespace_path == '${var.gitlab_group}'"
}

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

An example of a working GitLab CI configuration (.gitlab-ci.yml) can be found here.

Allow service account to login via Workload Identity Provider and limit login only from the GitLab repository (project path) octo-org/octo-repo:

# Get existing service account for GitLab CI
data "google_service_account" "gitlab" {
  project    = var.project_id
  account_id = "existing-account-for-gitlab-ci"
}

# Allow service account to login via WIF and only from GitLab repository (project path)
module "gitlab-service-account" {
  source     = "Cyclenerd/wif-service-account/google"
  version    = "~> 1.0.0"
  project_id = var.project_id
  pool_name  = module.gitlab-wif.pool_name
  account_id = data.google_service_account.gitlab.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 (project_path:{group}/{project}:ref_type:{type}:ref:{branch_name}) 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.project_path	The repository (project path) from where the workflow is running
attribute.aud	assertion.aud	Intended audience for the token. Specified in the ID tokens configuration. The domain of the GitLab instance by default.
attribute.iss	assertion.iss	Issuer of the token, which is the domain of the GitLab instance.
attribute.namespace_id	assertion.namespace_id	Use this to scope to group or user level namespace by ID.
attribute.namespace_path	assertion.namespace_path	Use this to scope to group or user level namespace by path.
attribute.project_id	assertion.project_id	Use this to scope to project by ID.
attribute.project_path	assertion.project_path	Use this to scope to project by path.
attribute.user_id	assertion.user_id	ID of the user executing the job.
attribute.user_login	assertion.user_login	Username of the user executing the job.
attribute.user_email	assertion.user_email	Email of the user executing the job.
attribute.pipeline_id	assertion.pipeline_id	ID of the pipeline.
attribute.pipeline_source	assertion.pipeline_source	Pipeline source.
attribute.job_id	assertion.job_id	ID of the job.
attribute.ref	assertion.ref	Git ref for the job.
attribute.ref_type	assertion.ref_type	Git ref type, either branch or tag.
attribute.ref_protected	assertion.ref_protected	true if the Git ref is protected, false otherwise.
attribute.environment	assertion.environment	Environment this job deploys to (introduced in GitLab 13.9).
attribute.environment_protected	assertion.environment_protected	true if deployed environment is protected, false otherwise (introduced in GitLab 13.9).
attribute.deployment_tier	assertion.deployment_tier	Deployment tier of the environment the job specifies. Introduced in GitLab 15.2.
attribute.runner_id	assertion.runner_id	ID of the runner executing the job. Introduced in GitLab 16.0.
attribute.runner_environment	assertion.runner_environment	The type of runner used by the job. Can be either gitlab-hosted or self-hosted. Introduced in GitLab 16.0.
attribute.sha	assertion.sha	The commit SHA for the job. Introduced in GitLab 16.0.

Providers

Name	Version
google	>= 4.61.0

Inputs

Name	Description	Type	Default	Required
allowed_audiences	Workload Identity Pool Provider allowed audiences	list(string)	[ "https://gitlab.com" ]	no
attribute_condition	(Optional) Workload Identity Pool Provider attribute condition expression	string	null	no
attribute_mapping	Workload Identity Pool Provider attribute mapping	map(string)	{ "attribute.aud": "attribute.aud", "attribute.deployment_tier": "assertion.deployment_tier", "attribute.environment": "assertion.environment", "attribute.environment_protected": "assertion.environment_protected", "attribute.iss": "attribute.iss", "attribute.job_id": "assertion.job_id", "attribute.namespace_id": "assertion.namespace_id", "attribute.namespace_path": "assertion.namespace_path", "attribute.pipeline_id": "assertion.pipeline_id", "attribute.pipeline_source": "assertion.pipeline_source", "attribute.project_id": "assertion.project_id", "attribute.project_path": "assertion.project_path", "attribute.ref": "assertion.ref", "attribute.ref_protected": "assertion.ref_protected", "attribute.ref_type": "assertion.ref_type", "attribute.repository": "assertion.project_path", "attribute.runner_environment": "assertion.runner_environment", "attribute.sha": "assertion.sha", "attribute.sub": "attribute.sub", "attribute.user_email": "assertion.user_email", "attribute.user_id": "assertion.user_id", "attribute.user_login": "assertion.user_login", "google.subject": "assertion.sub" }	no
issuer_uri	Workload Identity Pool Provider issuer URI	string	"https://gitlab.com"	no
pool_description	Workload Identity Pool description	string	"Workload Identity Pool for GitLab (Terraform managed)"	no
pool_disabled	Workload Identity Pool disabled	bool	false	no
pool_display_name	Workload Identity Pool display name	string	"gitlab.com"	no
pool_id	Workload Identity Pool ID	string	"gitlab-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 GitLab (Terraform managed)"	no
provider_disabled	Workload Identity Pool Provider disabled	bool	false	no
provider_display_name	Workload Identity Pool Provider display name	string	"gitlab.com OIDC"	no
provider_id	Workload Identity Pool Provider ID	string	"gitlab-com-oidc"	no

Outputs

Name	Description
pool_id	Identifier for the pool
pool_name	The resource 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.