Browse docs · Concepts
Get started
Concepts
Guides
Security
Reference
Docs / Concepts
Workload identity
Let agents authenticate with short-lived tokens from GitHub Actions, GitLab CI, Google Cloud, Kubernetes or SPIFFE instead of long-lived agent tokens.
An agent needs to prove who it is to the broker. Instead of a stored token, it can present a short-lived identity token issued by the platform it runs on. Nothing long-lived lives with the agent.
Two ways to authenticate
| Agent token | Workload identity | |
|---|---|---|
| Issued by | PastKeys dashboard | Your platform (GitHub, GitLab, Google, Kubernetes, SPIRE) |
| Lifetime | 90 days | Minutes |
| Stored by the agent | Yes | No, fetched per job or per call |
| Agent ID | Chosen by you | Prefix plus a token claim, e.g. github:repo:acme/app:ref:refs/heads/main |
Trusted issuers
In Workload identity add a trusted issuer (presets cover the common platforms). Each binding checks, and fails closed on:
- Signature against the issuer's published keys (RS256/384/512, PS256, ES256, ES384).
- Audience, which must be exactly yours.
- Required claims, such as
repository_owner = acme. These are mandatory for GitHub, GitLab.com and Google, because anyone can get a token from those issuers. - Expiry, and optionally a maximum token lifetime.
The agent ID is the binding's prefix followed by the identity claim (default sub); policies name that ID. Brokers pick up issuer changes within a minute.
Single use
Tokens that live 15 minutes or less are accepted once, so a captured token cannot be replayed. Fetch a fresh token for each call.
Require workload identity
Turn on Require workload identity to make brokers refuse agent tokens entirely and stop the dashboard from issuing them. It cannot be enabled until at least one issuer is trusted.
Self-hosted brokers can also trust issuers locally with BROKER_OIDC_ISSUERS (see configuration). Step-by-step: GitHub Actions guide.