Workload Identity Federation (WIF) Issuer Operations

This guide covers managing WIF issuers with spirlctl. WIF issuers are organization wide records that register external OIDC identity providers for use with secretless service account authentication.

Creating and deleting a wif-issuer requires Administrator or Owner role. All roles can list and get WIF Issuers.

Set a WIF issuer

set creates or updates a WIF issuer by name.

spirlctl iam wif-issuer set NAME ISSUER_URL [--oidc-uri <url>] [--jwks-url <url>] [--jwks <json>] [--jwks-pem-file <path>]

Argument / Flag	Required	Description
NAME	Yes	Name of the issuer. Used as the upsert key.
ISSUER_URL	Yes	The HTTPS URL of the OIDC issuer (must match the iss claim in tokens).
--oidc-uri	No	Override URL for OIDC discovery. Mutually exclusive with all other key source flags.
--jwks-url	No	URL of the JWKS endpoint. Mutually exclusive with all other key source flags.
--jwks	No	Inline JWKS JSON document. Mutually exclusive with all other key source flags.
--jwks-pem-file	No	Path to a PEM file containing the IdP's public keys. Mutually exclusive with all other key source flags.

At most one key source flag may be set. If none is provided, the control plane auto-discovers the JWKS endpoint from {ISSUER_URL}/.well-known/openid-configuration.

Example — auto-discover:

spirlctl iam wif-issuer set "github-actions" https://token.actions.githubusercontent.com

Example — JWKS URL:

spirlctl iam wif-issuer set "terraform-cloud" https://app.terraform.io \
  --jwks-url https://app.terraform.io/.well-known/jwks

Example — PEM:

spirlctl iam wif-issuer set "internal-idp" https://idp.internal.example.com \
  --jwks-pem-file /path/to/jwks.pem

Example — Inline JWKS:

spirlctl iam wif-issuer set "internal-idp" https://idp.internal.example.com \
  --jwks '{"keys":[{"kty":"RSA","kid":"key-1","use":"sig","n":"sIfxyz...","e":"AQAB"}]}'

Example output:

WIF Issuer set successfully
ID:          owi-abc1234567
Name:        github-actions
Issuer URL:  https://token.actions.githubusercontent.com
Key Source:  auto-discover

List WIF issuers

spirlctl iam wif-issuer list

Example output:

ID               NAME               ISSUER URL                                    KEY SOURCE      
owi-abc1234567   github-actions     https://token.actions.githubusercontent.com   auto-discover  
owi-def8901234   terraform-cloud    https://app.terraform.io                      jwks-url       

2 WIF issuers found.

Get a WIF issuer

spirlctl iam wif-issuer get NAME

Example output:

ID:          owi-abc1234567
Name:        github-actions
Issuer URL:  https://token.actions.githubusercontent.com
Key Source:  auto-discover

Delete a WIF issuer

spirlctl iam wif-issuer delete NAME

warning

Deleting a WIF issuer removes the key material used to verify tokens for all service accounts that reference it. Service accounts with a WIF Configuration pointing to this issuer will no longer be able to authenticate via WIF.

Example output:

WIF Issuer 'github-actions' deleted successfully.