Single Sign-On

Past a certain team size, "who holds which key" stops scaling and identity moves to the provider you already run. This server integrates with any OIDC-compliant identity provider in two independent halves: admin SSO, which signs operators into the admin surfaces through the provider, and API OIDC, which lets programs authenticate API calls with provider-issued JWTs instead of server-minted keys. Enable either, both, or neither; keys keep working alongside throughout (Keys and Authentication).

1Admin SSO: operators sign in with the provider#

Configured under Security:Sso and in the Security settings:

The flow is the standard authorization code exchange with PKCE and single-use state: the browser goes to the provider, the callback redeems the code, and a successful, ALLOWED account mints the same admin session a password sign-in mints. Refusals are precise: an account outside the domain, group, or email allowlists is told which gate refused it, which turns "SSO does not work" tickets into one-line fixes.

Two operational notes: the setup wizard offers SSO during first configuration, and the password path remains available as the break-glass sign-in for the day the provider is the thing that is down.

2API OIDC: programs authenticate with provider JWTs#

Configured under Security:Oidc, separately from admin SSO because machines and people deserve different rules:

Mechanics that matter:

• Both credential families share one header. A bearer that looks like a JWT (three dot-separated segments) validates against the provider; anything else is treated as a server key. Keys can never contain a dot, so the families cannot collide.
• Validation is the full contract: issuer, audience, expiry, and signature against the provider's published keys, plus the required scope when configured.
• The owner claim IS the tenant boundary. The claim's value, prefixed oidc:, becomes the caller's owner id, the exact same isolation an API key's owner draws: files, vector stores, response chains, memories. Choose the claim deliberately: a per-user claim makes every user their own tenant; a per-service claim makes the service one tenant (One Server, Many Teams).
• Scopes speak the key language. Read-only via scope behaves exactly like a read-only key, so authorization reasoning stays uniform across both families.

3What SSO does not change#

• Tool grants and search grants remain key features. Per-key narrowing (tools, search clusters and tenants) attaches to keys; a provider JWT arrives with the authority its scopes grant and its owner boundary, not with a key's grant records. Where fine-grained search access matters, keys remain the right credential (Access Model).
• The egress story gains exactly one channel: the OIDC exchanges with your provider, already counted in the exhaustive list.
• Anonymous loopback behavior is unchanged; SSO governs who may act, not where the server listens (Going Live).

4Rollout order that works#

1. Keep a local operator account (break-glass, Operator Accounts), then enable admin SSO and prove a provider sign-in end to end.
2. Tighten the account gates (domains, then groups) once the happy path works.
3. Enable API OIDC with RequiredScope from day one, so only tokens minted FOR this server validate, and pick OwnerClaim before real data accumulates: changing the boundary later re-partitions ownership.
4. Migrate services from shared keys to their own JWTs gradually; both work side by side, and the request trail attributes each call to whichever identity made it.

5Stated plainly#

• Two halves, independently switchable: provider sign-in for the admin surfaces, provider JWTs for the API, keys alive throughout.
• Account gates (domains, groups, explicit emails) refuse by name; scope gates make tokens server-specific and can grant read-only authority.
• The owner claim is the data boundary: pick it deliberately, once.
• Keep the password as break-glass; an identity provider outage should lock nobody out of their own server.