Workload Identity Federation (WIF) Issuers
A WIF issuer is an organization-wide record that registers an external OIDC identity provider (IdP) the organization trusts. Only organization owners or administrators can create and manage issuers, but all organization members can list and read them when configuring a WIF Configuration on a service account.
Decoupling key material into a shared issuer means that when an IdP rotates its signing keys, a single record needs to be updated regardless of how many service accounts reference that IdP.
Key source modes
Each issuer has exactly one key source. At most one of the options below may be set. If none is set, the control plane uses OIDC discovery based on the Issuer URL to find the JWKS endpoint.
| Mode | When to use | Behavior |
|---|---|---|
| Auto-discover (default) | Public issuers with a standard well-known endpoint (GitHub Actions, GitLab CI) | Control plane fetches JWKS from {issuer_url}/.well-known/openid-configuration. |
OIDC URI (--oidc-uri) | Issuers whose OIDC discovery endpoint is at a non-standard URL | Control plane fetches the OIDC configuration from the provided URI instead of constructing it from issuer_url. |
JWKS URL (--jwks-url) | Issuers whose JWKS endpoint is known and the full OIDC discovery document is not needed | Control plane fetches JWKS directly from the provided URL. |
Inline JWKS (--jwks) | When you have the JWKS document and want to provide it directly | JWKS JSON is stored as-is. No external requests are made for key material. |
PEM (--jwks-pem-file) | Private or air-gapped IdPs whose JWKS endpoint is unreachable by the control plane | You upload PEM-encoded public keys. The control plane makes no external requests for key material. Call wif-issuer set again when keys rotate. |
The PEM value is stored encrypted at rest and is never returned in API responses.
Managing issuers
For the full spirlctl iam wif-issuer command reference — set, list, get, and delete — see WIF Issuer Operations.
Security considerations
- For auto-discover, OIDC URI, and JWKS URL modes, the control plane enforces HTTPS-only URLs. Fetched JWKS are cached to limit external request volume and handle transient endpoint downtime.
- For PEM and inline JWKS modes, the control plane makes no external network requests for key material. Organization administrators are responsible for updating the issuer when the IdP rotates its signing keys.
- PEM values are stored encrypted at rest and are never returned in API responses.