GitHub Actions OIDC AWS Integration: A Step-by-Step Guide

In this blog, we will look at GitHub Actions OIDC AWS Integration using a step-by-step example that secures access to the AWS cloud.

By the end of this guide, you’ll understand:

• Why OIDC is a secure way to connect GitHub Actions with AWS
• How GitHub’s OIDC integration works with AWS
• A step-by-step method to set up OIDC using IAM roles
• How to test the setup using AWS CLI and deploy to EKS with GitHub Actions workflows

Lets gets started.

Sample AWS Deployment Workflow With GitHub Actions

The following image gives you a context on how GitHub Actions interact with AWS services.

In the above workflow, we have used an example of GitHub actions workflow that interacts with AWS EKS to push images to ECR and deploy applications on EKS.

Understanding AWS Authentication Methods for GitHub Actions

For the GitHub actions to interact with AWS services, it needs to authenticate with AWS.

Let's look at the different ways you can access AWS services like an EKS cluster from GitHub Actions. This way you understand why OpenID Connect is secure than other methods.

1. Access Keys And Secret Keys

The basic way to access EKS clusters from actions is by using AWS access and secret keys.

Here is an example workflow configuration.

- name: Configure AWS credentials
  uses: aws-actions/configure-aws-credentials@v1
  with:
    aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
    aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
    aws-region: us-west-2

But, storing or using AWS access and secret keys (long-lived tokens) directly in CI/CD pipelines is considered insecure and not a recommended approach.

If these long-term credentials are leaked, anyone with access to them can potentially control your AWS resources, leading to data breaches or infrastructure compromise.

2. For Self-Hosted Runners: Using IAM Roles

The recommended approach to overcome the limitations of using access keys and secrets is AWS IAM roles.

IAM roles use Temporary security credentials. It is not stored with the user but are created dynamically and given to the user when needed. They can be set to last from a few minutes to several hours.

Once they expire, AWS no longer recognizes them or allows access through API requests made with them.

3. OpenID Connect (A Secure Approach)

OpenID Connect (OIDC) allows your GitHub Actions workflows to access resources in AWS without needing to store AWS credentials as long-lived GitHub secrets.

This means that a GitHub Actions workflow can request a short‑lived OIDC token from GitHub, present it to AWS IAM, and get a temporary role. There is no need to store access keys in secrets.

Also, temporary credentials do not exist until a workflow needs them, and they expire shortly after (zero standing permissions).

OIDC can be used for both Github hosted runners and self-hosted runners.

In this guide, our focus is only on the OpenID Connect based GitHub actions workflow with AWS.

Configuring GitHub Actions OIDC with AWS IAM

Now, let's look at a practical example, where I show you step by step how to configure OIDC with GitHub and AWS.

Step 1: Create the OIDC Identity Provider in AWS IAM for GitHub

In this setup, GitHub is the OpenID Provider. So we need to setup the provider details on AWS.

Navigate to AWS IAM → Identity Providers.

Add a new provider:

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

Step 2: Create WebIdentity IAM Role with Trust Policy

If you click the created Identity provider, you will get an option to Assign role as shown below.

Click Assign role and select the create a new role option.

Next, select the trusted entity type "Web Identity" to log in to AWS with OIDC.

Now, enter the web identity information. Under Github Organization, enter your Github organization ID.

Next, add IAM permissions. Here, I am adding admin permissions. But as per your requirements and use cases, you can add only the required IAM permissions that your runner needs.

In the next page, enter the role name (eg, github-actions-workflow-role), review the details and click create role.

Step 3: Add the IAM Role arn to Github

Now you need to add the role ARN to GitHub Secrets.

You have two choices:

1. Organization secret: Available to all repositories in the organization.
2. Repository secret: Available only to one repository.

Pick the option that fits your needs. For this demo, we’ll set the secret at the organization level.

Navigate to the org or repo settings.

In the left pane you will find the secrets and variables option. Under secrets and variables, choose actions.

AWS_OIDC_ROLE

Step 4: Testing the OIDC Connection to AWS

The next step is to validate the integration of OIDC with AWS.

The following action uses the aws-actions/configure-aws-credentials action to configure OIDC in workflows. secrets.AWS_OIDC_ROLE fetches the secret arn we created in the previous step.

- name: Configure AWS credentials using OIDC
  uses: aws-actions/configure-aws-credentials@v4
  with:
    role-to-assume: ${{ secrets.AWS_OIDC_ROLE }}
    aws-region: us-west-2

To test this, we will create a simple GitHub Actions working to list AWS instances.

Create a ec2-list.yaml workflow file in your repository and copy the following workflow.

name: List EC2 Instances

on:
  push:
    branches:
      - main

permissions:
  id-token: write
  contents: read

jobs:
  list-ec2:
    runs-on: ubuntu-latest

    steps:
    - name: Checkout repository
      uses: actions/checkout@v3

    - name: Configure AWS credentials using OIDC
      uses: aws-actions/configure-aws-credentials@v4
      with:
        role-to-assume: ${{ secrets.AWS_OIDC_ROLE }}
        aws-region: us-west-2

    - name: List EC2 Instances
      run: |
        aws ec2 describe-instances \
          --query "Reservations[*].Instances[*].InstanceId" \
          --output table

If all the configurations are correct, when you run the workflow, you should be able to see the successful output as shown below.

Now that we have validated the OIDC AWS access using a workflow, we will test an EKS-based deployment using a workflow.

Step 5: Enabling GitHub Actions Access to Amazon EKS via OIDC

When setting up GitHub Actions to access an EKS cluster, you need to take several specific steps beyond basic AWS authentication.

This is because accessing an EKS cluster requires both AWS IAM permissions and Kubernetes-specific RBAC settings.

aws eks create-access-entry \
    --cluster-name <your-cluster-name> \
    --principal-arn <your-role-arn-here>
    --kubernetes-groups github-runners \
    --type STANDARD \
    --username github-actions-oidc

Next, we set up access policies for the arn to access Kubernetes objects.

You can list the available access polices using the following command.

aws eks list-access-policies --output table

Most runners would admin policy to deploy and manage the clusters. So, for testing purposes, I am going to assign AmazonEKSAdminPolicy

  aws eks associate-access-policy \
  --cluster-name <your-cluster-name> \
  --principal-arn <your-role-arn-here> \
  --policy-arn arn:aws:eks::aws:cluster-access-policy/AmazonEKSViewPolicy \
  --access-scope type=cluster

Step 6: Test The EKS Workflow

• GitHub Actions requests an OIDC token from its OIDC provider.
• The token is presented to AWS STS (AssumeRoleWithWebIdentity).
• AWS validates the token and issues short-lived credentials for the IAM role.
• The workflow uses these credentials to access AWS resources.

Here is an example of a GitHub Actions workflow that implements OIDC for AWS. I have used the workflow_dispatch trigger to deploy the workflow manually from the GitHub UI.

name: Deploy NGINX to EKS

on:
  workflow_dispatch:

permissions:
  id-token: write
  contents: read

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
    - name: Checkout repository
      uses: actions/checkout@v3

    - name: Configure AWS credentials using OIDC
      uses: aws-actions/configure-aws-credentials@v4
      with:
        role-to-assume: ${{ secrets.AWS_OIDC_ROLE }}
        aws-region: us-west-2

    - name: Set up kubeconfig
      run: |
        aws eks update-kubeconfig --region us-west-2 --name eks-spot-cluster-bibin

    - name: Deploy NGINX to EKS
      run: |
        kubectl create deployment nginx --image=nginx --port=80 --dry-run=client -o yaml | kubectl apply -f -

In the above workflow, update the Role URL and cluster name before running it.

If you trigger the workflow manually, you will see the successful output as shown below.

OpenID Connect Workflow

Now that we have done the hands-on, let's look at the whole workflow. It will make more sense to you now.

The following image shows the end-to-end workflow.

Here is how it works.

• In AWS, as a one-time task, we establish an OIDC trust between AWS and the GitHub workflows by creating an OIDC Identity Provider with a relevant IAM role to assume.
• Behind the scenes, the aws-actions/configure-aws-credentials action makes a request to GitHub's OIDC provider for a JWT token.
• It then takes this OIDC token and makes a call to the AWS Security Token Service. AWS then verifies the token and details with the entries configured in the IAM OIDC provider
• Once validated, AWS STS generates temporary short-lived (defaults to 1 hr) AWS security credentials. However, you can configure it to have ranges from 15 mins to 12 hours.
• Then aws-actions/configure-aws-credentials action exposes these credentials as environment variables (e.g., AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN)
• Now, in your workflow, when you use AWS CLI or an SDK like boto3, it makes use of the credentials in the environment variables.

Configuring OIDC for AWS with Self-Hosted GitHub Enterprise Server (GHES)

You can also setup OIDC with self-hosted GitHub Enterprise servers.

When when working with GHES OIDC you need to consider the following.

1. The issuer URL will be your GHES hostname. For example, https://<GHES_HOSTNAME>/_services/token
2. The GHES instance's OIDC endpoint must be publicly accessible over HTTPS or allowed access to AWS IP ranges.

Conclusion

Securing your CI/CD pipelines is an important aspect of modern software development, especially when deploying applications to cloud environments like AWS.

By leveraging GitHub Actions OIDC for AWS, you can enhance the security of your workflows without the need for long-lived AWS credentials.

This approach not only mitigates the risks associated with access keys and secrets but also simplifies credential management through the use of temporary security credentials.

Now we would like to hear from you.

How do you manage credentials for AWS access through Github Actions?

Have you tried OIDC approach?

Do let us know in the comments.