Securely Accessing AWS Resources from GitHub Actions using OpenID Connect (OIDC)

Introduction

Hardcoding AWS credentials into CI/CD pipelines is one of the most common mistakes teams make—and one of the easiest to avoid.

In this blog, you’ll learn how to connect GitHub Actions with AWS using OpenID Connect (OIDC), a method that skips access keys entirely. Instead of storing secrets, GitHub will request short-term credentials that allow access only to the AWS resources your workflow needs—like listing S3 buckets.

We’ll cover how this works, why it’s safer than using access keys, and how to set it up step by step.

Understanding OIDC with GitHub and AWS

OpenID Connect (OIDC) is an identity layer that sits on top of the OAuth 2.0 protocol. In simple terms, it allows one service (like GitHub) to prove its identity to another service (like AWS) using a signed token.

GitHub acts as the identity provider by issuing a short-lived token during each workflow run. AWS trusts GitHub to confirm the identity of the workflow, based on the configuration you set in your IAM roles and identity provider.

This setup lets GitHub Actions request temporary access to AWS without needing stored credentials. You define what GitHub is allowed to access by creating an IAM role in AWS. That role contains both:

• A trust policy that accepts GitHub-issued tokens from a specific repo or branch.
• A permission policy that limits what resources can be accessed.

In this setup:

• No access keys are used.
• No secrets are stored in GitHub.
• Access is limited and temporary.

This model fits CI/CD use cases well because it grants only the access needed for the workflow, only for the time it's running.

How the Authentication Flow Works

When a GitHub Actions workflow runs, a short chain of steps takes place behind the scenes to connect to AWS without storing any credentials. Here’s what happens:

1. Workflow Starts
   A workflow is triggered in your GitHub repository (for example, on a push to the main branch).
2. GitHub Requests a Token
   GitHub creates a signed identity token (OIDC token) for that specific workflow run.
3. Token is Sent to AWS
   The workflow uses the token to request temporary access from AWS by calling the Security Token Service (STS).
4. AWS Verifies the Token
   AWS checks if the token is valid by comparing it against your configured identity provider and IAM role trust policy.
5. Temporary Credentials Are Issued
   If everything matches, AWS responds with temporary credentials that the GitHub runner can use.
6. Workflow Uses AWS Access
   The runner can now run commands like aws s3 ls, limited to the permissions of the role.

This all happens automatically during the workflow. The token is short-lived, tied to the specific job, and cannot be reused elsewhere. Access is tightly scoped to what you define in the role.

Step-by-Step Setup Guide

AWS Configuration

Step 1: Add GitHub as an Identity Provider

• Go to the AWS Console → IAM → Identity providers.
• Provider URL:https://token.actions.githubusercontent.com

• Audience:sts.amazonaws.com

• Save the provider.
• Select Provider type: OpenID Connect.
• Click Add provider.

Step 2: Create an IAM Role for GitHub Actions

• Go to IAM → Roles → Create Role.
• Choose Web identity as the trusted entity type.
• Select the GitHub OIDC provider you just added.
• Set the audience to:sts.amazonaws.com

• Continue and attach a policy. For this example, attach AmazonS3ReadOnlyAccess or a custom policy with s3:ListAllMyBuckets.
• Save the role and copy its ARN.

• Name the role, e.g., GitHubActionsS3ReadOnly.
• Under Conditions, add a rule to allow only a specific repo (e.g., repo:kubenine/github_keyless_authentication:ref:refs/heads/main)

GitHub Configuration

Step 1: Add Role ARN as a GitHub Secret

• Go to your GitHub repository → Settings → Secrets and variables → Actions.
• Name: GH_ACTIONS_AWS_ROLE

• Value: arn:aws:iam::<your-account-id>:role/GitHubActionsS3ReadOnly
• Click New repository secret.

GitHub Actions Workflow Example: List S3 Buckets

Now that AWS and GitHub are connected, create a workflow file:

Create a new file at:

.github/workflows/list_s3_buckets.yml

name: List S3 Buckets
on:
  push:
    branches:
      - main
jobs:
  list_s3:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read
    steps:
      - name: Checkout code
        uses: actions/checkout@v2
      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v1
        with:
          role-to-assume: ${{ secrets.GH_ACTIONS_AWS_ROLE }}
          aws-region: us-east-1
      - name: List S3 buckets
        run: aws s3 ls

What Happens When This Runs

• GitHub requests a token for this workflow run.
• AWS validates the token and grants temporary credentials.
• The aws s3 ls command runs using those credentials.
• The output will appear in the GitHub Actions log, showing your S3 buckets.

• No access keys are stored, and access is restricted to exactly what the role allows.

Traditional AWS Authentication (Why This Is Better)

Before token-based authentication became available, the standard way to access AWS from CI/CD tools like GitHub Actions was by creating an IAM user and using its access key and secret key. These keys would often be stored in GitHub Secrets or environment variables and injected into the workflow.

That method works—but it comes with serious drawbacks:

• Hard to manage: Keys must be rotated regularly and updated across all workflows or systems that use them.
• Easy to leak: If a key is committed by mistake or exposed in logs, it can be misused until revoked.
• Always active: Unlike temporary tokens, long-term keys can be used at any time unless explicitly deactivated.
• Too much access: IAM users often have more permissions than needed, increasing the risk of misuse.
• Not tied to context: Access keys don't know where or why they are being used.

In contrast, the OIDC method you've just configured:

• Uses no permanent credentials.
• Grants access only for the duration of a single workflow run.
• Limits access to the specific repository and branch defined in the IAM role trust policy.
• Can be fine-tuned per workflow, per project, or per team.

This is a safer and more maintainable way to manage AWS access in CI/CD pipelines.

Conclusion

Connecting GitHub Actions to AWS using OpenID Connect removes the need for long-term access keys, reducing risk and simplifying management. By setting up a trusted relationship between GitHub and AWS, your workflows can request short-lived credentials that only allow access to what’s needed—and only for the time they’re running.

This setup is well-suited for modern CI/CD pipelines. It keeps your infrastructure safer, your workflows cleaner, and your access tightly controlled.

If you’re still using access keys in your GitHub workflows, this is a good time to move to a more secure and flexible setup.

At Kubenine, we help teams simplify cloud operations, automate workflows, and build secure infrastructure using AWS, Kubernetes, and modern DevOps practices. If you’d rather stay focused on your product while we handle the platform, we’re here to help.