Skip to content
Terrateam

OIDC Setup

What is OIDC?

OpenID Connect (OIDC) allows your GitHub Actions workflows to access GCP resources without storing any credentials as long-lived GitHub secrets. GCP implements this through Workload Identity. This is the most secure authentication method for production environments.

Setup Methods

Section titled “Setup Methods”

Choose your preferred method for setting up OIDC authentication:

Automated Setup

Section titled “Automated Setup”

Use our Terraform module to automatically create all required GCP resources:

Use our Terraform module to create all GCP resources that Terrateam requires.

  1. Create main.tf on your workstation

    Section titled “Create main.tf on your workstation”
    module "terraform_gcp_terrateam_setup" {
      source                        = "github.com/terrateamio/terraform-gcp-terrateam-setup"
      github_org                    = "GITHUB_ORG" # GitHub organization or username
      project_id                    = "PROJECT_ID"
      service_account_description   = "Terrateam service account"
      workload_identity_pool_id     = "terrateam-pool"
      workload_identity_provider    = "terrateam-provider"
      service_account_name          = "terrateam"
      service_account_role          = "roles/editor"
    }
    

    output "google_iam_workload_identity_pool_provider_github_provider_name" {
      value = module.terraform_gcp_terrateam_setup
    }

  2. Apply changes locally

    Section titled “Apply changes locally”
    Terminal window
    terraform apply

  3. Note the output

    Section titled “Note the output”

    Save the output value google_iam_workload_identity_pool_provider_github_provider_name - you’ll need it for Terrateam configuration.

Configure Terrateam for OIDC

Section titled “Configure Terrateam for OIDC”

After setting up GCP resources, configure Terrateam to use OIDC authentication:

  1. Create Configuration File

    Section titled “Create Configuration File”

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

  2. Add OIDC Hook

    Section titled “Add OIDC Hook”
    hooks:
      all:
        pre:
          - type: oidc
            provider: gcp
            service_account: "terrateam@PROJECT_ID.iam.gserviceaccount.com"
            workload_identity_provider: "WORKLOAD_IDENTITY_PROVIDER"

Testing Your Setup

Section titled “Testing Your Setup”

Test that OIDC authentication is working:

  1. Create a simple Terraform configuration in your repository
  2. Open a pull request with the changes
  3. Comment terrateam plan on the pull request
  4. Terrateam should successfully authenticate using OIDC and show the plan output

Manual Setup

Section titled “Manual Setup”

For custom configurations or when you need to understand exactly what resources are being created:

Need to set up OIDC manually? Expand for step-by-step instructions

  1. Create Service Account

    Section titled “Create Service Account”

    Create a Terrateam service account:

    Terminal window
    gcloud iam service-accounts create terrateam \
    --description="Terrateam service account" \
    --display-name="Terrateam" \
    --project="PROJECT_ID"

  2. Create Workload Identity Pool

    Section titled “Create Workload Identity Pool”

    Create the workload identity pool:

    Terminal window
    gcloud iam workload-identity-pools create "terrateam-pool" \
      --project="PROJECT_ID" \
      --location="global" \
      --display-name="Terrateam pool"

  3. Create OIDC Provider

    Section titled “Create OIDC Provider”

    Create the OIDC provider in the workload identity pool:

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

  4. Create IAM Policy Bindings

    Section titled “Create IAM Policy Bindings”

    Allow the workload identity pool to impersonate the service account:

    Terminal window
    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/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/terrateam-pool/attribute.repository_owner/GITHUB_ORG"

  5. Attach IAM Role

    Section titled “Attach IAM Role”

    Attach an IAM role to give the service account necessary permissions. We suggest roles/editor as a starting point:

    Terminal window
    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:terrateam@PROJECT_ID.iam.gserviceaccount.com" \
    --role='roles/editor'

  6. Get Workload Identity Provider Name

    Section titled “Get Workload Identity Provider Name”

    Get the full workload identity provider name for Terrateam configuration:

    Terminal window
    gcloud iam workload-identity-pools providers describe "terrateam-provider" \
      --project="PROJECT_ID" \
      --location="global" \
      --workload-identity-pool="terrateam-pool" \
      --format="value(name)"

  7. Configure Terrateam

    Section titled “Configure Terrateam”

    Follow the Configure Terrateam for OIDC section above to complete your setup.

Advanced Configuration

Section titled “Advanced Configuration”

Next Steps

Section titled “Next Steps”

Now that you have GCP authentication configured, you are now able to use Terrateam for plan and apply operations against GCP resources.