I'm migrating GitHub Actions deployments to AWS from long-lived IAM credentials to short-lived OIDC-based access, primarily for ECS deployments. OIDC lets a workflow request a temporary JWT and exchange it with AWS STS for credentials that usually last 15–60 minutes, without storing AWS secrets in the repository.
The basic setup involves creating an AWS IAM OIDC provider, an IAM role with a trust policy that validates the token audience and repository subject, and a workflow job with `id-token: write` permission. The workflow can then use `aws-actions/configure-aws-credentials` to assume the role and verify access with `aws sts get-caller-identity`.
Some details have caused confusion: the `sub` claim is case-sensitive, job-level permissions may be safer than relying on workflow defaults, repository renames can change subject-claim formats, and a condition such as `repo:org/repo:*` permits any branch, tag, or pull-request context in that repository. Production roles should usually be restricted to a specific branch or, preferably, a protected GitHub Environment.
I'm also interested in how others handle certificate thumbprints, reusable workflows, and cross-account deployments. Do you register the OIDC provider in every AWS account, or use a central account and role chaining?
5 Answers
Repository renames can be a surprising failure point. Newer subject-claim formats can include immutable organization or repository identifiers, while older repositories may still use the traditional `repo:org/repo:...` form during migration. If one repository suddenly stops authenticating, inspect the failed STS request and CloudTrail details to see the exact `sub` value, then update the trust policy to support the intended old or new format rather than blindly broadening it.
Adding `role-session-name` makes the audit trail much more useful. For example, combining the job name and run ID lets CloudTrail identify the exact workflow execution instead of showing only that the role was used by the repository. That makes incident review and troubleshooting considerably easier.
The certificate-thumbprint advice deserves verification against current AWS behavior. AWS IAM can validate this provider using its trusted CA handling, and some current configurations no longer need manually maintained thumbprints. Hard-coding values that AWS treats as computed can create needless Terraform drift, so check the provider resource behavior and current AWS documentation before adding or maintaining them.
For multiple AWS accounts, a central OIDC provider can work well. The workflow first assumes a role in a tooling account through OIDC, then that role uses `sts:AssumeRole` into narrowly scoped roles in the target accounts. Smaller installations may simply register the provider in each account, but the hub-and-spoke approach keeps identity configuration centralized and avoids falling back to permanent access keys.
Be careful with the trust-policy wildcard. `repo:org/repo:*` limits access to the repository, but it still allows every branch, tag, and other supported subject in that repository. For production, use a subject such as `repo:org/repo:ref:refs/heads/main`, or scope the role to a protected environment such as `repo:org/repo:environment:production`. Reusable workflows can also affect which repository appears in the subject, so test the actual token claims rather than assuming they match a direct workflow.
Environment-based restrictions have worked well for us because branch protection and deployment approvals can be enforced separately from the IAM policy.