Using AWS from GitHub without Credentials

AWS allows external services to authenticate without any secrets, which increases security and also reduces management overhead. There is no need to create, distribute, or rotate any secrets.

This short guide shows how to set up and use this federated identity concept.

Pre-Requirements

To follow this guide, you need:

• A GitHub repo with read/write access. We will use my-org/demo
• A AWS account that can create roles.
• This example will use terraform for IaC deployments. Other tools or the WebUI should also work.

Configure AWS

You need to configure your AWS account as an identity provider. This can be done via the aws_iam_openid_connect_provider resource or via the AWS console. To use that identity provider, you need to create a role (or use an existing one) and establish a trust relationship with that role and your GitHub repo. This can can be archived with a iam_policy_document. In terraform, this would look like this:

 1# Get the identity provider arn
 2resource "aws_iam_openid_connect_provider" "github" {
 3  client_id_list  = ["sts.amazonaws.com"]
 4  thumbprint_list = ["1b511abead59c6ce207077c0bf0e0043b1382612"]
 5  url             = "https://token.actions.githubusercontent.com"
 6}
 7
 8# Create iam trust policy with github repo
 9data "aws_iam_policy_document" "github_actions_assume_role" {
10  statement {
11    actions = ["sts:AssumeRoleWithWebIdentity"]
12    principals {
13      # GitHub identity provider
14      type        = "Federated"
15      identifiers = [data.aws_iam_openid_connect_provider.github.arn]
16    }
17    condition {
18      test     = "StringLike"
19      variable = "token.actions.githubusercontent.com:sub"
20      # CHANGE ME: Set organization to my-org and to demo
21      values   = ["repo:${var.organization}/${var.git_repo_name}:*"]
22    }
23  }
24}
25
26# Create role and assign iam_policy_document
27resource "aws_iam_role" "github_actions" {
28  name               = "github-actions-${lower(var.organization)}-${lower(var.git_repo_name)}"
29  assume_role_policy = data.aws_iam_policy_document.github_actions_assume_role.json
30  tags               = var.tags
31}

This is all that is needed to use this identity on the AWS side. Most likely, you need additional permissions attached to your roles in order to deploy lambda functions, access S3 or push containers to ECR. Just create this polices and attach them to the role as you need.

Configure GitHub Actions

Now we need GitHub Actions to log into AWS. For this, we create a workflow with this minimal configuration:

 1name: Demo
 2
 3on:
 4  push:
 5    branches: [main]
 6
 7# Minimal permissions needed
 8permissions:
 9  contents: read
10  id-token: write
11
12jobs:
13  build-image:
14    runs-on: ubuntu-latest
15    steps:
16      - name: Checkout repository
17        uses: actions/checkout@v4
18
19      - name: Configure AWS Credentials
20        uses: aws-actions/configure-aws-credentials@v4
21        with:
22          # Your region. Can be a var or hardcoded
23          aws-region: ${{ vars.AWS_REGION }}
24          # Your role name you created previously
25          role-to-assume: ${{ secrets.AWS_ROLE }}
26
27      - name: S3 list
28        run: aws s3 ls MY_BUCKET

Note: When you use repo secrets/vars you need to have maintainer or admin permissions for the GitHub repo. Yet, both values are not considered confidential.

Now you can run AWS commands in GitHub actions without having to set or manage any passwords or keys.