Authenticate a workload with OIDC#

This recipe exchanges external workload identity for one short-lived scoped grant without storing a production secret in CI. Commands and values are illustrative end-product examples.

Declare the requirement#

require one.authority#WorkloadAuthenticate@1(
    issuer: "https://token.actions.example"
    audience: "one-build"
    subject: repository("muijf/one", ref: "refs/heads/main")
)

The declaration is not a token, trust decision, or grant.

Exchange the external assertion#

one invoke one.authority.workload#Exchange@1 workload-exchange.json

The request contains the issuer, audience, assertion reference, and exact Build subject. The assertion file remains an input to the selected protected Authority boundary rather than portable source.

{
  "principal": "workload:repository/muijf/one",
  "subject": "build:sha256:…",
  "scope": ["build:execute"],
  "expires_in": "10m",
  "epoch": "authority:epoch:204"
}

Issuer signature, audience, subject, repository/ref claims, time, nonce, revocation epoch, and policy are validated independently.

Bind the grant to Build#

one build plan:sha256:… --credential workload-credential:sha256:…
one inspect build:sha256:… --subject authority

The credential cannot authorize release apply, another Build, another ref, or execution after expiry.

See authority and trust and supply chain.