DEV Community

David Nanjila
David Nanjila

Posted on

Troubleshooting GitHub Actions to AWS OIDC Authentication

 cover image

A practical guide to fixing AWS IAM role assumption failures in GitHub Actions

Introduction

One of the things I appreciate about working with cloud technologies is that troubleshooting often teaches you more than simply getting something to work.

While configuring a GitHub Actions workflow to authenticate with AWS using OpenID Connect (OIDC), I encountered an authentication failure that took some investigation to resolve.

My initial configuration appeared correct. I had configured an AWS IAM OIDC identity provider, created an IAM role with a trust policy, and set up the GitHub Actions workflow with the required permissions.

However, GitHub Actions could not assume the IAM role.

After investigating the issue, I discovered that the problem was not with the AWS credentials or the workflow itself. It was a mismatch between the OIDC sub (subject) claim issued by GitHub and the subject value configured in the AWS IAM role's trust policy.

The root cause was GitHub's newer immutable subject claim format.

In this article, I’ll walk through the issue, explain why it happened, and demonstrate how to fix it.

1. Understanding GitHub Actions OIDC authentication

Github OICD authentication flow
Before looking at the error, let's briefly understand how GitHub Actions authenticates with AWS using OIDC.

Traditionally, developers stored AWS access keys and secret access keys as GitHub repository secrets. Workflows then used these long-lived credentials to authenticate with AWS.

OIDC provides a different approach.

Instead of storing long-lived AWS credentials in GitHub, GitHub Actions requests a short-lived OIDC token. AWS validates that token against its configured identity provider and the trust policy of the IAM role being assumed.

The process looks like this:

  1. A GitHub Actions workflow starts.
  2. GitHub issues an OIDC token to the workflow.
  3. The workflow presents the token to AWS Security Token Service (STS).
  4. AWS validates the token's issuer, audience, and subject against the IAM role's trust policy.
  5. If the conditions match, AWS issues temporary credentials.

This approach reduces the need to manage long-lived AWS credentials in CI/CD pipelines.

2. The initial configuration

I was working with a GitHub repository named express-app under the stoicdavi account.

On the AWS side, I had already configured:

  • An IAM OIDC identity provider for token.actions.githubusercontent.com.
  • An IAM role named github-express-deploy.
  • A trust policy allowing GitHub Actions to assume the role.
  • A GitHub repository variable containing the IAM role ARN.

The original trust policy used the traditional GitHub subject format:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::<AWS_ACCOUNT_ID>:oidc-provider/token.actions.githubusercontent.com"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "token.actions.githubusercontent.com:aud": "sts.amazonaws.com",
          "token.actions.githubusercontent.com:sub": "repo:stoicdavi/express-app:ref:refs/heads/main"
        }
      }
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

The important part is the sub condition:

"token.actions.githubusercontent.com:sub": "repo:stoicdavi/express-app:ref:refs/heads/main"
Enter fullscreen mode Exit fullscreen mode

This tells AWS to trust tokens originating from the specified repository and branch.

The configuration looked reasonable, but authentication was still failing.

3. Investigating the authentication failure

Rather than immediately changing permissions or recreating the IAM role, I went back to the identity being presented by GitHub.

The important question became:

What subject claim was GitHub actually issuing, and did it match the value AWS expected?

This led me to investigate GitHub's documentation on OIDC subject claims.

I discovered that GitHub had introduced a newer immutable subject claim format.

Repositories created after July 15, 2026 automatically use this format. It includes immutable owner and repository IDs alongside their names.

The older format looks like this:

repo:OWNER/REPOSITORY:ref:refs/heads/BRANCH
Enter fullscreen mode Exit fullscreen mode

The newer immutable format looks like this:

repo:OWNER@OWNER_ID/REPOSITORY@REPOSITORY_ID:ref:refs/heads/BRANCH
Enter fullscreen mode Exit fullscreen mode

The subject claim formats

This change improves security because repository and owner names can change or be reused, while their numeric IDs are immutable.

My repository had been created after the July 15, 2026 rollout. Consequently, GitHub was issuing a subject claim containing the owner and repository IDs, while my AWS trust policy was expecting the older name-only format.

The two values did not match, so AWS rejected the role assumption.

That was the root cause.

4. Fixing the AWS IAM trust policy

Once I understood the mismatch, the solution became straightforward.

I needed to update the sub condition in my AWS IAM role's trust policy to match the immutable subject claim GitHub was issuing.

However, before updating the policy, I needed to obtain two important values:

  • GitHub owner ID: The permanent numeric ID of the GitHub user or organization that owns the repository.
  • GitHub repository ID: The permanent numeric ID assigned to the repository.

For this example, I was working with the repository stoicdavi/express-app.

There are several ways to retrieve these IDs.

4.1 Getting the GitHub owner ID and repository ID

You can retrieve these values using the GitHub CLI, the GitHub REST API, or directly through the GitHub web interface.

Option 1: Using GitHub CLI (Terminal)

If you have GitHub CLI installed, you can retrieve both IDs with a single command.

First, authenticate with GitHub if you haven't already:

gh auth login
Enter fullscreen mode Exit fullscreen mode

Next, execute:

gh api repos/stoicdavi/express-app \
  --jq '{owner_id: .owner.id, repository_id: .id}'
Enter fullscreen mode Exit fullscreen mode

The command returns something similar to:

{
  "owner_id": 123456,
  "repository_id": 789012
}
Enter fullscreen mode Exit fullscreen mode

These are example values. Replace them with the actual IDs returned for your repository.

If you only want to retrieve the owner ID separately, you can run:

gh api users/stoicdavi --jq .id
Enter fullscreen mode Exit fullscreen mode

And to retrieve the repository ID:

gh api repos/stoicdavi/express-app --jq .id
Enter fullscreen mode Exit fullscreen mode

What if the repository belongs to an organization?

In that case, use the organization endpoint to retrieve its ID:

gh api orgs/ORGANIZATION_NAME --jq .id
Enter fullscreen mode Exit fullscreen mode

The repository command also returns the owner's ID through .owner.id, regardless of whether the owner is an individual or an organization.

Option 2: Using the GitHub REST API through your browser

You don't necessarily need GitHub CLI installed to retrieve these values.

GitHub exposes the information through its REST API, and you can access it directly from your browser.

To retrieve the GitHub user ID:

Open the following URL, replacing USERNAME with your GitHub username:

https://api.github.com/users/USERNAME
Enter fullscreen mode Exit fullscreen mode

For my example:

https://api.github.com/users/stoicdavi
Enter fullscreen mode Exit fullscreen mode

GitHub returns a JSON response containing information about the account.

Look for the id field:

{
  "login": "stoicdavi",
  "id": 123456,
  "type": "User"
}
Enter fullscreen mode Exit fullscreen mode

The value of id is the GitHub owner ID.

For an organization, use:

https://api.github.com/orgs/ORGANIZATION_NAME
Enter fullscreen mode Exit fullscreen mode

To retrieve the repository ID:

Open:

https://api.github.com/repos/OWNER/REPOSITORY
Enter fullscreen mode Exit fullscreen mode

For my example:

https://api.github.com/repos/stoicdavi/express-app
Enter fullscreen mode Exit fullscreen mode

Look for the following fields in the JSON response:

{
  "id": 789012,
  "name": "express-app",
  "owner": {
    "login": "stoicdavi",
    "id": 123456
  }
}
Enter fullscreen mode Exit fullscreen mode

Here:

  • owner.id represents the GitHub account or organization ID.
  • id represents the repository ID.

These are example values, not the actual IDs of my repository.

Option 3: Navigating through the GitHub interface

GitHub also provides an OIDC configuration page where you can inspect the subject claim associated with your repository.

To access it:

  1. Open your repository on GitHub.
  2. Navigate to the repository's Settings.
  3. Find the Actions OIDC configuration section.
  4. Open the OIDC configuration page.
  5. Inspect the subject claim preview.

You can also access the page directly using this URL structure:

https://github.com/OWNER/REPOSITORY/settings/actions/oidc-configuration
Enter fullscreen mode Exit fullscreen mode

Replace OWNER and REPOSITORY with your actual GitHub account and repository names.

This is particularly useful because it allows you to inspect the subject claim GitHub is configured to issue without manually constructing it.

4.2 Updating the AWS IAM trust policy

After retrieving the owner ID and repository ID, I could construct the immutable subject claim.

The new format follows this structure:

repo:OWNER@OWNER_ID/REPOSITORY@REPOSITORY_ID:ref:refs/heads/BRANCH
Enter fullscreen mode Exit fullscreen mode

For my example, the subject claim would look like this:

repo:stoicdavi@123456/express-app@789012:ref:refs/heads/main
Enter fullscreen mode Exit fullscreen mode

Remember to replace the example IDs with the actual values retrieved from GitHub.

Next, I navigated to the AWS Management Console:

  1. Open the AWS Management Console.
  2. Navigate to IAM.
  3. Select Roles.
  4. Open the github-express-deploy role.
  5. Select Trust relationships.
  6. Click Edit trust policy.

I then updated the sub condition to use the immutable subject claim.

The updated trust policy looks like this:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::<AWS_ACCOUNT_ID>:oidc-provider/token.actions.githubusercontent.com"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "token.actions.githubusercontent.com:aud": "sts.amazonaws.com",
          "token.actions.githubusercontent.com:sub": "repo:stoicdavi@123456/express-app@789012:ref:refs/heads/main"
        }
      }
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Replace the placeholders with your actual AWS account ID and GitHub identifiers.

The important change is the sub condition. It now matches the immutable subject claim rather than the older name-only format.

After making the changes, save the updated trust policy.

4.3 Important things to remember

Before moving on, keep these points in mind:

  • Ensure that the owner ID and repository ID match the actual GitHub account and repository.
  • Make sure the branch in the subject claim matches the branch configured in your workflow.
  • Keep the audience set to sts.amazonaws.com when using the standard AWS OIDC configuration.
  • Do not use unrestricted wildcards in your trust policy.
  • Never expose your OIDC token or AWS credentials in workflow logs.
  • Check the OIDC configuration page if you are unsure which subject format your repository currently uses.

One important detail: Repositories created before July 15, 2026 generally retain the older subject format unless they opt in to immutable subject claims or undergo changes such as a rename or transfer that trigger the new format. Therefore, always verify the actual subject claim before changing your trust policy.

Once the trust policy matches the subject claim GitHub issues, the workflow should be able to assume the IAM role, provided the remaining OIDC configuration and permissions are correct.

5. Configure the AWS_ROLE_ARN Variable in GitHub

Before running the workflow again, there is one more important configuration we need to verify.

GitHub Actions needs to know which AWS IAM role it should assume when requesting temporary credentials through OIDC.

To achieve this, we need to add the AWS IAM Role ARN to our GitHub repository as an Actions variable.

5.1 Retrieve your AWS IAM Role ARN

First, navigate to the AWS Management Console:

  1. Open IAM.
  2. Select Roles from the left navigation menu.
  3. Search for the IAM role you created for GitHub Actions (in my case, github-express-deploy).
  4. Open the role.
  5. Under the Summary section, locate ARN.
  6. Copy the ARN.

It should look similar to this:

arn:aws:iam::123456789012:role/github-express-deploy
Enter fullscreen mode Exit fullscreen mode

This is the value we will add to GitHub.

5.2 Add AWS_ROLE_ARN to GitHub Actions Variables

Now navigate to your GitHub repository.

Follow these steps:

  1. Open your GitHub repository.
  2. Click Settings.
  3. On the left sidebar, locate Secrets and variables.
  4. Expand the section and select Actions.
  5. Select the Variables tab.
  6. Click New repository variable.

You will be presented with two fields.

Fill them in as follows:

Field Value
Name AWS_ROLE_ARN
Value arn:aws:iam::123456789012:role/github-express-deploy

Replace the example ARN with the actual ARN you copied from AWS.

Click Add variable to save it.

Why use a variable instead of a secret?

An IAM Role ARN is an identifier, not an AWS access key or password. Therefore, storing it as a GitHub Actions variable is perfectly reasonable.

We are not storing long-lived AWS access keys in GitHub. OIDC will allow AWS to issue temporary credentials when the workflow runs.

Here is an example of the workflow configuration:

name: Test AWS authentication

on:
  push:
    branches:
      - main

permissions:
  id-token: write
  contents: read

jobs:
  authenticate:
    runs-on: ubuntu-latest

    steps:
      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v6
        with:
          role-to-assume: ${{ vars.AWS_ROLE_ARN }}
          aws-region: us-east-1

      - name: Verify AWS identity
        run: aws sts get-caller-identity
Enter fullscreen mode Exit fullscreen mode

Let's briefly understand two important configurations here:

1. id-token: write

This permission allows the GitHub Actions workflow to request an OIDC token from Github.

Without it, the workflow cannot request the identity token required for AWS federation.

2. role-to-assume: ${{ vars.AWS_ROLE_ARN }}

This tells the AWS credentials action which IAM role to assume.

Instead of hardcoding the role ARN in the workflow, we reference the repository variable we created earlier.

5.4 Important: Verify your configuration before running the workflow

Before triggering the workflow, double-check the following:

  • The AWS_ROLE_ARN variable exists in your GitHub repository.
  • The variable contains the correct IAM role ARN.
  • The workflow has id-token: write permission.
  • The AWS IAM role has the correct GitHub OIDC provider configured.
  • The IAM trust policy matches the immutable subject claim GitHub issues.
  • The AWS region is configured correctly.

With these configurations in place, we are ready to test the authentication flow.

In the next step, we will trigger the GitHub Actions workflow and verify that it can successfully assume the AWS IAM role without requiring long-lived AWS access keys.

6. The result

After updating the AWS IAM trust policy with the correct immutable subject claim, I reran the GitHub Actions workflow.

Authentication succeeded.

The workflow was able to assume the IAM role, and aws sts get-caller-identity returned the expected AWS identity.

This confirmed that the issue was the mismatch between GitHub's issued subject claim and the AWS trust policy.

7. Lessons learned

This troubleshooting experience reinforced a few important lessons:

  1. Do not assume the old OIDC subject format is still being used. GitHub's immutable subject claims affect new repositories and repositories that opt in to the new format.
  2. Inspect the identity being presented. When authentication fails, compare the actual token claims with the conditions in the cloud provider's trust policy.
  3. Understand the trust relationship. A valid OIDC identity provider does not automatically mean every token from that provider is trusted. The IAM role's trust policy determines which identities can assume it.
  4. Use least privilege. Restrict role assumption to the intended repository and branch instead of using broad wildcard conditions.
  5. Verify before moving on. A successful aws sts get-caller-identity call is a useful confirmation that the workflow has authenticated successfully.

Conclusion

What initially looked like a generic AWS authentication problem turned out to be a mismatch in the OIDC subject claim format.

If you're configuring GitHub Actions to authenticate with AWS and encounter a role assumption failure, check the sub claim before spending too much time changing permissions or recreating resources.

Your AWS trust policy must match the subject claim GitHub actually issues.

I hope documenting this experience helps another developer avoid spending unnecessary time troubleshooting the same issue.


Further reading

Top comments (0)