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.

Credentials are never stored on our servers.

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.

Key	Type	Description
oidc	List	Initiate an OIDC connection to a cloud provider.
provider	String	Name of provider: `aws`.
role_arn	String	Specifies the ARN of an IAM role that you want to use.
assume_role_arn	String	Specifies the ARN of an IAM role that you want to assume into. Default is the value of `role_arn`.
assume_role_enabled	Boolean	Retrieve 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`.
audience	String	Specifies the AWS audience name to use. Default is `sts.amazonaws.com`.
region	String	Specifies the AWS region to use and sets the `AWS_REGION` environment variable. Default is `us-east-1`.
session_name	String	Specifies the AWS session name. Default is `terrateam`.
duration	Integer	Specifies the AWS session duration in seconds. Default is `3600`.

Example configuration using all keys:

This is a partial configuration. The oidc block must be configured under top-level keys hooks or workflows. See below for detailed examples.

      - 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-with-web-identity 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

Hooks Policy Testing