Skip to main content
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.
Workload identity lets a workload sign in to Ryvn with a token its own platform already gives it, so you don’t store a 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.
A binding only identifies the workload. A service user that a binding creates has no roles, so the exchange succeeds and every API call returns 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.
The presets are 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 project 12345 sign in as a new service user named ci-release:
  • --subject-key must 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 --policy or --policy-file.
  • The command updates in place when a binding with the same issuer, subject key, subject value, and service user already exists.
To start from a real token instead, pass it with --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.
Without any of those flags, it prints the binding and its recent denials. In a Kubernetes token, the namespace and service account are nested under 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 is service-user:<name>:
Grant the least access the workload needs. Every workload that matches the binding gets these roles.

Run the CLI in the workload

Install the CLI in the workload and run ryvn 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:
  1. RYVN_ACCESS_TOKEN, a ready-made Ryvn token, while it’s valid for more than another minute.
  2. A workload token, chosen as described below.
  3. RYVN_CLIENT_ID and RYVN_CLIENT_SECRET.
  4. The stored login of the active profile.
For the workload token, the CLI first looks at what you set explicitly: 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.
If 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:
This revokes the service user’s workload credential now. Its bindings fail until the next create workload-binding or set workload-binding for that user sets the credential up again.