## TL;DR
OIDC assume-role fails when the IAM trust policy's `sub` or `aud` conditions do not match the token GitHub mints. Grant `id-token -  write` in the workflow permissions and make the trust policy's subject pattern match your repo, environment, or ref exactly. The role assumption then succeeds.

## Error
```text
github actions oidc failed to assume role for secrets access
```

## Steps
1. Grant the token permission: in the workflow, set `permissions: id-token -  write` (and `contents: read` for checkout). Expected: the OIDC token is minted; without this the assume-role call never starts.
2. Read the trust policy on the IAM role and check the `sub` condition. The subject looks like `repo:ORG/REPO:ref:refs/heads/BRANCH` (or `environment:NAME` when using environments). Expected: you see the exact pattern the role expects.
3. Match the pattern to reality: wildcards must cover the actual ref, and environment-based subjects only match jobs that declare that environment. Expected: the token's subject satisfies the condition.
4. Check the audience: the trust policy usually expects `aud` of `sts.amazonaws.com`. Expected: the audience matches; a custom audience on either side breaks it.
5. Re-run the workflow and watch the assume-role step. Expected: temporary credentials are issued and subsequent secret reads succeed.

## When to use
- `configure-aws-credentials` or manual OIDC assume-role fails in Actions
- Moving from static keys to OIDC and hitting trust errors
- New branch, tag, or environment that the trust policy does not cover

## When not to use
- Static access-key failures (credential problem, not OIDC)
- The role assumes fine but secret reads are denied (IAM action permissions)

## Tool compatibility
- GitHub Actions OIDC, AWS IAM roles with web-identity trust policies

## Variant phrasings
### oidc subject claim mismatch github actions
Print the expected subject format for your trigger (branch, tag, PR, environment) and align the trust policy's `sub` condition.

### id-token write missing
Without `permissions: id-token -  write`, GitHub never mints the token and every OIDC step fails.

## Why it happens
OIDC replaces stored keys with a short-lived token whose claims describe the workflow. IAM evaluates those claims against the trust policy literally, so a policy written for `main` rejects a token minted for a feature branch, and a job without the token permission mints nothing at all.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_xtfM5BitVfUuQ3B5wzcoSQ