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

Choose your preferred method for setting up OIDC authentication:

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

    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

    Terminal window
    terraform apply

  3. 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

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

  1. Create Configuration File

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

  2. 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

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

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

    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

    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

    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

    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

    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

    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

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

Advanced Configuration

Next Steps

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