Skip to content

OIDC

OIDC can be used to safely and securely authenticate to your cloud provider using temporary credentials.

To use OIDC, you will first need to configure your cloud provider to trust the GitHub OIDC as a federated identity. Terrateam can then be configured to authenticate to your cloud provider using OIDC.

See Cloud Provider Setup documentation to learn how to connect the GitHub OpenID Connect Identity Provider to your cloud provider.

Configuration

Terrateam Configuration Terrateam behavior can be configured via a config.yml. This file is located in a directory named .terrateam at the root of your Terraform repository: .terrateam/config.yml.

See Configuration documentation for details.

OIDC can be configured using Hooks or Workflows depending on the complexity of your requirements. OIDC configuration blocks are identical in both top-level keys.

KeyTypeDescription
oidcListInitiate an OIDC connection to a cloud provider.
providerStringName of provider: aws.
role_arnStringSpecifies the ARN of an IAM role that you want to use. Value can be specified using a GitHub Secret / environment variable with ${ENV_VAR}.
assume_role_arnStringSpecifies the ARN of an IAM role that you want to assume into. Value can be specified using a GitHub Secret / environment variable with ${ENV_VAR}. Default is the value of role_arn.
assume_role_enabledBooleanRetrieve a set of temporary security credentials from AWS and set the AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_SESSION_TOKEN environment variables. Default is true.
audienceStringSpecifies the AWS audience name to use. Value can be specified using a GitHub Secret / environment variable with ${ENV_VAR}. Default is sts.amazonaws.com.
regionStringSpecifies the AWS region to use and sets the AWS_REGION environment variable. Default is us-east-1.
session_nameStringSpecifies the AWS session name. Default is terrateam.
durationIntegerSpecifies the AWS session duration in seconds. Default is 3600.

Example configuration using all keys:

      - type: oidc
        provider: aws
        role_arn: "arn:aws:iam::123456789012:role/terrateam"
        assume_role_arn: "arn:aws:iam::987654321012:role/terrateam"
        assume_role_enabled: true
        audience: "sts.amazonaws.com"
        region: "us-east-1"
        session_name: "terrateam"
        duration: 3600

Single IAM role

Authenticates using a single IAM role for all Terrateam operations:

hooks:
  all:
    pre:
      - type: oidc
        provider: aws
        role_arn: "arn:aws:iam::123456789012:role/terrateam"

Separate IAM role per environment

It’s possible to use separate IAM roles per environment. In the example Terraform repository layout below, environments are split out by directory:

josh@elmer:~ $ tree terraform/
terraform/
├── production
│   └── app
│       └── frontend
│           └── main.tf
└── staging
    └── app
        └── frontend
            └── main.tf

6 directories, 2 files
josh@elmer:~ $

To use a separate IAM role for the production and staging directories/environments, the .terrateam/config.yml can be configured with the following:

workflows:
  - tag_query: dir:staging
    plan:
      - type: oidc
        provider: aws
        role_arn: "arn:aws:iam::123456789012:role/terrateam-staging-role"
      - type: init
      - type: plan
    apply:
      - type: oidc
        provider: aws
        role_arn: "arn:aws:iam::123456789012:role/terrateam-staging-role"
      - type: init
      - type: apply
  - tag_query: dir:production
    plan:
      - type: oidc
        provider: aws
        role_arn: "arn:aws:iam::123456789012:role/terrateam-production-role"
      - type: init
      - type: plan
    apply:
      - type: oidc
        provider: aws
        role_arn: "arn:aws:iam::123456789012:role/terrateam-production-role"
      - type: init
      - type: apply

Separate IAM roles per environment and operation

Building off of the previous example, one could use separate IAM roles for Plan and Apply operations.

workflows:
  - tag_query: dir:staging
    plan:
      - type: oidc
        provider: aws
        role_arn: "arn:aws:iam::123456789012:role/terrateam-staging-plan-role"
      - type: init
      - type: plan
    apply:
      - type: oidc
        provider: aws
        role_arn: "arn:aws:iam::123456789012:role/terrateam-staging-apply-role"
      - type: init
      - type: apply
  - tag_query: dir:production
    plan:
      - type: oidc
        provider: aws
        role_arn: "arn:aws:iam::123456789012:role/terrateam-production-plan-role"
      - type: init
      - type: plan
    apply:
      - type: oidc
        provider: aws
        role_arn: "arn:aws:iam::123456789012:role/terrateam-production-apply-role"
      - type: init
      - type: apply

Assuming into another role

Sometimes it’s desired to assume into another role before performing an operation. This can be achieved with the assume_role_arn configuration.

Terrateam will retreive a web identity token from AWS using the ARN defined in role_arn and then perform an aws sts assume-role using the specified ARN in assume_role_arn which will return temporary credentials for the assume role arn. The AWS Terraform provider will use the newly created temporary credentials.

workflows:
  - tag_query: ""
    plan:
      - type: oidc
        provider: aws
        role_arn: "arn:aws:iam::999999999999:role/terrateam-aws-management-account"
        assume_role_arn: "arn:aws:iam::123456789012:role/terrateam-operations"
      - type: init
      - type: plan