Authenticate from GitHub Workflows to AWS Services using OpenID Connect (OIDC)

• Requires provisioning GitHub as an OpenID Connect Identity provider through AWS IAM
• Provides workflows access to AWS resources via short-lived credentials using the official configure-aws-credentials action
• Workflow must specify the AWS IAM role to assume

A sample workflow for creating an AWS ECR repository will used to demonstrate the procedure for completing the configuration.

GitHub and AWS details associated with the workflow are:

Add GitHub OIDC Identity Provider to AWS

The key details required as input for configuring the new IDP are:

• Provider URL: https://token.actions.githubusercontent.com
• Audience: sts.amazonaws.com

Add Identity Provider in IAM

From the AWS console, navigate to “IAM > Identity Providers > Add provider“.

1. Choose OpenID Connect for the provider type
2. Enter the Provider URL as noted in previous section
3. Enter Audience from the previous section
4. Click Get thumbprint
5. Click Add Provider

Once the provider has been been successfully added, it should appear in the Identity Providers list.

At this point, we have established “trust” between the Identity Provider (GitHub) and the target AWS account.

The following will still need to created before the workflow is able to authenticate to AWS and perform the actions required:

• IAM role which includes our new GitHub OIDC IdP as a trusted web entity
• an IAM policy granting permissions to allow the workflow access to the resources (in this case, the workflow needs access to create an ECR repository)

Creation of an appropriate role is covered in the next section.

Create an IAM Role for GitHub

From the AWS console:

• navigate to “IAM > Roles > Create role”
• details below reflect the values for the sample workflow previously mentioned

• After clicking “Next“, a list of policies to select from will be displayed
• We will attach our own custom policy definition later, so we can ignore screen for now and click “Next“
• Provide a Role name and Description

• The following confirms creation of the role:

Attach an IAM Policy to the Role

From the AWS console:

• navigate to “IAM > Policies > Create policy”
• add a policy definition that allows the workflow create an ECR repository in the target AWS account

{
	"Version": "2012-10-17",
	"Statement": [
		{
			"Sid": "AllowCreateRepo",
			"Effect": "Allow",
			"Action": "ecr:CreateRepository",
			"Resource": "*"
		}
	]
}

• Provide an appropriate name and description for the new policy

Attach the new policy to the IAM role:

• select the role: “IAM > Roles > assumed-oidc-test-repo“
• add the new policy via “Add permissions > Attach policies“
• filter for name of the policy and attach it to the role

• note down the arn of the role: arn:aws:iam::123456789123:role/assumed-oidc-test-repo

Testing the Workflow

Sample workflow definition:

name: Create ECR Repo

on: [push, workflow_dispatch]

env:
    AWS_REGION: us-east-1
    ECR_REPOSITORY: my-ecr-sample-repo

permissions:
  contents: read
  id-token: write

jobs:
  create-ecr-repo:
    runs-on: self-hosted
    steps:
    - name: Configure AWS Credentials
      uses: aws-actions/configure-aws-credentials@v4
      with:
        aws-region: ${{ env.AWS_REGION }}
        role-to-assume: arn:aws:iam::${{ secrets.AWS_ACCOUNT_ID }}:role/assumed-oidc-test-repo
        role-session-name: assumed-oidc-test-repo-session	
    - name: Create repo
      run: |
        aws ecr create-repository --repository-name ${{ env.ECR_REPOSITORY }}

Key Points to Note for the Workflow:

• AWS account ID has been configured as an Actions repository secret
• Official GitHub configure-aws-credentials action has been used for requesting short-lived credentials via OIDC, with the arn of IAM role created in section “Create an IAM Role for GitHub“, being provided as the role-to-assume
• Permissions settings have been included, i.e:
  • contents: read
    This is generally included to grant allow actions/checkout to execute
  • id-token: write
    This permits the workflow to request an OIDC JSON Web Token (JWT) from AWS

...
...
permissions:
  contents: read
  id-token: write
...

Running the Workflow

The following shows a log from a successful execution: