> ## Documentation Index
> Fetch the complete documentation index at: https://ryvn.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Workload identity

> Let CI jobs, Kubernetes pods, and agents sign in to Ryvn with their own OIDC token instead of a stored client secret

> [!NOTE]
>
> Workload identity is in preview and isn't enabled by default. [Contact Ryvn support](https://ryvn.ai/docs/support/contact-us.md) 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](https://ryvn.ai/docs/deploy/github-actions-integration.md#authentication).

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](https://cel.dev) 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.

```bash theme={null}
ryvn get workload-issuer-preset
ryvn create workload-issuer --preset gitlab-com
```

The presets are `github`, `gitlab-com`, `gcp`, `kubernetes`, `cursor`, and `custom`. For any other provider, give the
issuer URL and its signing keys:

```bash theme={null}
ryvn describe workload-issuer https://oidc.example.invalid
ryvn create workload-issuer https://oidc.example.invalid \
  --jwks-url https://oidc.example.invalid/jwks \
  --subject-keys sub \
  --algorithms RS256
```

`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`:

| Flag | Effect |
| - | - |
| `--display-name` | A readable name. |
| `--subject-keys` | The claims a binding may pin. |
| `--run-claim` | The claim that identifies one run, used for rate limiting. |
| `--max-token-age` | The oldest token to accept, in seconds. Ryvn lowers it to its own ceiling if needed. |
| `--allow-token-reuse` | Let one token be exchanged more than once. |
| `--enabled=false` | Disable the issuer. Its bindings stop working. |

`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`:

```bash theme={null}
ryvn create workload-binding \
  --issuer <issuer-id> \
  --subject-key project_id \
  --subject-value 12345 \
  --policy 'claims.project_id == "12345"' \
  --new-service-user 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.

```bash theme={null}
ryvn create workload-binding --from-token "$TOKEN" --new-service-user ci-release
```

`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.

```bash theme={null}
ryvn describe workload-binding <binding-id> --from-token "$TOKEN"
ryvn describe workload-binding <binding-id> \
  --claims '{"project_id":"12345"}' \
  --policy 'claims.project_id == "12345"'
```

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](https://ryvn.ai/docs/iac/access-policy.md). The member is `service-user:<name>`:

```yaml theme={null}
kind: AccessPolicy
metadata:
  name: ci-release
spec:
  members:
    - service-user:ci-release
  grants:
    - developer:environment:staging
```

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:

| Provider | What the workload needs | Claim to pin |
| - | - | - |
| GitHub Actions | `permissions: id-token: write`. See [GitHub Actions integration](https://ryvn.ai/docs/deploy/github-actions-integration.md#which-identity-a-job-uses). | `repository_id` |
| GitLab CI | An `id_tokens` entry whose `aud` is your Ryvn API URL, and `RYVN_OIDC_TOKEN_ENV` set to the entry's name. | `project_id` |
| Google Cloud | A service account attached to the workload. The CLI reads its token from the metadata server. | `sub` |
| Kubernetes | A projected service account token whose `audience` is your Ryvn API URL, mounted at `/var/run/secrets/ryvn/token` or named in `RYVN_OIDC_TOKEN_FILE`. | `kubernetes.io/namespace`, `kubernetes.io/serviceaccount/name`, or `sub` |
| Cursor cloud agent | `CURSOR_AGENT_SOCKET`, which Cursor sets on its hosted agents. A self-hosted worker needs `cursor-agent worker --identity-socket`. | `sub`, as `user:<cursor-user-id>` or `service_account:<id>` |

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.

> [!NOTE]
>
> 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:

| Reason | Meaning | What to do |
| - | - | - |
| `NoBindingForIdentity` | No binding accepted the token. Ryvn reports several different causes the same way. | Run `ryvn describe workload-binding <id>` for the binding's recent denial reasons, such as `policy_denied`. |
| `UnknownIssuer` | No enabled issuer trusts the token's issuer. | Register it with `ryvn create workload-issuer <issuer-url>`, or enable it. |
| `InvalidToken` | The token failed verification. | Check that its audience is your Ryvn API URL and that it hasn't expired. |
| `FederationNotEnabled` | Workload identity is off for your organization, or the issuer is disabled. | [Contact Ryvn support](https://ryvn.ai/docs/support/contact-us.md), or run `ryvn set workload-issuer <issuer-url> --enabled=true`. |
| `AmbiguousOrganization` | Several organizations trust this identity. | Set `RYVN_ORG_ID` to the organization's ID. A name or slug doesn't work. |
| `AmbiguousTarget` | The token matches bindings for more than one service user. | Set `RYVN_SERVICE_USER` to a service user ID, or `RYVN_BINDING_ID` to a binding ID. The error lists the candidates. |
| `TargetNotEligible` | The service user or binding you named doesn't match this token, or doesn't exist. | Check the value, or unset it to see the eligible targets. |
| `Replay` | The token was already used. | Use a fresh token. A job-scoped token needs a new job, or an issuer registered with `--allow-token-reuse`. |
| `RateLimited` | The workload or its source IP exchanged too many tokens. | Run fewer concurrent `ryvn` commands. |

`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`.

```bash theme={null}
ryvn get workload-denials
```

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](#grant-the-service-user-roles).

## Revoke access

These commands cut off every workload that depends on the binding or issuer, so confirm the target first.

```bash theme={null}
ryvn set workload-binding <binding-id> --enabled=false
ryvn delete workload-binding <binding-id>
ryvn set workload-issuer <issuer-url> --enabled=false
ryvn delete workload-issuer <issuer-id>
```

`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:

```bash theme={null}
ryvn delete federation-credential <service-user>
```

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.
