Cloud workload identity federation security checklist
Replace long-lived CI/CD cloud keys with workload identity federation, narrowly scoped trust claims, short-lived credentials, protected environments and auditable deployment roles.
In this guide
What is workload identity federation?
Workload identity federation lets an external workload, such as a CI/CD job, prove its identity to a cloud provider and exchange that proof for temporary access. It can remove the need to store a long-lived cloud key in repository secrets, but a broad trust policy can let an untrusted workflow obtain the same access. Secure the issuer, audience and identity claims together, then give the resulting role only the deployment permissions it needs.
Inventory which workloads need cloud access and why
List repositories, CI platforms, deployment environments, cloud roles, target resources and human owners. Separate build, test and production deploy identities. Remove unused access keys and identify any remaining path that can assume the same role without passing through the intended federated trust.
Restrict trust to the expected issuer, audience and workload claims
Validate the token issuer and audience, then constrain subject or mapped claims to the trusted organization, repository, branch, tag, protected environment or reusable workflow. Do not accept every repository from a shared identity provider. Google Cloud recommends attribute conditions for multi-tenant providers such as GitHub; configure the equivalent claim conditions in your provider.
Use short-lived roles with a narrow deployment purpose
Allow the federated identity to assume a role scoped to the target environment and resources, with only the actions the job needs. Set a session duration appropriate to the deployment and keep production separate from preview or test. Federation replaces a stored cloud credential; it does not make the workflow or deployment artifact trustworthy by itself.
| Workflow and environment | Issuer, audience and claims | Cloud role and permissions | Approval and runner controls | Test and review date |
|---|---|---|---|---|
| Test deployment | ||||
| Production release | ||||
| External reusable workflow |
How should teams configure GitHub Actions OIDC safely?
Grant token permission only to the job that deploys
Set id-token: write at the smallest practical job scope and keep other workflow permissions minimal. GitHub notes that this permission lets a job request an OIDC token; it does not itself grant write access to cloud resources. The cloud trust policy and resulting role permissions determine what that token can do.
Match the trust policy to protected branches and environments
Use provider claim conditions to restrict deployments to reviewed branches, tags or protected environments. Add environment approval rules where production release needs a second-person check. Review pull-request workflows, reusable workflows and self-hosted runners because code running in a trusted job may be able to request that job's token.
Check the exact subject format after repository or identity changes
OIDC claim formats and provider mappings can evolve. GitHub documents immutable subject formats for repositories created or transferred after 15 July 2026, or that opted into the format. Confirm the actual token claims for your repository before changing trust, then update conditions without broadening access to make a deployment pass.
How do you operate and review federated cloud access?
Protect the workflow code and actions that can request a token
Require review for deployment workflow changes, pin third-party actions to reviewed immutable versions where appropriate, protect reusable workflows and restrict who can approve production environments. Limit self-hosted runner access and avoid running untrusted pull-request code on runners that hold sensitive network or identity access.
Log role assumptions and alert on unexpected subjects
Send cloud identity events to the protected audit destination and retain the federated subject or source identity when the provider records it. Alert on role use from an unexpected repository, branch, environment or time, and test that denied claims fail closed. Review trust conditions after repository transfers, renames, workflow reuse or cloud-account changes.
Keep a recovery path that does not weaken the trust policy
Document who can restore the federated provider or role if configuration breaks. Use a controlled, logged break-glass route with limited scope and review rather than adding a wildcard claim or permanent access key during an incident. Revoke temporary credentials and remove emergency grants after recovery.
Workload identity federation FAQs
Does workload identity federation eliminate all secrets?
No. It can eliminate a long-lived cloud key for the federated exchange, but applications may still need database passwords, signing keys or third-party tokens. Store those separately in an approved secrets service and scope access to the specific workload.
Does id-token: write let a GitHub workflow change cloud resources?
No. That permission lets the job request a GitHub OIDC token. The cloud provider issues an access token only if its trust policy accepts the claims, and the resulting role then determines resource permissions. Keep both the trust conditions and role policy narrow.
Can every workflow in a repository use the production role?
Avoid broad repository-only trust when only one protected deployment workflow should reach production. Constrain branch, environment, workflow or other stable claims supported by the provider, and confirm untrusted pull-request jobs cannot satisfy those conditions.
Do federated credentials need rotation?
Short-lived exchanged credentials expire, which reduces the need to rotate a stored cloud key. You still need to review provider trust, signing keys and issuer configuration, role permissions, workflow ownership and any other long-lived secrets the workload uses.
Related practical guides
Related issue guides
Sources and publication record
Draft prepared 27 September 2026; engineering, security and editorial review pending · Sources checked .
- Configuring OpenID Connect in Cloud ProvidersGitHub Docs
- OpenID Connect Reference for GitHub ActionsGitHub Docs
- Best Practices for Using Workload Identity FederationGoogle Cloud
- Identity-Provider Controls for Shared OIDC ProvidersAmazon Web Services