GitHub Actions – No Need for AWS Secret Keys! Building an OIDC Configuration with Terraform to Securely Use IAM Roles

Introduction

When accessing AWS resources from GitHub Actions, the easiest approach is often to register secret keys (AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY) in GitHub secrets, which many of us tend to do.

However, this method is no longer recommended due to the risk of key leakage.

This is where OIDC (OpenID Connect) authentication comes in.
It allows you to assume AWS IAM Roles without secret keys safely.

In this article, I’ll explain how to set up AWS IAM Roles using OIDC with GitHub Actions.

What is OIDC?

• OIDC is an authentication protocol based on OAuth 2.0
• It allows GitHub to verify to AWS that "I am an official GitHub repository"
• AWS trusts GitHub’s verification and provides temporary credentials for the specified IAM Role

Why use OIDC?

• No secret keys needed → Eliminates the risk of key leakage
• Issues temporary credentials only during job execution → Safer because it uses temporary tokens for each authentication rather than fixed keys

Configuration

The Direct Secret Key Approach

The image below illustrates this approach:

1. Users directly issue secret keys for the IAM Role they need from IAM
2. They save the obtained secret keys in GitHub Actions Secrets and use them
3. During job execution, the Secret information is injected into the job

This is the basic flow.
In steps 1 and 2, users must issue and configure the secret keys themselves.
These secret keys need to be set with long expiration periods to avoid expiring.

This is a security concern, which is why we’d prefer to only grant necessary permissions when needed.

Using OIDC

Overall Flow

When using OIDC, the configuration increases slightly:

1. Prepare an IAM OIDC ID Provider and register information that GitHub Actions can be trusted
   (The logic is that if Provider information is registered on the AWS account side, which only administrators can access, then that Provider must be safe. This is because such information would not be intentionally registered without a takeover.)
2. On the GitHub Actions side, configure the CI to allow the GitHub OIDC Provider to issue JWT (JSON Web Token)
3. Users just need to execute the job. After authentication is complete, they receive access tokens for the requested IAM Role (authorized)

The following documents are also helpful for reference:

• https://docs.github.com/en/actions/security-for-github-actions/security-hardening-your-deployments/about-security-hardening-with-openid-connect
• https://docs.aws.amazon.com/ja_jp/IAM/latest/UserGuide/id_roles_providers_create_oidc.html

Configuration Example (Terraform)

0. Preparing an IAM Role with the Desired Permissions

locals {
  # Build provider ARN according to environment
  github_oidc_arn = "arn:aws:iam::your-account-id:oidc-provider/token.actions.githubusercontent.com"
  github_oidc_url = "token.actions.githubusercontent.com"
}

# Define ECS task execution role
resource "aws_iam_role" "ecs_task_role" {
  name = "EcsTaskRole-${var.env}"

  assume_role_policy = jsonencode({
    Version = "2008-10-17"
    Statement = [
      {
        Sid    = "GitHubOIDC"
        Effect = "Allow"
        Principal = {
          Federated = local.github_oidc_arn
        }
        Action = "sts:AssumeRoleWithWebIdentity"
        Condition = {
          StringEquals = {
            "${local.github_oidc_url}:aud" : "sts.amazonaws.com"
          }
          StringLike = {
            "${local.github_oidc_url}:sub" : "repo:your-repository-name/*:*"
          }
        }
      }
    ]
  })
}

• It might be cleaner to define and externalize the IAM Policy Document
• The key point is specifying the repository name that can use this role, limiting the scope. For security reasons, we cannot allow unrelated repositories to use this Role

If you need additional permissions, attach the minimum necessary policies.

For example, if you want to operate ECR, it would look like this:

resource "aws_iam_policy" "ecr_push_policy" {
  name        = "ECRPushPolicy-${var.env}"
  description = "Allow pushing to ECR repositories"

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

# Attach ECR push policy to ECS task execution role
resource "aws_iam_role_policy_attachment" "ecr_push_policy_attachment" {
  role       = aws_iam_role.ecs_task_role.name
  policy_arn = aws_iam_policy.ecr_push_policy.arn
}

1. Setting up IAM OIDC ID Provider

data "tls_certificate" "github_actions" {
  url = "https://token.actions.githubusercontent.com/.well-known/openid-configuration"
}

resource "aws_iam_openid_connect_provider" "github" {
  url = "https://token.actions.githubusercontent.com"

  client_id_list = ["sts.amazonaws.com"]

  thumbprint_list = [data.tls_certificate.github_actions.certificates[0].sha1_fingerprint]

  tags = {
    Name        = "github-actions"
    Environment = var.env
  }
}

2. GitHub Actions Configuration

name: Deploy

on:
  push:
    branches:
      - develop
  workflow_dispatch:

permissions:
  id-token: write
  contents: read

jobs:
  build_and_push:
    runs-on: ubuntu-latest

    steps:
    - name: Checkout
      uses: actions/checkout@v2

    - uses: aws-actions/configure-aws-credentials@v4
      with:
        role-to-assume: arn:aws:iam::(your account id):role/EcsTaskRole-stg
        aws-region: ap-northeast-1
        role-session-name: GitHubActions

    - name: Login to Amazon ECR
      uses: aws-actions/amazon-ecr-login@v1

The key points are:

Adding the following configuration allows GitHub Actions to automatically generate JWT:

permissions:
  id-token: write
  contents: read

Here we specify the ARN of the previously defined Role.
This allows you to obtain access tokens for this role after authentication is complete.

    - uses: aws-actions/configure-aws-credentials@v4
      with:
        role-to-assume: arn:aws:iam::(your account id):role/EcsTaskRole-stg
        aws-region: ap-northeast-1
        role-session-name: GitHubActions

3. Job Execution

Then verify that it works.

Summary

In this article, I explained how to securely assume IAM Roles using OIDC (OpenID Connect) when accessing AWS resources from GitHub Actions.

The traditional method of directly registering secret keys (AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY) in GitHub secrets carries the risk of key leakage, so using OIDC enables safer operations.

Benefits of Using OIDC

• No secret keys needed → Eliminates leakage risk
• Issues temporary credentials only valid during job execution → Complies with the principle of least privilege
• Restricts IAM Role scope at the repository level → Prevents unnecessary access

OIDC Configuration Steps

1. Create an IAM OIDC ID provider (AWS trusts GitHub’s OIDC)
2. Create an IAM Role and allow AssumeRole with OIDC (restricting repositories)
3. Add OIDC settings to GitHub Actions workflow (grant id-token permission)
4. Securely access AWS resources (obtain credentials during job execution)

Thank you for reading this far.