AWS STS: Validate OIDC provider claims from GitHub, Google, CircleCI, and OCI

AWS announced an update to AWS Security Token Service (STS): you can now validate select identity-provider-specific JWT claims from Google, GitHub, CircleCI, and Oracle Cloud Infrastructure (OCI) when you use AssumeRoleWithWebIdentity. This matters because it makes it easier to write tight IAM trust policies for OIDC-based federation (CI/CD, workload identity) without relying on overly broad patterns.

Source: AWS announcement

Why this is useful Link to heading

If you already use OIDC federation, you’ve probably done at least one of these:

• Restricted access with a single sub pattern and hoped it was specific enough.
• Used repository names or branch names that are easy to change.
• Accepted “any workflow in this org can assume the role” because the policy became too complex.

Provider-specific claim keys let you express intent more clearly: “only this repo (by immutable ID)”, “only this enterprise”, “only this workflow”, “only this actor”.

Example: GitHub Actions trust policy conditions Link to heading

For GitHub Actions, AWS supports condition keys that map to common GitHub OIDC claims.

Note on “available in session”: these claim checks are evaluated during the role assumption step (trust policy). They are not automatically materialized as attributes you can later reference inside the role’s permission policies.

Practical patterns Link to heading

• token.actions.githubusercontent.com:actor: identify who triggered the workflow. For example, if the actor is dependabot[bot], you may allow only read-only access.
• token.actions.githubusercontent.com:repository_id: prefer immutable IDs over names to avoid “rename to bypass policy” scenarios.
• token.actions.githubusercontent.com:enterprise_id: ensure only workflows from your GitHub Enterprise can assume the role.

IAM trust policy snippet (GitHub Actions) Link to heading

This is the kind of policy shape I like: keep the trust policy strict, and keep permissions scoped to the minimum required actions.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": { "Federated": "arn:aws:iam::123456789012:oidc-provider/token.actions.githubusercontent.com" },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "token.actions.githubusercontent.com:aud": "sts.amazonaws.com",
          "token.actions.githubusercontent.com:repository_id": "123456789",
          "token.actions.githubusercontent.com:enterprise_id": "987654321"
        },
        "StringLike": {
          "token.actions.githubusercontent.com:ref": "refs/heads/main",
          "token.actions.githubusercontent.com:job_workflow_ref": "my-org/my-repo/.github/workflows/deploy.yml@refs/heads/main"
        }
      }
    }
  ]
}

Quick guidance Link to heading

• Prefer immutable identifiers (repository_id, enterprise_id) over names where possible.
• Treat the trust policy as your “admission control”: keep it as narrow as you can.
• Don’t rely on the OIDC federation session to “carry” these claims; if you need richer audit context, plan for it explicitly (CloudTrail, additional logging, or separate roles per workflow).