Google Cloud Workload Identity for Jenkins

This Terraform module creates a Workload Identity Pool and Provider for Jenkins with the OpenID Connect Provider plugin.

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.

You are also welcome to take a look at the comprehensive blueprint which describes in more detail how to securely connect Jenkins to Google Cloud Platform (GCP) using Workload Identity Federation.

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

Example

Create Workload Identity Pool and Provider:

# Create Workload Identity Pool Provider for Jenkins
module "jenkins-wif" {
  source            = "Cyclenerd/wif-jenkins/google"
  version           = "~> 1.0"
  project_id        = var.project_id
  issuer_uri        = "https://jenkins.localhost"
  allowed_audiences = ["https://jenkins.localhost"]
  # Export of public OIDC JSON Web Key (JWK) file
  jwks_json_file    = "jenkins-jwk.json"
}

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

Allow service account to login via Workload Identity Provider and limit login only from the Jenkins build gcp-test with URL http://jenkins.localhost:2529/job/gcp-test/:

# Get existing service account for Jenkins
data "google_service_account" "jenkins" {
  project    = var.project_id
  account_id = "existing-account-for-jenkins"
}

# Allow service account to login via WIF and only from Jenkins build gcp-test
module "jenkins-service-account" {
  source     = "Cyclenerd/wif-service-account/google"
  version    = "~> 1.1"
  project_id = var.project_id
  pool_name  = module.jenkins-wif.pool_name
  account_id = data.google_service_account.jenkins.account_id
  subject    = "http://jenkins.localhost:2529/job/gcp-test/"
}

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

👉 More examples

Known Errors

Whitespace Changes

The JSON file does not match the format stored in Google Cloud. This means that every Terraform plan will result in a drift:

jwks_json = jsonencode( # whitespace changes

Please see also the GitHub Issue.

To work around the issue, the JWK stored in Google Cloud can be downloaded and the JSON file must be overwritten manually. It will then be in the same format as in Google Cloud.

Example to download the JWK:

gcloud iam workload-identity-pools providers describe "jenkins-oidc" \
    --workload-identity-pool="jenkins" \
    --location="global" \
    --project="YOUR-PROJECT" \
    --format="json" | jq -er '.oidc.jwksJson' | sed -e 's/\\"/"/g' -e 's/\\n/\n/g' | perl -pe 'chomp if eof' > "jwks.json"

OIDC Token Attribute Mapping

The attributes attribute.sub is 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.aud	assertion.aud	Intended audience for the token.
attribute.iss	assertion.iss	Issuer of the token.

Providers

Name	Version
google	>= 5.0.0

Inputs

Name	Description	Type	Default	Required
allowed_audiences	Workload Identity Pool Provider allowed audiences	list(string)	n/a	yes
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": "assertion.aud", "attribute.iss": "assertion.iss", "attribute.sub": "assertion.sub", "google.subject": "assertion.sub" }	no
issuer_uri	Workload Identity Pool Provider issuer URI	string	n/a	yes
jwks_json	(Optional) OIDC JSON Web Key (JWK) in JSON String format. If not set, then the key is fetched from the .well-known path for the issuer_uri	string	null	no
jwks_json_file	(Optional) OIDC JSON Web Key (JWK) file. If not set, then we use the jwks_json is used	string	null	no
pool_description	Workload Identity Pool description	string	"Workload Identity Pool for Jenkins (Terraform managed)"	no
pool_disabled	Workload Identity Pool disabled	bool	false	no
pool_display_name	Workload Identity Pool display name	string	"Jenkins"	no
pool_id	Workload Identity Pool ID	string	"jenkins"	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 Jenkins (Terraform managed)"	no
provider_disabled	Workload Identity Pool Provider disabled	bool	false	no
provider_display_name	Workload Identity Pool Provider display name	string	"Jenkins OIDC"	no
provider_id	Workload Identity Pool Provider ID	string	"jenkins-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.