Skip to content

0003. OIDC federation over long-lived cloud secrets

  • Status: Accepted
  • Date: 2026-05-28
  • Formalizes: D22, D26
  • Deciders: Sagar, SnowOps engineering

Context

CI/CD and service principals need to authenticate to Azure. The traditional path is a client secret or certificate stored in the CI system and rotated on a schedule. Stored credentials leak, expire at the worst time, and accumulate as unrotated debt. One of our non-negotiable principles is Identity > Secrets.

Decision

We will use workload-identity / OIDC federation as the default authentication mechanism, and treat long-lived cloud credentials as something to eliminate rather than rotate:

  • GitHub Actions authenticate to Azure via federated OIDC (no client secrets); apps/github-onboarder (B1) attaches federated identity credentials to the client's Azure AD App Registration at onboarding time.
  • AKS workloads use Workload Identity (Azure CNI Overlay), and External Secrets Operator authenticates to Key Vault via that identity (F8/D24).
  • State-backend data-plane access uses use_azuread_auth = true with shared-key access disabled (D22); no storage account keys in CI.
  • Where secrets still exist (legacy SPs), H5 (D26) is a read-only tool that opens a rotation PR rather than auto-rotating, and actively steers SPs toward federated OIDC — a secretless SP never goes stale.

Consequences

  • Easier: no secret storage, distribution, or rotation for the federated paths; credential leakage surface shrinks toward zero.
  • Easier: least-privilege is cleaner — federated credentials are scoped per repo / environment / branch.
  • Harder / accepted: OIDC trust requires correct subject/audience configuration; misconfiguration fails closed (no access) which is the safe direction but adds setup friction. Some Azure resources still need network reachability for GitHub-hosted runners (D22), so network lockdown stays opt-in.

Alternatives considered

  • Stored client secrets with scheduled rotation: rejected — violates Identity > Secrets; rotation is perpetual toil and a recurring leak risk.
  • Self-hosted runners with managed identity only: deferred — adds runner fleet ops; federated OIDC gives most of the benefit on hosted runners.

References

  • apps/github-onboarder (B1), apps/sp-inventory (H5, D26), gitops/ (F8)
  • modules/azure/ state-backend wiring (D22)
  • Decisions D22, D26 in docs/context/07-decisions.md