Thursday, 3 September 2026

Eliminating Long-Lived Cloud Secrets in CI/CD: Configuring GitHub Actions with AWS OIDC

# Eliminating Long-Lived Cloud Secrets in CI/CD: Configuring GitHub Actions with AWS OIDC

Storing static cloud credentials (such as `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`) inside GitHub repository secrets introduces significant operational and security overhead. Long-lived credentials risk credential leakage, require manual or automated rotation mechanisms, and often lack fine-grained scoping.

Using **OpenID Connect (OIDC)**, your GitHub Actions workflows can authenticate directly against AWS Identity and Access Management (IAM) to receive short-lived, automatically rotated credentials through AWS Security Token Service (STS). In this post, we explore how OIDC authentication works and provide a step-by-step implementation guide.

---

## How GitHub Actions OIDC Authentication Works

Instead of storing static credentials, GitHub Acts as an OIDC Identity Provider (IdP). The authentication flow follows these steps:

```
+-------------------+ 1. Request JWT Token +-------------------------+
| GitHub Actions | ---------------------------------> | GitHub OIDC Provider |
| Workflow Runner | <--------------------------------- | (token.actions) |
+-------------------+ 2. Signed OIDC JWT +-------------------------+
|
| 3. AssumeRoleWithWebIdentity (JWT + Role ARN)
v
+-------------------------+
| AWS STS Service | ---> 4. Validates JWT Signature & Claims
+-------------------------+ against IAM Role Trust Policy
|
v 5. Returns Temporary Credentials (e.g., 1-hour session)
+-------------------+
| GitHub Actions | ---> Interacts with AWS Resources (S3, ECR, EKS)
| Workflow Runner |
+-------------------+
```

1. The GitHub Actions job requests an ephemeral OIDC JSON Web Token (JWT) from GitHub’s OIDC token service.
2. GitHub generates a cryptographically signed token containing specific claims (repository, branch, environment, actor).
3. The workflow presents the JWT to AWS STS via the `AssumeRoleWithWebIdentity` API call.
4. AWS validates the token's signature against GitHub's public OIDC keys and evaluates the IAM Role's trust policy.
5. STS returns temporary AWS credentials valid only for the configured duration of the job.

---

## Step 1: Provisioning the OIDC Provider and IAM Role (Terraform)

Before your workflow can assume a role, you must register GitHub as an OIDC provider in AWS IAM and create a trust policy tied to your repository.

```hcl
# https://www.google.com/url?q=http://main.tf&source=gmail&ust=1788583225469000&sa=E

provider "aws" {
region = "us-east-1"
}

# 1. Fetch GitHub's OIDC Thumbprint
data "tls_certificate" "github" {
url = "https://www.google.com/url?q=https://token.actions.githubusercontent.com/.well-known/openid-configuration&source=gmail&ust=1788583225469000&sa=E"
}

# 2. Create the OIDC Identity Provider in AWS IAM
resource "aws_iam_openid_connect_provider" "github_actions" {
url = "https://www.google.com/url?q=https://token.actions.githubusercontent.com&source=gmail&ust=1788583225469000&sa=E"
client_id_list = ["https://www.google.com/url?q=http://sts.amazonaws.com&source=gmail&ust=1788583225469000&sa=E"]
thumbprint_list = [data.tls_certificate.github.certificates[0].sha1_fingerprint]
}

# 3. Create IAM Role with Scoped Trust Policy
resource "aws_iam_role" "github_deploy_role" {
name = "github-actions-deploy-role"

assume_role_policy = jsonencode({
Version = "2012-10-17"
Statement = [
{
Effect = "Allow"
Principal = {
Federated = aws_iam_openid_connect_provider.github_actions.arn
}
Action = "sts:AssumeRoleWithWebIdentity"
Condition = {
StringEquals = {
"token.actions.githubusercontent.com:aud" = "https://www.google.com/url?q=http://sts.amazonaws.com&source=gmail&ust=1788583225469000&sa=E"
}
StringLike = {
# Restrict authentication to the 'main' branch of your specific repository
"token.actions.githubusercontent.com:sub" = "repo:my-organization/my-app:ref:refs/heads/main"
}
}
}
]
})
}

# 4. Attach Permissions Policy to the Role
resource "aws_iam_role_policy" "deploy_permissions" {
name = "github-actions-ecr-push"
role = https://www.google.com/url?q=http://aws_iam_role.github_deploy_role.id&source=gmail&ust=1788583225469000&sa=E

policy = jsonencode({
Version = "2012-10-17"
Statement = [
{
Effect = "Allow"
Action = [
"ecr:GetAuthorizationToken",
"ecr:BatchCheckLayerAvailability",
"ecr:GetDownloadUrlForLayer",
"ecr:BatchGetImage",
"ecr:PutImage",
"ecr:InitiateLayerUpload",
"ecr:UploadLayerPart",
"ecr:CompleteLayerUpload"
]
Resource = "*"
}
]
})
}

output "role_arn" {
value = aws_iam_role.github_deploy_role.arn
}
```

---

## Step 2: Configuring the GitHub Actions Workflow

In your repository, update your workflow YAML file. You must add the `id-token: write` permission to allow the runner to request the OIDC token.

```yaml
# .github/workflows/deploy.yml
name: Build and Deploy to AWS

on:
push:
branches:
- main

permissions:
id-token: write # Required for requesting the JWT
contents: read # Required for actions/checkout

jobs:
deploy:
name: Authenticate & Deploy
runs-on: ubuntu-latest

steps:
- name: Checkout Source Code
uses: actions/checkout@v4

- name: Configure AWS Credentials via OIDC
uses: aws-actions/configure-aws-credentials@v4
with:
role-to-assume: arn:aws:iam::123456789012:role/github-actions-deploy-role
aws-region: us-east-1
audience: https://www.google.com/url?q=http://sts.amazonaws.com&source=gmail&ust=1788583225469000&sa=E

- name: Verify Authentication
run: |
aws sts get-caller-identity
```

When this job runs, `configure-aws-credentials` requests the JWT, contacts AWS STS, and exports standard AWS environment variables (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN`) into subsequent workflow steps without ever storing a secret in repository settings.

---

## Security Best Practices for OIDC in CI/CD

1. **Strictly Constrain the Subject (`sub`) Claim**: Never use wildcard subjects like `repo:my-org/*`. Always constrain to the specific repository and either a protected branch (`ref:refs/heads/main`) or environment (`environment:production`).
2. **Minimize IAM Role Permissions**: Follow the principle of least privilege. Grant only the exact actions required for the pipeline stage (e.g., ECR push vs. ECS task update).
3. **Limit Role Session Duration**: Set `role-session-duration` to the minimum time required for deployment (e.g., 900–1800 seconds).
4. **Audit via AWS CloudTrail**: OIDC logins log `AssumeRoleWithWebIdentity` events in CloudTrail, providing clear audit visibility into which GitHub workflow run and commit triggered an action.

---

## Key Implementation Takeaways

* **Zero Secret Storage**: Eliminates credential leak vectors through compromised repository secrets or CI logs.
* **Automatic Rotation**: Every job execution receives short-lived credentials that expire automatically after the run.
* **Fine-Grained Governance**: AWS IAM trust conditions ensure only authenticated requests from authorized repositories and branches can assume operational roles.