Skip to content
Terrateam

OIDC Setup

What is OIDC?

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

The fastest way to get OIDC working is with our automated tools. Choose your preferred method:

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

  1. Create main.tf on your workstation

    module "terraform_aws_terrateam_setup" {
      source               = "github.com/terrateamio/terraform-aws-terrateam-setup"
      github_org           = "GITHUB_ORG" # GitHub organization or username
      aws_policy_arn       = "arn:aws:iam::aws:policy/PowerUserAccess"  # Suggested policy - customize as needed
      aws_iam_role_name    = "terrateam"
      create_oidc_provider = true
    }

  2. Apply changes locally

    Terminal window
    terraform apply

Configure Terrateam for OIDC

After setting up AWS 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: aws
            role_arn: "arn:aws:iam::AWS_ACCOUNT_ID:role/terrateam"

Manual Setup (Advanced)

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

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

  1. Create OIDC Provider

    Create the OIDC provider in AWS to trust GitHub’s identity provider:

    Terminal window
    aws iam create-open-id-connect-provider \
    --url https://token.actions.githubusercontent.com \
    --client-id-list sts.amazonaws.com \
    --thumbprint-list 6938fd4d98bab03faadb97b34396831e3780aea1 1c58a3a8518e8759bf075b76b750d4f2df264fcd

  2. Create Trust Policy

    Create a local file on your workstation named trustpolicy.json. This defines the policy allowing AWS to trust GitHub’s OIDC as a federated identity.

    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Effect": "Allow",
          "Principal": {
            "Federated": "arn:aws:iam::AWS_ACCOUNT_ID:oidc-provider/token.actions.githubusercontent.com"
          },
          "Action": "sts:AssumeRoleWithWebIdentity",
          "Condition": {
            "StringLike": {
              "token.actions.githubusercontent.com:sub": "repo:GITHUB_ORG/*"
            },
            "StringEquals": {
              "token.actions.githubusercontent.com:aud": "sts.amazonaws.com"
            }
          }
        }
      ]
    }

    Example Trust Policies:

  3. Create IAM Role

    Create the terrateam IAM role using the trust policy:

    Terminal window
    aws iam create-role \
    --role-name terrateam \
    --assume-role-policy-document file://trustpolicy.json

  4. Attach Permissions Policy

    Attach an IAM policy to give the role necessary permissions. We suggest PowerUserAccess as a starting point:

    Terminal window
    aws iam attach-role-policy \
    --policy-arn arn:aws:iam::aws:policy/PowerUserAccess \
    --role-name terrateam

  5. Configure Terrateam

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

Advanced Configuration

Next Steps

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