A GitHub Actions workflow must deploy to AWS with no access keys stored as repository secrets. How do you set that up with an IAM OIDC identity provider, and which condition must the role's trust policy contain?

## What problem this solves The traditional pattern is an IAM user with access keys pasted into GitHub repository secrets. Those keys never expire, they are readable by anyone who can add a workflow to the repository, and they survive long after the person who created them leaves. OIDC federation removes the stored secret entirely: GitHub signs a short-lived JSON Web Token asserting facts about the running job, and AWS trades that token for a temporary session. ## The three pieces **1. The identity provider object.** In IAM you register the issuer `https://token.actions.githubusercontent.com` as an OIDC identity provider with the client ID (audience) `sts.amazonaws.com`. This is a one-off per account. It tells IAM that tokens signed by GitHub's keys, for that audience, are worth evaluating. **2. The role and its trust policy.** The role holds the deployment permissions in its identity policy, and its trust policy decides who may assume it: ```json { "Effect": "Allow", "Principal": { "Federated": "arn:aws:iam::111122223333: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:my-org/my-repo:ref:refs/heads/main" } } } ``` The condition keys are the OIDC issuer's hostname followed by a colon and the claim name — that syntax is how AWS exposes web-identity token claims to policy. **3. The workflow side.** The job needs `permissions: id-token: write` (this is a GitHub permission to *request* a token, nothing to do with AWS), and typically uses the `aws-actions/configure-aws-credentials` action with `role-to-assume` and `aws-region`. The action requests the token, calls `AssumeRoleWithWebIdentity`, and exports temporary credentials into the job's environment for every later step. ## The sub claim is where the security lives The `aud` claim proves the token was minted for AWS. It proves nothing about *whose* workflow produced it, because every GitHub OIDC token for AWS carries the same audience. A trust policy that checks only `aud` is trusted by every repository on GitHub — anyone can push a workflow that assumes your role and takes your deployment permissions. The `sub` claim carries the identity that matters, in a structured form: - `repo:my-org/my-repo:ref:refs/heads/main` — a push or run on that branch - `repo:my-org/my-repo:ref:refs/tags/v1.2.3` — a tag - `repo:my-org/my-repo:pull_request` — a pull-request event - `repo:my-org/my-repo:environment:production` — a job targeting that GitHub environment The scoping mistakes, in descending order of frequency: 1. **No `sub` condition at all.** Global exposure. 2. **`repo:my-org/*`** with `StringLike`. Any repository in your organisation deploys to production, including a new one created by anyone with repo-create rights. 3. **A trailing wildcard in the wrong place.** `repo:my-org/my-repo*` also matches `my-org/my-repo-fork` and `my-org/my-repo-scratch`. Wildcards belong *after* a colon-delimited segment boundary, as in `repo:my-org/my-repo:*`. 4. **`repo:my-org/my-repo:*`** for a production role. Legitimate for a read-only or plan role; for a deploy role it means a pull request from a fork-triggered workflow, or any branch, can assume it. Pin to the branch, tag pattern, or environment. The strongest pattern for production is the **environment** subject, because GitHub environments carry their own protection rules — required reviewers, branch restrictions, wait timers — so approval and the AWS trust condition reinforce each other. ## Operational notes - **Scope the role's permissions too.** Federation gets rid of the stored key; it does not excuse `AdministratorAccess` on the deploy role. Separate plan/read roles from apply/write roles. - **Set a short `Duration`.** The action supports a role session duration; a deploy rarely needs hours. - **`role-session-name`** shows up in CloudTrail, so set it to something that identifies the workflow run and makes an audit trail readable. - **Multi-account deploys** are cleanest as one role per target account, each with its own narrow trust condition, rather than one hub role that chains outward. - **Self-hosted runners change nothing here** — the token comes from GitHub's issuer regardless of where the job runs. ## The shape of a good answer Describe the three pieces, then spend most of the answer on the `sub` condition and the exposure created by omitting it. An interviewer asking this question is almost always listening for whether you know that `aud` alone is worthless.