Customize GitHub Actions OIDC Claim for AWS IAM Authentication

OIDC subject claim

GitHub Actions OIDC token contains useful claims that you can check in Understanding the OIDC token. But AWS only supports what’s included in sub claim and cannot use any other claims in the token. Example subject claims such as branch, pull_request, and environment.

The default subject claim is very limited and if we want to have more granular permissions i.e check the workflow name or the actor we need to customize the subject claim and Set the customization template.

Customize subject claim at the Organization level

To customize the sub claim, we have included it below.

Before we apply custom claims at an organizational level, we can apply to a single repo to play with.

curl \
  -X PUT \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer xxxxxxxxxx" \
  https://api.github.com/orgs/myorg/actions/oidc/customization/sub \
  -d '{"include_claim_keys":["repo","context","event_name","ref","workflow","job_workflow_ref","actor"]}'

More details on this request at https://docs.github.com/en/enterprise-cloud@latest/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-an-organization

Updating repositories to use the modified claim

We need to run this in all the repositories under the org that would authenticate with AWS.

curl \
  -X PUT \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer xxxxxxxxxx" \
  https://api.github.com/repos/myorg/myrepo/actions/oidc/customization/sub \
  -d '{"use_default":false}'

Here we set false to the default claim used in the repo.

Using claim

When using the claim in trust policy, we should maintain the order as we updated above. i.e

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Federated": "arn:aws:iam::111111111111:oidc-provider/token.actions.githubusercontent.com"
            },
            "Action": "sts:AssumeRoleWithWebIdentity",
            "Condition": {
                "StringLike": {
                    "token.actions.githubusercontent.com:sub": "repo:myorg/myrepo:*:event_name:push:ref:refs/heads/main:ref_type:*:workflow:GitHub actions OIDC test:job_workflow_ref:*:actor:irfadrazick",
                    "token.actions.githubusercontent.com:aud": "sts.amazonaws.com"
                }
            }
        }
    ]
}

We’ve used StringLike so we can put * if we want to skip some keys.

Few examples

When pushing against a branch test-branch

"repo:myorg/myrepo:environment:uat:event_name:push:ref:refs/heads/test-branch:*"

For pull requests

"repo:myorg/myrepo:*:event_name:pull_request:*"