Google Cloud Workload Identity Module#

This module provides a standardized and reusable way to manage Workload Identity Federation in Google Cloud Platform. It simplifies the process of creating and configuring Workload Identity Pools and Providers, allowing external identities (such as those from Azure Kubernetes Service or AWS) to impersonate Google Cloud service accounts. This is essential for securely authenticating workloads running outside of GCP without needing to manage service account keys.

Features#

Generic and Reusable: This module can be used for various identity providers, including OIDC (e.g., Azure AKS, GitHub Actions) and AWS.
Simplified Configuration: Abstracts the complexity of setting up Workload Identity Federation, requiring only a few input variables to get started.
Secure by Design: Follows best practices for IAM and Workload Identity Federation, ensuring that external identities are granted the principle of least privilege.
Automated IAM Bindings: Automatically grants the roles/iam.workloadIdentityUser role to the specified service accounts, allowing them to be impersonated by the external identities.
Flexible JWKS Handling: Supports multiple ways to provide JWKS (JSON Web Key Set) for OIDC providers, including public endpoints, inline JSON, or secure storage in Secret Manager.
Configurable Subject Mapping: Allows precise control over which external identities can access your GCP resources by specifying exact subject mappings.

Compatibility#

This module is compatible with Terraform version ~> 1 and the Google Provider version >= 6.28.0, < 7.0.0.

Usage#

Basic Example with Public JWKS#

Here is an example of how to use this module to configure Workload Identity Federation for an OIDC provider with a public JWKS endpoint:

module "workload_identity" {
  source = "./modules/terraform-google-workload-identity"

  project_id            = "your-gcp-project-id"
  pool_id               = "your-pool-id"
  pool_display_name     = "My Workload Identity Pool"
  provider_id           = "your-provider-id"
  provider_display_name = "My OIDC Provider"

  jwks_source_type      = "public"  # Use the public JWKS endpoint

  oidc_provider = {
    issuer_uri = "https://oidc.eks.us-east-1.amazonaws.com/id/EXAMPLED539D4633E53BF8DE7"
  }

  attribute_mapping = {
    "google.subject" = "assertion.sub",
    "attribute.actor" = "assertion.actor",
    "attribute.aud"   = "assertion.aud",
  }

  service_accounts = [
    "projects/your-gcp-project-id/serviceAccounts/your-service-account@your-gcp-project-id.iam.gserviceaccount.com",
  ]
}

Example with JWKS from Secret Manager#

This example shows how to configure Workload Identity Federation using a JWKS stored in Secret Manager:

module "workload_identity" {
  source = "./modules/terraform-google-workload-identity"

  project_id            = "your-gcp-project-id"
  pool_id               = "your-pool-id"
  pool_display_name     = "My Workload Identity Pool"
  provider_id           = "your-provider-id"
  provider_display_name = "My OIDC Provider"

  jwks_source_type      = "secret"
  jwks_secret_id        = "my-jwks-secret"
  jwks_secret_project_id = "secrets-project-id"  # Optional, defaults to provider project_id

  oidc_provider = {
    issuer_uri = "https://oidc.azure.com/tenant-id/"
  }

  attribute_mapping = {
    "google.subject" = "assertion.sub",
  }

  service_accounts = [
    "projects/your-gcp-project-id/serviceAccounts/your-service-account@your-gcp-project-id.iam.gserviceaccount.com",
  ]
}

Example with Specific Subject Mapping for Kubernetes Service Account#

This example shows how to configure specific subject mapping for a Kubernetes Service Account:

module "workload_identity" {
  source = "./modules/terraform-google-workload-identity"

  project_id            = "your-gcp-project-id"
  pool_id               = "k8s-pool"
  pool_display_name     = "Kubernetes Workload Identity Pool"
  provider_id           = "aks-provider"
  provider_display_name = "AKS Provider"

  jwks_source_type      = "public"

  oidc_provider = {
    issuer_uri = "https://oidc.azure.com/tenant-id/"
  }

  attribute_mapping = {
    "google.subject" = "assertion.sub",
  }

  # Use specific subject mapping for a Kubernetes service account
  subject_mapping = "system:serviceaccount:apigee:apigee-runtime"

  service_accounts = [
    "projects/your-gcp-project-id/serviceAccounts/apigee-runtime@your-gcp-project-id.iam.gserviceaccount.com",
  ]
}

Software#

This module requires the following software: - Terraform ~> 1.0 - gcloud CLI (for authentication)

Service Account#

The service account used to run this module requires the following IAM roles: - roles/iam.workloadIdentityPoolAdmin on the project. - roles/iam.serviceAccountAdmin on the project (or on the specific service accounts). - roles/secretmanager.viewer if using secrets from Secret Manager.

APIs#

The following APIs must be enabled in the target project: - iam.googleapis.com - secretmanager.googleapis.com

Limitations#

This module currently supports Workload Identity Federation for OIDC and AWS providers only. It does not support the following configurations:

SAML: Security Assertion Markup Language (SAML) 2.0-based federation is not implemented.
X.509: Certificate-based authentication using X.509 is not supported.

License#

This module is covered by a commercial license. Please see LICENSE for details.

Support#

This module is developed and maintained by MyOps Limited. For any support inquiries, please contact us at info@myops.co.il.

Requirements#

Name	Version
terraform	~> 1
google	>= 6.28.0, < 7.0.0
google-beta	>= 6.28.0, < 7.0.0

Providers#

Name	Version
google	>= 6.28.0, < 7.0.0

Modules#

No modules.

Resources#

Name	Type
google_iam_workload_identity_pool.pool	resource
google_iam_workload_identity_pool_provider.provider	resource
google_service_account_iam_member.workload_identity_user	resource
google_project.project	data source
google_secret_manager_secret.jwks_secret	data source
google_secret_manager_secret_version.basic	data source

Inputs#

Name	Description	Type	Default	Required
attribute_condition	The condition to use for workload identity federation.	`string`	`null`	no
attribute_mapping	A mapping of attributes from the external identity provider to Google Cloud.	`map(string)`	`{}`	no
aws_provider	AWS provider configuration.	object({ account_id = string })	`null`	no
jwks_json	The JSON representation of the JWKS.	`string`	`""`	no
jwks_secret_id	The ID of the Secret Manager secret containing the JWKS.	`string`	`""`	no
jwks_secret_project_id	The ID of the project containing the Secret Manager secret.	`string`	`""`	no
jwks_source_type	The source type for the JWKS (JSON Web Key Set).	`string`	`"secret"`	no
oidc_provider	OIDC provider configuration.	object({ issuer_uri = string jwks_json = optional(string, null) })	`null`	no
pool_description	A description of the Workload Identity Pool.	`string`	`null`	no
pool_disabled	Whether the Workload Identity Pool is disabled.	`bool`	`false`	no
pool_display_name	The display name of the Workload Identity Pool.	`string`	n/a	yes
pool_id	The ID of the Workload Identity Pool.	`string`	n/a	yes
project_id	The ID of the project in which to create the Workload Identity Pool.	`string`	n/a	yes
provider_description	A description of the Workload Identity Pool Provider.	`string`	`null`	no
provider_disabled	Whether the Workload Identity Pool Provider is disabled.	`bool`	`false`	no
provider_display_name	The display name of the Workload Identity Pool Provider.	`string`	n/a	yes
provider_id	The ID of the Workload Identity Pool Provider.	`string`	n/a	yes
service_accounts	A list of service account emails to grant Workload Identity User role.	`list(string)`	`[]`	no
subject_mapping	The specific subject to use for workload identity federation. If not provided, uses a wildcard (*) mapping.	`string`	`null`	no

Outputs#

Name	Description
workload_identity_pool_name	The name of the Workload Identity Pool.
workload_identity_pool_provider_name	The name of the Workload Identity Pool Provider.