Naveed Ahmed

Posted on Nov 3 Originally published at blog.naveedkumbhar.com

GitHub Actions OIDC AWS: Secure CI/CD Without Access Keys

#aws #security #githubactions #devops

Originally published on Naveed Ahmed's Engineering Blog.

Still storing AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY in GitHub Actions secrets?

It works, but it also means managing long-lived credentials, rotation, and the risk of those keys being exposed.

For workflows deploying to AWS, there's a better option: OpenID Connect (OIDC).

GitHub Actions can use OIDC federation to request temporary AWS credentials without storing permanent AWS access keys.

Here's how it works.

1. Understanding GitHub Actions OIDC

The authentication flow looks like this:

GitHub Actions
      |
      | Request signed OIDC JWT
      v
GitHub OIDC Provider
      |
      | JWT
      v
AWS STS
      |
      | Validate IAM role trust policy
      v
Temporary AWS Credentials
      |
      v
Deploy to AWS

AWS uses AssumeRoleWithWebIdentity to exchange the signed token for temporary credentials after validating the issuer, audience, and allowed subject.

2. Register the GitHub OIDC Provider in AWS

Configure an IAM OIDC identity provider with:

Provider URL:
https://token.actions.githubusercontent.com

Audience:
sts.amazonaws.com

You can configure it in the AWS IAM console, AWS CLI, or Terraform.

For production, keeping identity infrastructure in Terraform helps make the configuration reviewable.

3. Configure a Restricted IAM Trust Policy

This is the most important step.

A trust policy should identify the GitHub repository and deployment context that may assume the role.

For example, a branch-scoped policy condition can look like:

{
  "StringEquals": {
    "token.actions.githubusercontent.com:aud": "sts.amazonaws.com",
    "token.actions.githubusercontent.com:sub": "repo:YOUR_ORG/YOUR_REPO:ref:refs/heads/main"
  }
}

This is the condition portion of a trust policy, not the complete policy document.

For repositories using GitHub's newer immutable OIDC subject format, adjust the value to match the actual token.

Avoid broad wildcards that unintentionally authorize additional repositories or workflows.

Also restrict the permissions attached to the role. A tightly scoped trust policy won't help much if the role has unnecessary administrator access.

4. Configure GitHub Actions

The workflow needs permission to request an OIDC token.

name: AWS OIDC Authentication

on:
  workflow_dispatch:

permissions:
  id-token: write
  contents: read

jobs:
  verify-aws:
    runs-on: ubuntu-latest
    steps:
      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::123456789012:role/github-oidc-role
          aws-region: us-east-1

      - name: Check caller identity
        run: aws sts get-caller-identity

Replace the example AWS account ID and IAM role.

For production, pin third-party and security-sensitive actions to reviewed commit SHAs.

The important point: id-token: write authorizes requesting an OIDC token. It does not grant AWS permissions by itself.

AWS evaluates the role trust policy before allowing role assumption.

5. Common OIDC Authentication Problems

If you encounter AccessDenied or a role-assumption failure, check:

The IAM identity provider exists in the correct AWS account.
The token audience matches the trust policy.
The subject claim matches the repository and deployment context.
The job has id-token: write.
The role ARN is correct.
The workflow is running from an allowed branch or protected environment.

If you use GitHub Environments, remember that the OIDC subject format differs from a branch-scoped subject.

6. Production Security Checklist

For a safer setup:

Restrict IAM trust to authorized repository identities.
Use protected branches and deployment environments.
Grant only necessary AWS permissions.
Keep development and production roles separate.
Review third-party GitHub Actions.
Monitor role assumption and AWS API activity through CloudTrail.
Avoid exposing temporary credentials in workflow logs.

OIDC removes the need to store permanent AWS keys for this authentication flow. It doesn't eliminate the need for secure workflow code and IAM design.

Read the Complete Tutorial

My full guide includes detailed OIDC architecture, AWS CLI and Terraform configuration, trust policy examples, GitHub Actions YAML, and troubleshooting.

GitHub Actions OIDC AWS: Full Secretless CI/CD Guide

Final Thoughts

Replacing static AWS keys with temporary credentials is a useful security improvement.

But the real protection comes from combining OIDC with strict IAM trust policies, least privilege, and protected deployment workflows.

Have you implemented GitHub Actions OIDC for your AWS deployments?

Written by Naveed Ahmed — DevOps & Platform Engineering

Engineering Blog | Kubernetes Mastery | GitHub

DEV Community