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.

Section titled “Quick Setup (Recommended)”

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

    Section titled “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

    Section titled “Apply changes locally”
    Terminal window
    terraform apply

Configure Terrateam for OIDC

Section titled “Configure Terrateam for OIDC”

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

Manual Setup (Advanced)

Section titled “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

    Section titled “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

    Section titled “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

    Section titled “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

    Section titled “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

    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 AWS authentication configured, you are now able to use Terrateam for plan and apply operations against AWS resources.