A secretsless pipeline does not mean a pipeline with no credentials. It means the deployment job starts without a reusable cloud key, proves its workload identity with a short-lived OpenID Connect token, and exchanges that assertion for narrowly authorized cloud access. The credential exists only for the job's bounded session. This removes a high-value stored secret from repositories and CI secret stores, but only if the cloud trust policy restricts which workflow may obtain which role.
A broad federation rule can be worse than one well-governed key because every matching workflow becomes a mint for temporary credentials. Design the trust relationship around immutable provider identity and constrained claims: issuer, audience, organization, repository, workflow, branch or protected environment, and sometimes stable numeric IDs. Then constrain the cloud role itself. Authentication says which workload presented the assertion; authorization says what that workload can change.
Understand the federation exchange
OpenID Connect Core defines identity assertions built on OAuth 2.0, including issuer, subject, audience, expiry, issued-at time, and signature validation. A CI platform acts as the identity provider and issues an ID token describing one job context. The cloud security token service validates it against configured trust and returns a provider-specific access token or role session. The ID token should not be treated as a generic cloud bearer token or logged for debugging.
RFC 8693 standardizes OAuth token exchange concepts, but provider implementations differ in claims, mapping, conditions, token lifetime, and resulting identity. Document the exact exchange used. Trust begins with TLS and discovery or pinned configuration for the issuer and JSON Web Key Set, continues through token signature and claim validation, and ends with cloud authorization. Cache and key-rotation behavior must not silently accept stale or unknown signing material.
Write the workload trust contract before configuring it
Describe one sentence per role: only the protected production deployment job in repository R, running through reusable workflow W and environment E, may request audience A and assume production role P. Separate build, staging, production, database migration, and rollback roles. The trust contract should identify who controls each input: repository administrators, workflow maintainers, environment approvers, CI provider, cloud identity administrators, and resource owners. A condition is only as strong as the governance of the claim behind it.
| Claim or control | Security purpose | Preferred constraint | Failure to avoid |
|---|---|---|---|
Issuer (iss) | Selects the identity provider | Exact provider URL and trusted keys | Accepting tokens from another tenant or issuer |
Audience (aud) | Binds token to intended relying party | Exact cloud or broker audience | Token replay at an unintended service |
Subject (sub) | Expresses workload context | Exact repo plus protected environment or branch | Organization-wide wildcard |
| Repository identity | Binds to controlled project | Stable ID plus owner where supported | Name reuse after transfer or deletion |
| Workflow identity | Restricts deployment implementation | Pinned reusable workflow reference | Any workflow in an allowed repository |
| Environment | Adds approvals and branch restrictions | Protected production environment | Trusting an unprotected branch name |
Choose claims that survive real repository changes
Review the CI provider's current claim reference rather than copying an internet example. GitHub's OIDC reference documents standard and custom claims, subject formats, immutable identifiers, reusable-workflow information, and customization. Prefer stable repository and organization identifiers where the cloud supports them; names can change or be reused. Test the exact token claims in a non-sensitive environment, then encode an allowlist. Never print a production token into logs to inspect it.
Branch trust alone is often too weak. A repository administrator may change a workflow on that branch, a pull-request workflow may run attacker-controlled code, or a dependency action may be compromised. Use protected deployment environments, required reviewers, restricted deployment branches or tags, pinned third-party actions, CODEOWNERS for workflow files, and a centrally maintained reusable deployment workflow. Where supported, require the token to identify that reusable workflow, not merely the caller repository.
Constrain the cloud role after authentication
A perfect trust policy attached to an administrator role still creates excessive blast radius. Create deployment roles per environment and service, with only required actions and resource scopes. Add provider-native conditions for region, resource tags, account boundaries, session duration, and prohibited privilege escalation. The job that updates application artifacts rarely needs to create identity providers, alter trust policy, read unrelated secrets, disable logging, or administer every cluster.
AWS's OIDC federation guidance specifically recommends constraining GitHub subjects to controlled organizations, repositories, or branches and warns against unconstrained trust. Apply equivalent controls on every cloud. Separate the people who can change CI trust from those who can edit deployment workflows where practical; collusion or one compromised administrator should not automatically control both the identity assertion and relying-party policy.
| Layer | Control | Evidence to retain | Review trigger |
|---|---|---|---|
| CI organization | Allowed actions, runner policy and identity governance | Settings snapshot and audit events | Organization ownership or policy change |
| Repository | Protected workflow files and approved dependencies | Commit, review and action digests | Repository transfer or administrator change |
| Environment | Approvals, branches and deployment rules | Approval and job-environment record | Production policy change |
| Federation | Issuer, audience, subject and attribute conditions | Versioned trust policy | Claim-format or provider change |
| Cloud role | Least privilege and bounded session | Authorization policy and access analysis | Resource architecture change |
| Deployment | Artifact identity and change record | Role session, artifact digest and outcome | Incident or rollback |
Implement the workflow with minimum token exposure
Grant permission to request an ID token only to the deployment job, not every workflow job. Keep source checkout and untrusted build steps separate from the trusted deployment stage. Prefer promoting an immutable artifact built earlier, with admission or provenance verification, rather than rebuilding after obtaining cloud access. Request credentials immediately before use, keep the session short enough for the operation, and clear generated credential files or environment variables during cleanup.
Pin deployment actions to reviewed versions or immutable commits according to provider guidance. Prevent pull requests from untrusted forks or modified scripts from reaching the privileged job. On self-hosted runners, isolate jobs and destroy workspaces; short-lived credentials do not protect against persistence that steals the next job's token. Restrict outbound network destinations where feasible, because arbitrary exfiltration can turn any issued bearer credential into remote access during its lifetime.
Migrate stored keys without losing rollback
Inventory deployment keys by repository, cloud principal, permissions, last use, owner, and rotation state. Build federation in parallel, compare the resulting role and audit identity, then migrate one non-production workflow. Move production through a change window with explicit rollback. After successful observation, remove the stored secret from CI, disable and delete the old cloud key, search history and logs for exposure, and confirm no alternate workflow still depends on it.
Do not keep a permanent administrator key as an easy rollback. Maintain a separate, strongly authenticated break-glass process with human approval, limited role, short duration, audit alerting, and post-use review. Test recovery from issuer outage, cloud token-service outage, claim-format change, expired trust configuration, and accidental policy lockout. Secretsless delivery improves routine credential hygiene; resilience still requires an engineered emergency path.
Monitor sessions and prepare incident response
Cloud audit events should show the federated role session, source identity or claims available from the provider, actions, resources, region, and time. Join them to CI run ID, repository and workflow commit, environment approval, deployer, and artifact digest. Alert on unexpected repositories, audiences, branches, role assumptions outside deployment windows, denied assumption spikes, privilege-policy changes, and cloud activity without a matching job. Retain records long enough to investigate software and credential incidents.
If a workflow or repository is compromised, disable the trust relationship or narrow conditions, cancel active jobs, revoke sessions where supported, and inspect cloud activity. Correct the workflow and dependency path before restoring federation. Rotating no long-lived key is an advantage, but already issued access tokens remain valid until expiry or revocation. That is why short sessions, narrow roles, immutable artifacts, and correlated logs matter.
Key takeaways
- Federation replaces stored keys with short-lived credentials; it does not remove credential or workflow risk.
- Constrain exact issuer, audience, stable repository identity, workflow, and protected environment claims.
- Give each deployment role narrow resource permissions and a bounded session.
- Separate untrusted build activity from the job that requests production credentials.
- Correlate cloud sessions to CI runs, approvals, workflow commits, and artifact digests.
Frequently asked questions
Does id-token: write grant cloud write access?
No. It lets the job request an OIDC token. Cloud access depends on the relying party's trust conditions and the permissions of the role or principal issued after exchange. Both configurations must be reviewed.
Can one federated role serve every repository?
Technically, but broad trust and permissions increase blast radius and make attribution harder. Prefer service and environment roles with exact workload conditions. Central reusable workflows can standardize deployment without granting every caller identical authority.
Should long-lived deployment keys be deleted immediately?
Remove them after federation is tested, observed, and a controlled recovery path exists. Then disable and delete the keys promptly, confirm no use, and remove secret-store copies. Keeping them indefinitely defeats the migration's main benefit.
Conclusion
OIDC CI/CD cloud authentication is strongest when one protected workload can obtain one short-lived, least-privileged role for one deployment context. Define that context as a trust contract, encode stable claims, constrain cloud authorization, isolate deployment from untrusted execution, and preserve end-to-end audit identity. Done well, federation eliminates a durable secret and makes every deployment credential narrower and more attributable. Done broadly, it simply creates a faster credential issuer for compromised workflows.