Skip to content

GCP Authentication and Authorization

Overview

Terrateam needs permission to access resources in your GCP account.

Credentials can be configured using one of the following methods:

  • OIDC
  • Static Credentials

Setup Instructions

OIDC

OpenID Connect (OIDC) allows the Terrateam GitHub Actions workflow to access resources in your GCP account using short-lived temporary credentials.

Prerequisites

These instructions require you to run commands from a terminal.

Create a Terrateam service account

A dedicated service account is used to access GCP resources.

  1. Get your Project ID
gcloud projects list
  1. Export your Project ID
export PROJECT_ID="<project-id>"
  1. Create a terrateam service account
gcloud iam service-accounts create terrateam \
--description="Terrateam" \
--display-name="Terrateam" \
--project="$PROJECT_ID"

Create the workload idenity pool

A workload identity pool lets you access GCP resources from GitHub.

  1. Enable the IAM Credentials API
gcloud services enable iamcredentials.googleapis.com \
  --project "${PROJECT_ID}"
  1. Create the workload identity pool
gcloud iam workload-identity-pools create "terrateam-pool" \
  --project="${PROJECT_ID}" \
  --location="global" \
  --display-name="Terrateam pool"
  1. Export the workload identity pool id as an environment variable
export WORKLOAD_IDENTITY_POOL_ID=$(gcloud iam workload-identity-pools describe "terrateam-pool" \
  --project="${PROJECT_ID}" \
  --location="global" \
  --format="value(name)")

Create the OIDC provider

An OIDC workload identity pool provider for GitHub is necessary to authenticate from GitHub.

gcloud iam workload-identity-pools providers create-oidc "terrateam-provider" \
  --project="${PROJECT_ID}" \
  --location="global" \
  --workload-identity-pool="terrateam-pool" \
  --display-name="Terrateam provider" \
  --attribute-mapping="google.subject=assertion.sub,attribute.actor=assertion.actor,attribute.repository=assertion.repository,attribute.repository_owner=assertion.repository_owner" \
  --issuer-uri="https://token.actions.githubusercontent.com"

Create IAM policy bindings

An IAM policy binding binds the Terrateam service account to a role in your GCP project and GitHub repository.

  1. Export your GitHub organization as an environment variable
export GITHUB_ORG="organization"
  1. Authorize your GitHub organization
gcloud iam service-accounts add-iam-policy-binding "terrateam@${PROJECT_ID}.iam.gserviceaccount.com" \
	--project="${PROJECT_ID}" \
	--role="roles/iam.workloadIdentityUser" \
	--member="principalSet://iam.googleapis.com/${WORKLOAD_IDENTITY_POOL_ID}/attribute.repository_owner/${GITHUB_ORG}"
Don’t want to grant access to your entire GitHub organization? Expand me

Single repository access:

gcloud iam service-accounts add-iam-policy-binding "terrateam@${PROJECT_ID}.iam.gserviceaccount.com" \
  --project="${PROJECT_ID}" \
  --role="roles/iam.workloadIdentityUser" \
  --member="principalSet://iam.googleapis.com/${WORKLOAD_IDENTITY_POOL_ID}/attribute.repository/${GITHUB_ORG}/repository-one"
  1. Add the roles/editor IAM policy binding
gcloud projects add-iam-policy-binding ${PROJECT_ID} \
--member="serviceAccount:terrateam@${PROJECT_ID}.iam.gserviceaccount.com" \
--role='roles/editor'

Configure Terrateam for OIDC

Create a .terrateam/config.yml configuration file at the root of your Terraform repository:

Terrateam Configuration Terrateam behavior can be configured via a config.yml. This file is located in a directory named .terrateam at the root of your Terraform repository: .terrateam/config.yml.

See Configuration documentation for details.

Configure Terrateam to use GCP OIDC

##########################################################################
# .terrateam/config.yml
##########################################################################
hooks:
  all:
    pre:
      - type: oidc
        provider: gcp
        service_account: "terrateam@PROJECT_ID.iam.gserviceaccount.com"
        workload_identity_provider: "WORKLOAD_IDENTITY_PROVIDER"
  1. Replace PROJECT_ID with your GCP project id. This can be found using the following command:
echo $PROJECT_ID
  1. Replace WORKLOAD_IDENTITY_PROVIDER with your GCP workload identity provider. This can be found using the following command:
gcloud iam workload-identity-pools providers describe "terrateam-provider" \
  --project="${PROJECT_ID}" \
  --location="global" \
  --workload-identity-pool="terrateam-pool" \
  --format="value(name)"

GCP Terraform Provider

The GCP Terraform provider will detect and use the temporary credentials created using the GitHub OIDC Identity Provider. These credentials are short-lived and set with the GOOGLE_OAUTH_ACCESS_TOKEN environment variable in the Terrateam GitHub Action runtime environment.

Back to Getting Started