AWS Authentication and Authorization

Terrateam needs permission to access resources in your AWS account.

Credentials can be configured using one of the following methods:

OIDC
Static Credentials

Credentials are never stored on our servers.

Setup Instructions

OIDC

OpenID Connect (OIDC) allows the Terrateam GitHub Actions workflow to access resources in your AWS account using short-lived temporary credentials.

Terrateam leverages GitHub's OIDC Identity Provider to issue a secure token.

Prerequisites

These instructions require you to run commands from a terminal.

AWS CLI (opens in a new tab)

Connect the GitHub OpenID Connect Identity Provider

The OpenID Connect Identity Provider is used to allow the Terrateam GitHub Actions workflow to access resources in AWS.

Create the OIDC provider in AWS

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

What's thumbprint-list?

The thumbprint is a signature for the CA's certificate that was used to issue the certificate for the OIDC Identity Provider. When you create an IAM OIDC Identity Provider in AWS, you are trusting identities authenticated by that Identity Provider, in this case GitHub, to have access to your AWS account. See the official AWS documentation (opens in a new tab) for details.

The GitHub thumbprint is 6938fd4d98bab03faadb97b34396831e3780aea1 which can be verified with a simple script (opens in a new tab).

Create a local file on your workstation named trustpolicy.json. This file will define the policy to be used to allow AWS to trust GitHub's OIDC as a federated identity. You must update the example file below with your own values.

Example trustpolicy.json. Make sure to replace AWS_ACCOUNT_ID and GITHUB_ORG with your own values.

{
  "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"
        }
      }
    }
  ]
}

`AWS_ACCOUNT_ID`

Replace AWS_ACCOUNT_ID with your AWS Account ID that you want to authenticate against. This can be found using the following command:

aws sts get-caller-identity

`GITHUB_ORG`

Replace GITHUB_ORG with your GitHub Organization you want to grant access to against your AWS account.

Don't want to grant access to your entire GitHub organization? Expand for more examples

Example trustpolicy.json (opens in a new tab) that grants access to a single repository
Example trustpolicy.json (opens in a new tab) that grants access to multiple repositories

Create a terrateam IAM role using the newly created trustpolicy.json

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

Attach the PowerUserAccess IAM policy

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

PowerUserAccess is an AWS managed IAM policy.

This policy provides full access to AWS services and resources, but does not allow management of users and groups.

This IAM policy is merely a suggestion. Choose whichever IAM policy makes the most sense for your organization.

Configure Terrateam for OIDC

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

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.

##########################################################################
# .terrateam/config.yml
##########################################################################
hooks:
  all:
    pre:
      - type: oidc
        provider: aws
        role_arn: "arn:aws:iam::AWS_ACCOUNT_ID:role/terrateam"

Replace AWS_ACCOUNT_ID with your AWS Account ID. This can be found using the following command:

aws sts get-caller-identity

Advanced configuration? Use separate IAM roles against multiple environments with additional configuration. See OIDC documentation for details.

AWS Terraform Provider

The AWS Terraform provider (opens in a new tab) will detect and use the temporary credentials created using the GitHub OIDC Identity Provider. These credentials are short-lived and set with the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables in the Terrateam GitHub Action runtime environment.

Getting Started: Next Steps

How It Works Azure