How to Seamlessly Integrate GitHub with AWS using OpenID Connect for GitHub Actions

As more and more organizations adopt a DevOps approach to software development, seamless and secure integration between different tools and platforms is becoming increasingly important. In this blog post, I'll show you how to integrate GitHub with AWS using OpenID Connect for GitHub Actions.

What is OpenID Connect?

OpenID Connect is an authentication protocol that allows users to authenticate themselves to an application by using a third-party identity provider, such as GitHub. OpenID Connect provides a standard way to exchange authentication and authorization data between different systems, making it a popular choice for integrating different platforms securely.

Why Integrate GitHub with AWS using OpenID Connect?

Without OIDC, When GitHub Actions workflows need to access cloud providers for deployment or using their services, requiring credentials to be stored as secrets in GitHub. However, this method of hardcoding secrets requires duplicating them in both the cloud provider and GitHub.This is not secure.

With OIDC, we don't have to store any secrets.

How to Integrate GitHub with AWS using OpenID Connect for GitHub Actions?

To integrate GitHub with AWS using OpenID Connect, you will need to follow these steps:

Steps:

1.Create an Identity Provider in AWS

The first step is to create an Identity Provider in AWS. To do this, you will need to sign in to the AWS Management Console and navigate to the IAM (Identity and Access Management) service. From there, you can create a new identity provider and select OpenID Connect as the provider type. You will need to provide the Client ID and Client Secret for your GitHub application, which you can obtain from your GitHub Developer Settings.

Provider URL: https://token.actions.githubusercontent.com
This is the Github OpenID Connect URL for authentication requests

Audiences : sts.amazonaws.com
(Audiences is also known as client ID)
Audience is a value that identifies the application that is registered with an OpenID Connect provider

2.Assign a role

You can create a role or add an existing role.But make sure that its trust relationships of that role configured as follows.

Trust relationships of the role

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Federated": "<Arn of Identity provider>"
            },
            "Action": "sts:AssumeRoleWithWebIdentity",
            "Condition": {
                "StringEquals": {
                    "token.actions.githubusercontent.com:aud": "sts.amazonaws.com",
                    "token.actions.githubusercontent.com:sub": "repo:<GitHub organization name>/<GitHub repo name>:ref:refs/heads/<branch name>"
                }
            }
        }
    ]
}

You have to replace the placeholders with correct values.

Arn of Identity Provider - ARN of the Identity Provider that you created in step 1.
GitHub organization name - your GitHub Organization name
GitHub repo name - your GitHub Repository name
branch name - Your branch that you want to trigger Github actions

Permissions of the role

Set the permissions according to your requirement.
E.g:- If your Github actions need only S3 bucket access then make sure you just give only that permission.

3.Configure GitHub Actions

Next, you will need to configure GitHub Actions to use OpenID Connect for authentication. To do this, you will need to create a new GitHub Actions workflow file and add the necessary configuration. You will need to specify the ID of your AWS Identity Provider, as well as the client ID and client secret for your GitHub application.

this is an example of GitHub Actions workflow file (.github/workflows/dev.yaml) which achieve the repository and upload to s3 bucket when code pushes to dev branch.

name: Dev Branch Build and Deploy

on:
  push:
    branches:
      - dev
env:
  BUCKET_NAME_PREFIX: "test-bucket"
  AWS_REGION: "ap-southeast-1"
  GITHUB_REF: "dev"

jobs:
  build:
    name: Build and Package
    runs-on: gh-runner
    permissions:
      id-token: write
      contents: read
    steps:
      - uses: actions/checkout@v3
        with:
          path: "./${{ env.GITHUB_REF }}"
      - name: Extract branch name
        shell: bash
        run: echo "##[set-output name=branch;]$(echo ${GITHUB_REF#refs/heads/})"
        id: extract_branch
      - name: Extract commit hash
        shell: bash
        run: echo "##[set-output name=commit_hash;]$(echo "$GITHUB_SHA")"
        id: extract_hash
      - name: configure aws credentials
        uses: aws-actions/configure-aws-credentials@v1
        with:
          role-to-assume: <role arn>
          role-session-name: <role session-name>
          aws-region: ${{ env.AWS_REGION }}
      # Copy build directory to S3
      - name: Copy build to S3
        run: |
          cd ${{ env.GITHUB_REF }} 
          pwd
          git status 
          git archive --format=zip --output=artifact.zip ${{ steps.extract_branch.outputs.branch }}          
          aws s3 cp ./artifact.zip s3://${{ env.BUCKET_NAME_PREFIX }}-${{ steps.extract_branch.outputs.branch }}/artifact.zip

4.Test the Integration

Once you have configured GitHub Actions, you can test the integration by pushing a change to your GitHub repository. GitHub Actions should automatically trigger a build and deploy process in AWS, using the OpenID Connect authentication data to authenticate the user.

Benefits of using OIDC

One of the primary benefits of using OIDC tokens is the elimination of the need for cloud secrets. Instead of duplicating your cloud credentials as long-lived GitHub secrets, by this method, it request a short-lived access token from the provider through OIDC. This eliminates the need to store secrets in your GitHub repository, thus reducing the risk of secrets being accidentally or intentionally exposed.

Another major benefit is,OIDC tokens allow for the rotation of credentials. With OIDC, your cloud provider issues a short-lived access token that is only valid for a single job, and then automatically expires. This ensures that credentials are rotated frequently, thus reducing the likelihood of misuse or abuse.

Blog