AWS Learning Journey

Delete Your AWS Access Keys: How OIDC and Federation Replace Them

Your CI pipeline doesn't need a password. It needs an identity. Here's how federation lets GitHub Actions, your team, and your apps get AWS access without storing a single long-term key.

10 min read · 1867 words
AWSGitHub ActionsDevSecOpsCloud SecurityOpenID Connect
Delete Your AWS Access Keys: How OIDC and Federation Replace Them cover image

AWS from Zero to Production — Phase 2, Part 3 of 6 · See the full series roadmap


Here’s how most teams first connect GitHub Actions to AWS:

  1. Create an IAM user called github-deployer.
  2. Generate an access key.
  3. Paste it into GitHub as AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY.
  4. Forget about it.

That key never expires. It’s copied into every fork’s settings someone configures, every log that accidentally prints environment variables, and every laptop where someone tested the workflow locally. Rotating it means updating every repository that uses it — so nobody does.

There’s a better model: federation. Instead of giving GitHub a secret, you teach AWS to trust GitHub’s identity. Each workflow run proves who it is, receives credentials that last minutes, and leaves nothing behind to steal.

What you’ll walk away with


Federation in one sentence

Federation means AWS trusts an external identity provider (IdP) to vouch for who someone is — and exchanges that proof for temporary AWS credentials.

External identity          AWS
-----------------          ---
"I am X" (signed token) --> STS checks the signature and the role's trust policy
                        <-- temporary credentials for the role (minutes to hours)

Nothing long-lived is stored on the caller’s side. The trust is configured once, in AWS, and every session proves itself fresh.


Three kinds of federation

SAML 2.0 — for your workforce

SAML is an XML-based standard used by corporate identity providers such as Microsoft Entra ID, Okta, and Google Workspace.

Engineer’s note: Today, most organizations connect their corporate IdP to IAM Identity Center rather than configuring SAML directly on IAM in every account. Identity Center then handles access to all accounts through permission sets — exactly what you used in Phase 1.

OpenID Connect (OIDC) — for workloads and apps

OIDC is a modern, JSON-based identity layer built on OAuth 2.0. An OIDC provider issues a signed JSON Web Token (JWT) that contains claims — facts about the identity, such as which repository a workflow runs in.

AWS exchanges a valid JWT for a role session through AssumeRoleWithWebIdentity.

Common OIDC providers for AWS:

Web identity federation — for end-user apps

Mobile and web apps can let users sign in with providers like Google or Apple, then call AWS directly with temporary credentials.

Engineer’s note: For customer-facing apps, use Amazon Cognito instead of wiring identity providers directly to IAM. Cognito handles user pools, token exchange, and scoping far more safely.


How GitHub Actions authenticates to AWS with OIDC

This is the pattern you’ll build in Part 6.

The flow

1. Workflow job starts (with permission: id-token: write)
2. GitHub's OIDC provider issues a short-lived JWT for this job
       claims include: repository, branch or environment, workflow, run ID
3. The aws-actions/configure-aws-credentials action sends the JWT to AWS STS
       (AssumeRoleWithWebIdentity)
4. STS checks:
       - Is the token signed by a provider registered in IAM?
       - Does the token's audience match?
       - Does the role's trust policy allow these claims?
5. STS returns temporary credentials (typically valid for one hour)
6. The job uses them, finishes, and the credentials expire

What you configure in AWS

1. An IAM OIDC identity provider — once per account:

aws iam create-open-id-connect-provider \
  --url https://token.actions.githubusercontent.com \
  --client-id-list sts.amazonaws.com

No thumbprint needed. Older tutorials tell you to calculate and enter a certificate thumbprint. AWS now verifies GitHub’s endpoint using its library of trusted certificate authorities, so the thumbprint isn’t necessary — and if you specify one, AWS ignores it for providers like GitHub.

2. An IAM role with a trust policy that allows the GitHub provider — with conditions.

What you configure in GitHub

In the workflow:

permissions:
  id-token: write   # allows the job to request an OIDC token
  contents: read

steps:
  - uses: aws-actions/configure-aws-credentials@v6
    with:
      role-to-assume: arn:aws:iam::111122223333:role/github-deploy
      aws-region: eu-west-1

That’s it. No AWS_ACCESS_KEY_ID. No secrets.


Claims: how you restrict which workflows get in

A trust policy without conditions would let any GitHub repository in the world assume your role. Conditions on the token’s claims prevent that.

The two claims that matter most

sub formats

The subject depends on how the job runs:

Branch:       repo:my-org/my-repo:ref:refs/heads/main
Tag:          repo:my-org/my-repo:ref:refs/tags/v1.2.0
Environment:  repo:my-org/my-repo:environment:production
Pull request: repo:my-org/my-repo:pull_request

Important: When a job specifies a GitHub environment, the sub claim uses the environment form — not the branch form. A trust policy that only allows ref:refs/heads/main will reject a job running in the production environment, even on main.

⚠️ The 2026 change: immutable subject claims

Repositories created on GitHub on or after 15 July 2026 — and older repositories that opt in or are renamed after that date — emit an immutable sub claim. It adds the permanent numeric IDs of the organization and repository:

Legacy:     repo:my-org/my-repo:environment:production
Immutable:  repo:my-org@123456/my-repo@789012:environment:production

Why? If an organization or repository is deleted and someone else later claims the same name, a name-only trust policy could accept their tokens. Numeric IDs can’t be recycled.

What this means for you:

Example: allow only the production environment of one repository

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "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@123456/my-repo@789012:environment:production"
        }
      }
    }
  ]
}

Patterns to avoid

Engineer’s note: Wildcards aren’t always wrong — repo:my-org/my-repo:ref:refs/heads/release/* is a reasonable way to allow release branches. The danger is wildcards in the organization or repository part of the claim.


Environment-based trust: the production gate

GitHub environments let you add protection rules, such as required reviewers or wait timers, before a job can run in that environment.

Combine them with environment-based trust policies:

Now production credentials can only be issued to a job that someone approved. Even a compromised branch can’t reach production without that approval.

Note: Environment protection rules such as required reviewers are available for public repositories and for private repositories on eligible paid GitHub plans. Check GitHub’s current plan details.


The same idea for people: CLI and Identity Center

Federation isn’t just for pipelines. You’ve been using it since Phase 1:

The principle is identical: prove who you are, get short-lived credentials, never store a long-term secret.


Temporary credentials everywhere

Here’s how each kind of caller should get AWS credentials:


Finding and removing long-lived access keys

If you already have access keys in use, here’s a practical cleanup plan:

  1. Inventory. Generate an IAM credential report (Part 2) and list every active access key, its age, and when it was last used.
  2. Find the callers. Use the “last used” service and Region, plus CloudTrail, to see what each key does.
  3. Replace. Move each caller to a role: OIDC for CI, instance profiles or task roles for workloads, Identity Center for people.
  4. Deactivate, then delete. Deactivate the key first and watch for errors for a few days. If nothing breaks, delete it.
  5. Prevent new ones. Add secret scanning to your repositories, and consider an SCP or IAM policy that restricts iam:CreateAccessKey to a small admin group.

Common mistakes


Key takeaways


Quick self-check

Test yourself before moving on:

  1. Which workflow permission must be set for GitHub Actions to request an OIDC token?
  2. A job runs on main with environment: production. Which sub form does its token use?
  3. Your trust policy matches repo:my-org/my-repo:environment:production, but a brand-new repository fails to assume the role. What’s the likely cause?
  4. Why is StringLike with repo:my-org/* dangerous?

Answers

  1. id-token: write.
  2. The environment form: repo:my-org/my-repo:environment:production (or the immutable equivalent).
  3. Repositories created on or after 15 July 2026 emit the immutable sub claim with numeric IDs, such as repo:my-org@123456/my-repo@789012:....
  4. It lets every repository in the organization — including future ones — assume the role.

What’s next

In Part 4, we protect the data itself: encryption at rest and in transit, AWS KMS, and where your application’s passwords and API keys should actually live.

Are you still using access keys in CI? What’s stopping the switch to OIDC? Share it in the comments.


Share this article

LinkedIn post draft