Workload identity is in preview and isn’t enabled by default. Contact Ryvn support to enable
it for your organization. Until it’s enabled, the exchange fails with
FederationNotEnabled, and registering an
issuer can be refused.RYVN_CLIENT_ID and RYVN_CLIENT_SECRET on it. The Ryvn CLI reads the workload’s OIDC token, exchanges it for a
short-lived Ryvn credential, and runs the command as a service user. It works for GitLab CI, Google Cloud workloads,
Kubernetes pods, Cursor cloud agents, and any other OIDC issuer. GitHub Actions has a built-in setup that needs no
registration: see GitHub Actions integration.
Three things control what a workload can do:
- An issuer says which OIDC provider Ryvn trusts to sign tokens, such as
https://gitlab.com. - A binding says which tokens from that issuer map to which service user. It pins one claim, such as a GitLab
project_id, and carries a CEL policy that checks more claims. - The service user’s roles decide what the workload can do once it’s signed in.
403 until you grant access.
Set up a workload identity
Register the issuer once, then repeat the binding and role steps for each workload. Run the first three steps with the CLI signed in as an organization admin. The last step runs inside the workload.Register an issuer
List the providers that have presets, then register one. The command prints the provider’s setup steps and a job snippet.github, gitlab-com, gcp, kubernetes, cursor, and custom. For any other provider, give the
issuer URL and its signing keys:
describe workload-issuer <issuer-url> reads the provider’s discovery document and prints its JWKS URL and supported
algorithms, so you can copy them into create. For an issuer with no public key endpoint, such as a private cluster,
pass --jwks-static-file jwks.json instead of --jwks-url. Your Ryvn instance can refuse static key sets, with the
error static JWKS issuers are not enabled on this hub.
Other flags on create and set:
ryvn set workload-issuer <issuer-url> creates the issuer if it doesn’t exist and updates it if it does, matching on
the URL. ryvn get workload-issuer lists issuers, and -o json shows each issuer’s id, which bindings need.
Create a binding
Pin one claim of the token and name the service user the workload becomes. This binding lets GitLab project12345
sign in as a new service user named ci-release:
--subject-keymust be one of the issuer’s subject keys.- Use exactly one of
--new-service-user <name>, which creates a service user with no roles, or--service-user <name-or-id>for an existing one. - A policy is required: pass
--policyor--policy-file. - The command updates in place when a binding with the same issuer, subject key, subject value, and service user already exists.
--from-token. The CLI reads the token’s claims, picks the registered
issuer and subject pin, proposes a policy, saves the binding, and tests the policy against the token. It decodes the
token without verifying it. Treat the token as a credential: use one that’s short-lived or already expired.
ryvn get workload-binding lists bindings with their target and last exchange. ryvn set workload-binding <id>
changes the policy (--policy, --policy-file, or --clear-policy), the target (--service-user), the pin
(--subject-key, --subject-value), or --enabled.
Test a policy
describe workload-binding tests the binding’s policy against claims without signing anything in. Pass one of
--claims, --claims-file, or --from-token. Add --policy to try a new expression instead of the stored one.
kubernetes.io, so a policy reads them as
claims["kubernetes.io"]["namespace"] and claims["kubernetes.io"]["serviceaccount"]["name"].
Grant the service user roles
Grant roles to the service user with an access policy. The member isservice-user:<name>:
Run the CLI in the workload
Install the CLI in the workload and runryvn as usual. What the workload needs to expose its token depends on the
provider:
The token’s audience must be the API URL the CLI uses: the
API line under Endpoints in ryvn auth status. On a
dedicated Ryvn instance, set RYVN_API_URL to that URL.
To confirm which credential a run uses, add ryvn auth status. It prints a Workload identity section with the
token source, the issuer, the subject, the service user, and the binding Ryvn matched.
Each
ryvn command exchanges the workload token again. A GitLab id_tokens token stays the same for the whole
job, so unless the issuer allows reuse (--allow-token-reuse), a second ryvn command in the same job, including
ryvn auth status, can fail with Replay. Allow token reuse on the issuer if a job runs more than one command.How the CLI picks a token
The CLI chooses a credential in this order, and uses the first one that applies:RYVN_ACCESS_TOKEN, a ready-made Ryvn token, while it’s valid for more than another minute.- A workload token, chosen as described below.
RYVN_CLIENT_IDandRYVN_CLIENT_SECRET.- The stored login of the active profile.
RYVN_OIDC_TOKEN holds the token,
RYVN_OIDC_TOKEN_FILE names a file that holds it, and RYVN_OIDC_TOKEN_ENV names another environment variable that
holds it. Set only one. When it finds more than one source and none is selected, the CLI stops with
multiple workload token sources detected and the names it found.
With nothing set explicitly, the CLI probes the platform it runs on: GitHub Actions, the Google Cloud metadata server,
the Cursor socket, and the Kubernetes token file. The Google Cloud, Cursor, and Kubernetes probes are skipped when
RYVN_CLIENT_ID and RYVN_CLIENT_SECRET or a stored login exist, so a Cursor worker on a laptop doesn’t override your
own login. GitHub Actions with id-token: write always stays eligible, and it wins over the other platform probes
when several match.
To force one source, set RYVN_OIDC_SOURCE to env, file, github, gitlab, gcp, cursor, or k8s. The
CLI fails if that source isn’t present.
When the exchange is refused, the command fails. The one exception is a GitHub Actions token: if Ryvn answers
FederationNotEnabled or RateLimited, or AmbiguousOrganization while RYVN_ORG_ID is unset, the CLI warns and
falls back to RYVN_CLIENT_ID and RYVN_CLIENT_SECRET when they’re set. For every other source and every other
denial, static credentials aren’t tried, even if they’re set.
Fix a denied exchange
A refused exchange fails with a reason name and a hint:RYVN_SERVICE_USER and RYVN_BINDING_ID only choose among the targets the token already matches. The workload’s token
is still the credential.
To see denials without a binding ID, list the organization’s recent denials. A token whose subject no binding pins
appears here with the reason subject_not_registered.
ryvn get returns an empty list or 403 for a workload that signed in, the service user probably has no roles yet.
Grant them.
Revoke access
These commands cut off every workload that depends on the binding or issuer, so confirm the target first.delete workload-issuer refuses while bindings exist under the issuer. Add --delete-bindings to delete them with it.
For a service user, ryvn describe federation-credential <service-user> shows the credential’s status, its bindings,
and the last exchange. To cut access immediately, for example after a leak, delete the credential:
create workload-binding or
set workload-binding for that user sets the credential up again.