Skip to content

AWS Authentication and Authorization

Overview

Terrateam needs permission to access resources in your AWS account.

Credentials can be configured using one of the following methods:

  • OIDC
  • Static Credentials

Setup Instructions

OIDC

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

Prerequisites

These instructions require you to run commands from a terminal.

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.

  1. 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 \
1c58a3a8518e8759bf075b76b750d4f2df264fcd
  1. 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
  1. 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
  1. Attach the PowerUserAccess IAM policy
aws iam attach-role-policy \
--policy-arn arn:aws:iam::aws:policy/PowerUserAccess \
--role-name terrateam

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

AWS Terraform Provider

The AWS Terraform provider 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.

Back to Getting Started