Workload Identity Federation: How to Replace Long-Lived Credentials Without Creating New Trust Risks

A deployment job stores a cloud access key in its CI/CD secret store. A Kubernetes worker mounts a cloud service-account key. A backend integration shares a client secret with two other services. In each case, workload identity federation can remove the reusable secret by exchanging an identity the workload already has for short-lived access.

That exchange changes the security boundary rather than eliminating it. Access now depends on which issuer the target trusts, which token claims identify the workload, and which permissions the resulting principal receives. This guide explains how to make those decisions, migrate with controlled overlap, and produce enough evidence to revoke the old credential.

Key takeaways

Copy link

• Federate only from an identity source that can reliably distinguish the intended workload from other tenants, environments, and jobs.
• Restrict the issuer, audience, subject, and other authoritative claims before mapping resource permissions.
• Treat the trust policy and permissions policy as independent controls: one decides who can obtain access, while the other decides what that identity can do.
• Define migration completion before rollout, then revoke the replaced static credential when its expected usage reaches zero.

Decide whether federation fits the workload

Copy link

Workload identity is the identity assigned to software such as a job, service, container, or virtual machine. Workload identity federation is the trust mechanism that lets an identity from one security domain obtain access in another. It commonly relies on a signed platform assertion and a security token service (STS), but it does not remove credentials as a class. The workload still handles an assertion and a short-lived token.

Federation fits when a platform-issued identity can distinguish the workload, the target supports token exchange, acquisition and renewal need no human login, and permissions can be expressed separately.

The identity source is the first test. A Kubernetes service account dedicated to one application, a protected CI environment, or a cloud instance identity can be useful sources. A shared runner label, a repository name that can be transferred, or an attribute any developer can edit is not equivalent evidence. Ask who can cause the issuer to produce the accepted claims and whether the identifier can be renamed, reused, or reassigned.

Federation is not always the shortest or safest path. If the workload and resource share a native cloud identity system, a managed identity may provide short-lived access without an external federation boundary. If a legacy API accepts only an API key, federation cannot change the target's authentication contract; the practical control remains managed secret storage, rotation, and monitoring. Human access belongs in workforce IAM or SSO because a person has different lifecycle, authentication, and accountability requirements.

Choose the authentication pattern

Copy link

For each candidate, run a negative test before selecting federation: can another repository, namespace, tenant, branch, or service account produce a token that matches the proposed rule? If the answer is unknown, the identity design is not ready. If the answer is yes, narrow the claims or choose a different identity source.

Define the trust boundary before mapping access

Copy link

The new boundary is the set of conditions under which the target accepts an external assertion. It should answer one concrete question: which exact workload is allowed to exchange which exact platform-issued credential for access to this target?

Start with the issuer. The issuer identifies the authority that signs and describes the assertion. With a multi-tenant issuer, trusting its URL alone says little about which organization or tenant produced a token. Add an authoritative organization, tenant, account, or project condition that excludes neighboring customers.

Then restrict the audience. The audience indicates where the assertion is intended to be used. The current IETF Workload Identity Practices draft recommends narrowly scoped audiences and a separate credential for an external STS rather than reusing a credential intended for an internal platform resource. An audience check limits token substitution across relying parties; it is not a substitute for identifying the workload.

The subject and mapped attributes carry that identity. Prefer values that are unique, stable, authoritative, and non-reusable. A display name may change. A repository or namespace name may be deleted and claimed again. A branch claim may be meaningful only if the platform prevents untrusted actors from updating that branch. Google Cloud's WIF security guidance documents how ambiguous mappings and subject collisions can make different external identities indistinguishable, including in audit logs.

Production and non-production also need explicit separation. A single trust mapping for every environment lets compromise or configuration error cross the most consequential boundary. Prefer distinct subjects, principals, pools, roles, or equivalent controls, depending on the target. Protect changes to the federation configuration separately from the workloads that consume it.

Workload federation trust flow

Copy link

[Workload]
    | identity proof requested
    v
[Platform-issued identity]
    | signed assertion: issuer + audience + subject + attributes
    v
[Trusted issuer] ---- trust decision ----> [Token exchange / STS]
                                               |
                                               | short-lived credential
                                               v
                                      [Federated principal]
                                               |
                                               | authorization decision
                                               v
                                           [Resource]

Review the flow from left to right and record an owner and evidence for each transition. Platform configuration proves how the workload receives its identity. The federation policy proves which assertions the STS accepts. The resource policy proves what the resulting principal may do. A gap at any transition is a gap in the access model.

Separate workload trust from resource permissions

Copy link

A trust policy answers, “Which workload may obtain this identity or temporary credential?” A permissions policy answers, “What may that identity do after authentication?” OWASP's Workload Identity Federation Cheat Sheet treats these as separate controls because precision in one cannot compensate for breadth in the other.

For example, a team can restrict federation to one protected repository and its production deployment environment, then attach an administrative cloud role to the federated principal. The authentication rule is narrow, but any code executing in the authorized job receives excessive authority. Federation does not make a compromised workload trustworthy and does not provide least privilege automatically.

Build the permissions mapping from observed operations rather than the capabilities of the old role. Inventory the resources and actions used by a normal deployment, then test both required and prohibited actions. A deployment identity might need to update one cluster workload and read one artifact registry, but it may not need to create IAM bindings, edit federation providers, or administer every cluster in the account.

Use a dedicated principal or role per workload when practical. Dedicated identities make permission review, incident containment, and attribution easier than a shared federated principal. At minimum, separate production from non-production and prevent ordinary deployment roles from modifying their own trust or permissions. Avoid wildcard mappings that grant an entire workload pool the same role unless every member genuinely shares the same authorization boundary.

Validation needs two sides. Prove that the intended workload can exchange a token and complete its task. Then prove that an unauthorized repository, environment, namespace, or subject cannot exchange one, and that the authorized principal cannot reach resources beyond its assignment. Repeat these tests after claim formats, trust policies, or permissions change.

Map legacy credentials before starting migration

Copy link

Migration checklist

Copy link

A credential inventory defines the real migration scope. For every key, certificate, API token, or client secret being considered, capture:

• the workload and environment that use it;
• the target resources and operations it reaches;
• its current permissions and where they are defined;
• every location where the credential is stored or copied;
• its owner, rotation process, expiration behavior, and incident contact;
• other workloads, scripts, or recovery procedures that reuse it.

Do not assume the identity named in IAM maps to a single workload. Usage logs, pipeline configuration, secret references, vault access, and owner interviews often expose hidden consumers. A shared key is not one migration item: it is a coupling between workloads. Replacing it may require several federated identities and narrower permission sets.

Create a mapping record for each future principal: old credential, owning workload, authoritative identity source, accepted issuer and claims, required permissions, validation evidence, and revocation owner. This prevents the project from becoming a generic “enable OIDC” initiative with no accountable exit condition.

Also establish a baseline for legacy usage before changing authentication. Identify which logs show the old access key ID, service principal, certificate thumbprint, or equivalent identifier. If the platform cannot distinguish old and new access in telemetry, add that capability before overlap begins. Otherwise, the team cannot prove that the old path is unused.

Migrate with temporary overlap and an explicit exit condition

Copy link

Overlap is a rollback mechanism, not a permanent architecture. Set a time-bound migration window and an exit condition before enabling the new path. The condition should include successful token exchanges, successful required resource operations, rejected negative tests, and zero expected use of the old credential over a period that covers the workload's normal schedule.

Use this sequence:

1. Create the federated trust path with issuer, audience, subject, tenant, and environment restrictions.
2. Grant the new principal equivalent or narrower permissions based on the inventory.
3. Enable federation for one workload in one environment.
4. Observe token exchange, resource access, denials, and workload behavior.
5. Move the production job or traffic to the federated path.
6. Verify that the legacy credential has no expected use and investigate every remaining event.
7. Revoke the legacy credential and remove its stored copies and fallback references.

Rollback during the window should be an explicit operator action. Avoid application logic that silently falls back to the static credential whenever token exchange fails. Silent fallback hides federation defects and can keep the legacy path alive indefinitely. If rollback is used, log the decision, investigate the cause, and restart the evidence window.

Practical migration example: a CI/CD deployment job

Copy link

Consider a hypothetical deployment job that uses a long-lived cloud key to update a production Kubernetes workload. The CI platform becomes the identity source, and a protected production job becomes the principal. Its issuer signs an OIDC assertion containing a target-specific audience plus claims for the organization, repository, and protected environment.

The cloud trust policy accepts only that combination. The mapped role can update the intended workload and read its deployment artifact, but it cannot administer IAM, modify the federation provider, or deploy to unrelated clusters. The team first exercises this path in non-production with a separate identity and role, including negative tests from an unapproved branch and repository.

For production, the job requests a platform assertion, exchanges it through the cloud STS, and runs the deployment with the issued short-lived credential. During a short overlap, engineers correlate the CI run ID, token exchange, federated principal, and resource operations. They also monitor the old access key's identifier. Once normal scheduled and manual deployment paths use federation, negative tests fail as designed, and the old key has no expected use, its owner revokes it and removes every stored copy.

The provider-specific mechanics are deliberately outside this decision guide. Mad Devs' Azure AKS guide shows GitHub Actions using Managed Identity and Federated Credentials. The AWS OIDC guide shows trust and role configuration for GitHub Actions and GitLab CI. In either implementation, verify the current provider documentation and apply the trust and permission tests above.

Design for short-lived token and federation failures

Copy link

Federation replaces secret distribution and manual rotation with runtime dependencies. The workload now depends on its identity endpoint or issuer, the token exchange service, network reachability, correct time, and compatible claims. Treat those dependencies as part of production reliability.

Choose a token lifetime that limits exposure while allowing the operation to complete. Implement renewal or reacquisition before expiry for long-running work. Do not assume an issued cloud credential expires when the source assertion or CI job ends; the target credential has its own lifetime. Treat both the assertion and resulting token as sensitive because a stolen bearer token may be usable until it expires.

Test predictable failure modes: issuer or STS unavailability, clock skew, audience mismatch, changed subject format, invalid signatures, expired assertions, permission propagation, and target throttling. The workload should fail clearly, avoid logging tokens, and expose enough context to distinguish identity acquisition failure from authorization denial. Retries need limits and jitter so an identity outage does not become a retry storm.

Removing trust stops new exchanges but may not invalidate already issued sessions immediately. Incident procedures should cover both new issuance and active credentials, using the controls each provider supports. They should also account for configuration propagation delays.

If the business requires emergency credentials, manage them as a separate break-glass process. Give the credential a named owner, restricted storage, approval conditions, monitoring, rotation, and a post-use revocation procedure. A static key left in a pipeline as an automatic fallback is not break glass; it is a second production authentication path.

Audit federation as a trust system

Copy link

The audit objective is end-to-end attribution: connect a token exchange and its resource actions to a specific workload execution. Collect the issuer, subject, audience, mapped attributes, federated principal, session identifiers, target resources, and decision outcome where the platforms expose them. Correlate those fields with CI run IDs, Kubernetes workload metadata, or equivalent execution records.

Monitor successful and failed exchanges, denied resource requests, unexpected identities, and changes to issuers, claim mappings, trust conditions, roles, and permissions. Alert when a workload scheduled for migration still uses its legacy credential. Review whether changes to the identity source itself – repository ownership, environment protection, service-account binding, or tenant configuration – can widen access without a visible change to the target trust policy.

Audit queries should answer four operational questions:

• Which workloads obtained federated credentials during the period?
• Which issuer, subject, audience, and attributes supported each trust decision?
• What did each federated principal access, and which requests were denied?
• Did any retired or soon-to-be-retired credential remain active?

Track migrated workloads, post-cutover legacy-credential events, exchange failures by cause, and identities with shared principals or broad permissions. Interpret zero legacy events only after every expected path has run.

Configuration review is equally important. Look for wildcard subjects, broad audiences, mutable or reusable identifiers, shared production and non-production principals, and deployment roles able to modify federation. Google Cloud's guidance highlights spoofing, privilege escalation, subject collisions, and loss of auditability as configuration risks; the same review questions are useful across providers even when their policy syntax differs.

Migration is complete only when the legacy credential has zero expected usage, remaining dependencies are understood, and the credential has been revoked. A dashboard showing successful federated exchanges proves that the new path works. It does not prove that the old path is gone.

When an organization cannot reliably locate long-lived machine credentials, separate shared consumers, or compare trust across clouds and tenants, a focused assessment can establish the migration map. Mad Devs' Infrastructure & DevOps Audit and Focused Technical Review can examine cloud access, CI/CD, identity boundaries, and the evidence needed for a controlled redesign.

Replace one credential end to end

Copy link

Workload identity federation reduces dependence on stored, reusable secrets, but the security result depends on the relationship that replaces them. The intended workload must be identified precisely, its permissions must remain narrow, and its activity must be attributable. The migration also needs a terminal state; indefinite dual access preserves the very credential risk the project was meant to remove.

Choose one long-lived machine credential that your team wants to remove. Before configuring federation, document the workload that owns it, the identity source that can prove that workload, the permissions it actually requires, and the evidence you will use to revoke the old credential.