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”

Scoping Credentials by Environment

Section titled “Scoping Credentials by Environment”

The example above names a service account per workflow. The service account and workload identity provider come from your Terrateam configuration, so Google cannot tell which environment a run belongs to. Any run matching the workflow can request any credentials the configuration names.

Associating a workflow with a GitHub Environment closes that gap. GitHub signs the environment into the token it issues, so Google validates the environment instead of trusting your configuration.

This follows Google’s guidance to use attribute conditions when federating with GitHub and to grant roles to identities matching specific criteria rather than to every member of a pool. Google recommends a single pool and provider for GitHub, with attributes separating access. See Configure Workload Identity Federation with deployment pipelines.

  1. Set the environment on the workflow

    Section titled “Set the environment on the workflow”
    workflows:
      - tag_query: "dir:terraform/production/**"
        environment: production
        plan:
          - type: oidc
            provider: gcp
            service_account: "terrateam-prod@PROJECT_ID.iam.gserviceaccount.com"
            workload_identity_provider: "projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/terrateam-pool/providers/terrateam-provider"
          - type: init
          - type: plan

    Terrateam runs each environment as its own job, and that job runs in the GitHub Environment you name. Create the environment in your repository settings before the first run.

  2. Map the environment claim

    Section titled “Map the environment claim”

    Add attribute.environment to the provider you created during setup:

    Terminal window
    gcloud iam workload-identity-pools providers update-oidc "terrateam-provider" \
      --project="PROJECT_ID" \
      --location="global" \
      --workload-identity-pool="terrateam-pool" \
      --attribute-mapping="google.subject=assertion.sub,attribute.actor=assertion.actor,attribute.repository=assertion.repository,attribute.repository_owner=assertion.repository_owner,attribute.environment=assertion.environment" \
      --attribute-condition="assertion.repository_owner == 'GITHUB_ORG'"

    A job running in an environment also changes the subject claim to repo:GITHUB_ORG/REPO:environment:production. Review any binding that matches on google.subject before you roll this out.

  3. Bind each service account to its environment

    Section titled “Bind each service account to its environment”

    Replace the attribute.repository_owner binding from the setup steps with one binding per environment:

    Terminal window
    gcloud iam service-accounts add-iam-policy-binding "terrateam-prod@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.environment/production"

    A run in the staging environment receives a token carrying "environment": "staging", which does not satisfy this binding. Google refuses the impersonation.

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.