circleci-gcp-oidc-terraform

Terraform plan to deploy GCP infra necessary for authenticating with GCP using CircleCI OIDC tokens. Creates a workload identity pool, a workload identity pool provider, a service account to impersonate, and binds necessary permissions to the new service account.

Requirements

• Terraform (>= 1.0.9)

How to Use

module "gcp_oidc_provider_with_circleci_bindings" {
  #source = "git@github.com:jtreutel/circleci-gcp-oidc-terraform.git?ref=<DESIRED_TAG_HERE>"

  circleci_org_id = "xxxxxx-xxx-xxx-xxx-xxxxxx" #source: https://app.circleci.com/settings/organization/github/YOUR_CIRCLECI_ORG/overview
  resource_prefix = "your-awesome-prefix"
  roles_to_bind = ["roles/foobar"]
}

1. Retrieve your organization ID by logging in to CircleCI and navigating to "Organization Settings".
2. Rename terraform.tfvars.example to terraform.tfvars and replace required values
3. (Optional) In terraform.tfvars, change the resource prefix and any other optional variables to desired values (see below for an explanation of the variables)
4. (Optional, but strongly recommended) Add a remote state backend to store your terraform state
5. Run terraform plan and inspect proposed changes
6. Run terraform apply to apply changes

Optional: If you would like to do a sandbox deploy to test the Terraform plan using CircleCI, follow these steps:

1. Enter the necessary values in terraform.tfvars.example and save your changes
2. Run the following bash command: cat terraform.tfvars | base64
3. Store the output in a CircleCI context or project-level variable named BASE64_TFVARS.

Granular Access Control

Access to service accounts can be restricted at the workload identity pool provider level and at the service account binding level.

Restricting at the WIP Provider Level

Restrict access at the workload identity pool provider level by writing a CEL expression to describe which CircleCI OIDC tokens are allowed to impersonate the service accounts. You can then set the expression as the value of variable wip_provider_attribute_condition. Here are a few examples:

Restrict access to a specific org and user:

attribute.org_id=='01234567-89ab-cdef-0123-4567890abcde' && 
google.subject.matches('org/([\da-f]{4,12}-?){5}/project/([\da-f]{4,12}-?){5}/user/76543210-ba98-fedc-3210-edcba0987654')

Restrict access to and org and its users with permission access a specific context:

attribute.org_id=='01234567-89ab-cdef-0123-4567890abcde' && 
attribute.context_id=='76543210-ba98-fedc-3210-edcba0987654' 

Restrict access and org and its users with access to a specific project :

attribute.org_id=='01234567-89ab-cdef-0123-4567890abcde' && 
attribute.project_id=='76543210-ba98-fedc-3210-edcba0987654' 

Restricting at the Service Account Level

If you choose to automatically create a new service account, you can add a single condition to restrict impersonation of this service account. Configure the variables sa_impersonation_filter_attribute and sa_impersonation_filter_value with the provider attribute and desired value, respectively. For example:

sa_impersonation_filter_attribute = "attribute.project_id" sa_impersonation_filter_value = "01234567-89ab-cdef-0123-4567890abcde"

CI/CD Terraform Module Testing

The pipeline config in this project will perform a sandbox deploy/destroy to validate the module. The prerequsite configuration is as follows:

GCP

• A GCP project
• A service account in that project with a valid key

CircleCI

The following variables should be configured in a context or at the project level:

Name	Value	Description
BASE64_SA_KEY	(base-64 string)	Base-64 encoded GCP service account key.
BASE64_TFVARS	(base-64 string)	Base-64 encoded contents of terraform.tfvars for your sandbox deployment target.
GOOGLE_APPLICATION_CREDENTIALS	key.json	Path to the SA key file.
GOOGLE_DNS_ZONE_NAME	(varies)	For Terraform GCP auth.
GOOGLE_PROJECT	(varies)	For Terraform GCP auth.
GOOGLE_REGION	(varies)	For Terraform GCP auth.
GOOGLE_ZONE	(varies)	For Terraform GCP auth.

Terraform Module Details

Resources Created by Terraform

• google_iam_workload_identity_pool.circleci
• google_iam_workload_identity_pool_provider.circleci
• google_project_iam_member.project[]
• google_service_account.circleci[0]
• google_service_account_iam_member.circleci_impersonation

Generated by tf-docs.

Requirements

No requirements.

Providers

Name	Version
google	n/a

Modules

No modules.

Resources

Name	Type
google_iam_workload_identity_pool.circleci	resource
google_iam_workload_identity_pool_provider.circleci	resource
google_service_account.circleci	resource
google_service_account_iam_binding.circleci	resource
google_service_account_iam_binding.circleci_sa_user	resource
google_project.project	data source
google_service_account.circleci_access	data source

Inputs

Name	Description	Type	Default	Required
circleci_org_id	Your CircleCI org ID. Can be found under "Organization Settings" in the CircleCI application.	string	n/a	yes
custom_attribute_mappings	List of custom attribute mappings. See https://cloud.google.com/iam/docs/workload-identity-federation#mapping and https://circleci.com/docs2/2.0/openid-connect-tokens#format-of-the-openid-connect-id-token.	map(string)	{}	no
existing_service_account_email	Enter the email of the GCP SA that CircleCI should impersonate. Leave blank to create a new service account.	string	""	no
resource_prefix	A prefix that will be added to all resources created by this Terraform plan.	string	"CircleCI"	no
roles_to_bind	A set of IAM roles to bind to the service account. e.g. roles/iam.serviceAccountAdmin	set(string)	n/a	yes
sa_impersonation_filter_attribute	A GCP workload identity pool provider attribute to use for restricting role impersonation to specific CircleCI orgs, projects, or contexts. Defaults to CircleCI org ID.	string	""	no
sa_impersonation_filter_value	A GCP workload identity pool provider attribute value to use for restricting role impersonation to specific CircleCI orgs, projects, or contexts. Defaults to CircleCI org ID.	string	""	no
wip_provider_attribute_condition	CEL expression describing which principles are allowed to impersonate service accounts. Defaults to anyone from your CircleCI org.	string	""	no

Outputs

Name	Description
GOOGLE_PROJECT_ID	Google project ID.
GOOGLE_PROJECT_NUMBER	Google project number.
OIDC_SERVICE_ACCOUNT_EMAIL	OIDC service account ID.
OIDC_WIP_ID	GCP IAM workload identity pool ID.
OIDC_WIP_PROVIDER_ID	GCP IAM workload identity pool provider ID.