Skip to main content

AWS OIDC

Follow these steps to authenticate against AWS

1. Configure AWS to allow GitHub Actions to communicate using OpenID Connect

Details
  1. Sign in to the AWS Management Console and navigate to the IAM console

  2. Select Access management Identity providers

  3. Select Add provider

  4. Select OpenID Connect

    • Provider URL: https://token.actions.githubusercontent.com Get thumbprint
    • Audience: sts.amazonaws.com
  5. Select Add provider

2. Create a new IAM role

An IAM role is required to start using the identity provider.

Details
  1. Sign in to the AWS Management Console and navigate to the IAM console

  2. Select Access management Roles

  3. Select Create role

  4. Select Web identity

    • Identity provider: token.actions.githubusercontent.com
    • Audience: sts.amazonaws.com
  5. Select Next

  6. Add permissions

    • Select PowerUserAccess

    • 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.

  7. Select Next

  8. Role name: terrateam

  9. Select Create role

  10. Select the terrateam role

Note the ARN as you will need this for the next step

3. Modify the Terrateam GitHub Workflow File

In order to use OIDC, the GitHub Workflow File requires two modifications under jobs->terrateam.

This file must be merged into your default branch as .github/workflows/terrateam.yml.

Required changes (full example below):

  • Permissions
permissions: # Required to pass credentials to the Terrateam action
id-token: write
contents: read
  • Configure AWS credentials
steps:
- name: Configure AWS credentials
uses: aws-actions/configure-aws-credentials@v1
with:
role-to-assume: $YOUR_TERRATEAM_ROLE_ARN # REPLACE (format: arn:aws:iam::AWS_ACCOUNT_NUMBER:role/TERRATEAM_ROLE_NAME)
aws-region: us-east-1

Full Example

Add to your default branch as .github/workflows/terrateam.yml
tip

Replace $YOUR_TERRATEAM_ROLE_ARN with the ARN of the IAM role you created in the IAM role creation step

##########################################################################
# DO NOT MODIFY
#
# THIS FILE SHOULD LIVE IN .github/workflows/terrateam.yml
#
# Looking for the Terrateam configuration file? .terrateam/config.yml.
#
# See https://docs.terrateam.io/configuration/overview for details
##########################################################################
name: 'Terrateam Workflow'
on:
workflow_dispatch:
inputs:
# The work-token is automatically passed in by the Terrateam backend
work-token:
description: 'Work Token'
required: true
api-base-url:
description: 'API Base URL'
jobs:
terrateam:
permissions: # Required to pass credentials to the Terrateam action
id-token: write
contents: read
runs-on: ubuntu-latest
name: Terrateam Action
steps:
- name: Configure AWS credentials
uses: aws-actions/configure-aws-credentials@v1
with:
role-to-assume: $YOUR_TERRATEAM_ROLE_ARN # REPLACE (format: arn:aws:iam::AWS_ACCOUNT_NUMBER:role/TERRATEAM_ROLE_NAME)
aws-region: us-east-1
- uses: actions/checkout@v2
with:
fetch-depth: 0
- name: Run Terrateam Action
id: terrateam
uses: terrateamio/action@v1 # Do not replace with a custom image. Doing so may cause Terrateam to not operate as intended.
with:
work-token: '${{ github.event.inputs.work-token }}'
api-base-url: '${{ github.event.inputs.api-base-url }}'
env:
SECRETS_CONTEXT: ${{ toJson(secrets) }}

Terrateam can now authenticate using short-lived AWS credentials 🔒

AWS Provider Configuration Example

The official aws-actions/configure-aws-credentials GitHub Action creates short-lived credentials using GitHub's OIDC provider and configures them for use in the Terrateam action.

Example

The following is an example configuration that can be used with your newly created OIDC connection.

provider "aws" {
region = "us-west-2"
}