SSO configuration reference
Everything configurable about single sign-on, in one place. Values live in
the sso_connections rows of global.db (server-wide by design), edited
via Settings → Server → Single sign-on or the sso.* RPC ops. The
saved row is the only source of truth — there is no CC_SAML_* /
CC_OIDC_* environment path (a connection that could arrive from two
places is one the settings screen can disagree with).
Connection fields
Section titled “Connection fields”| Field | Applies to | Default | Meaning |
|---|---|---|---|
enabled |
both | off | logins may use this connection |
idpMetadataXml |
SAML | — | the IdP’s EntityDescriptor XML (required to enable) |
spEntityId |
SAML | <origin>/saml |
our entity ID, pinned when the origin varies |
emailAttribute |
SAML | email |
attribute carrying the email; an email-shaped NameID is the fallback |
displayNameAttribute |
SAML | displayName |
display-name attribute |
groupsAttribute |
SAML | groups |
group-names attribute |
clockSkewSeconds |
SAML | 90 | lifetime-validation skew allowance |
allowIdpInitiated |
SAML | off | accept valid unsolicited Responses (no InResponseTo); the browser must claim a short-lived grant before receiving a recipient-sealed credential |
wantResponseSigned |
SAML | off | require a Response-root signature (assertion signatures are always required) |
issuer |
OIDC | — | issuer base URL (required to enable) |
clientId |
OIDC | — | public-client id (required to enable) |
clientSecret |
OIDC | — | confidential clients only; stored in the 0600 secrets file, never the database — write-only over RPC (sso.getConfig reports clientSecretPresent) |
groupsClaim |
OIDC | groups |
claim carrying group names |
defaultRole |
both | member |
role when no group maps — never owner |
groupRoleMap |
both | {} |
group → role; owner mappings are refused at save |
autoMember |
both | on | auto-add users to every workspace on first login |
allowJit |
both | on | provision unknown users at login |
Account matching
Section titled “Account matching”SsoProvisioner resolves a login in this order and never by username:
(users.sso_issuer, users.sso_subject)equal to the login’s issuer and subject (SAML NameID / OIDCsub).- An account whose address equals the login’s email, only when both ends
vouch for it: the provider (OIDC
email_verified: true; a missing claim is not a vouch; a signed SAML assertion always is) and the account (users.email_verified). Addresses are stored trimmed and lower-cased and compared that way, and a verified address matches only when exactly one account holds it verified; two holders match nothing (logged without the address), and no account can be verified for a case variant of an address another account holds verified. - Otherwise a new account when
allowJitis on; a refusal when it is off.
users.email_verified is set by an SSO login or a SCIM push that carries the
address, or by the server owner with users.vouchEmail (Settings → Server →
People → Confirm email, audited user.email_vouched). The owner’s own
profile edit vouches for their own address. Any other profile edit, and any
address typed on an invite, leaves it unverified, and editing an address
clears the flag. A vouched login that creates an account takes the address
from accounts that only typed it (audited user.email_unvouched_cleared),
never from one that holds it verified; in that case the new account gets no
address.
A matched account already pinned to a different subject or issuer refuses the
login with This account is already linked to a different SSO identity. A
deactivated account refuses with This account has been deactivated.
Process configuration
Section titled “Process configuration”SSO connections are not seeded from the environment. One remaining process flag chooses where the browser opens the web client after an SSO callback:
| Variable / flag | Meaning |
|---|---|
--web-client-url / CC_SERVER_WEB_CLIENT_URL |
web-client URL for a sealed credential handoff; unset keeps same-origin handoff (only useful if the web client is served there). For a web-popup login, an allowed client_origin from the initiating tab takes precedence. |
The issuer URL itself must be https (http is accepted for loopback
issuers localhost, 127.0.0.1, and ::1 only). Use trusted TLS for the
IdP callback and web-client host: the page that generates the recipient key
and its delivered JavaScript are part of the trust boundary. HTTPS protects
that bootstrap; after pairing, direct and relayed /rpc sessions both
require Noise encryption and a pinned server identity.
HTTP endpoints
Section titled “HTTP endpoints”| Endpoint | Auth | Purpose |
|---|---|---|
GET /saml/login?relay=…&handoff_key=… |
none (redirect) | start SP-initiated login with a client-held X25519 recipient key; relay=desktop hands off to the app, relay=web-popup postMessages the waiting connect tab (its client_origin is honoured only when the origin allow-list trusts it) |
POST /saml/acs |
none (IdP POST) | verify the assertion and provision the user; SP-initiated login seals the minted device credential to the initiating recipient key; allowed unsolicited SAML yields a browser-bound claim instead |
POST /saml/claim |
same-origin browser grant | redeem a single-use unsolicited SAML grant with its cookie and a fresh handoff_key; returns a recipient-sealed credential, never a plaintext pairing key |
GET /saml/metadata |
none | our SP EntityDescriptor |
GET /oidc/login?relay=…&handoff_key=… / GET /oidc/callback |
none | the OIDC round-trip; login requires the client-held recipient key; relay=desktop hands off to the app, relay=web-popup to the waiting connect tab (same client_origin convention) |
GET /auth/providers |
none, CORS * |
the connect-screen probe: offered SSO connections (id/kind/label) + pairingEnabled |
/scim/v2/Users… |
Bearer (SCIM token) | Users create/get/list+filter/PUT/PATCH/DELETE |
/scim/v2/Groups |
Bearer | read-only; group push answers 501 by design |
/scim/v2/ServiceProviderConfig |
Bearer | capability document |
For SP-initiated SAML and OIDC, the login-start URL requires a valid
handoff_key (the initiating client’s X25519 public key). The server retains
that key with the pending sign-in and seals the minted device credential at
the callback using ephemeral X25519, HKDF-SHA256 and AES-256-GCM bound to the
server origin. Desktop handoff uses control-center://pair, same-tab web
handoff uses a URL fragment, and web-popup postMessages to the allowed
client_origin if provided (otherwise the configured web-client URL or
callback origin). The sealed envelope, not a plaintext pairing key, travels
in that fragment or popup message. The initiating client retains the
corresponding private key to open it. This envelope is distinct from the
mandatory Noise session established after pairing.
An IdP-initiated SAML Response (when enabled) has no initiating recipient.
Instead, the ACS sets a five-minute, HttpOnly, SameSite=Strict browser cookie
and presents an Open web client / Open desktop app choice. That page
generates a fresh recipient key and posts its public half and grant handle to
POST /saml/claim from the same origin. Claim requires the matching cookie
and origin (a CSRF boundary), consumes the grant once and returns only a
recipient-sealed envelope. The subsequent web/desktop fragment carries that
envelope and the recipient’s private-key material so the destination client
can open it, not a plaintext device credential. A different browser or
expired grant cannot redeem it. The destination web-client origin can access
the fragment and decrypt it; a compromised callback page or web-client origin
can steal credentials. Encryption does not make untrusted served code safe.
RPC ops
Section titled “RPC ops”All sso.* ops are server-scoped and gated to the server owner (the
install’s operator, ServerAuthority.serverOwner). Owning a workspace is
not enough; pairing alone never grants them.
| Op | Purpose |
|---|---|
sso.getConfig |
the saved connection for a kind |
sso.saveConfig |
validate, persist and live-apply |
sso.status |
enabled/configured flags, SCIM token presence, canonical origin |
sso.testConnection |
test a connection short of the browser round-trip (SAML: metadata parse + AuthnRequest build; OIDC: issuer discovery), with optional unsaved on-screen values |
sso.spMetadata |
emit the SP EntityDescriptor for an origin |
sso.setPairingEnabled |
allow/forbid manual pairing (invite codes, pairing keys); refusing to disable it while no working SSO connection exists guards against lockout |
sso.sessionPolicy |
read the install’s device-credential max age and idle timeout (minutes; 0 = unset) |
sso.setSessionPolicy |
set those bounds; enforced at the device check, not advertised to clients |
sso.scimRegenerateToken |
generate + return the SCIM bearer token (once) |
Validation error codes
Section titled “Validation error codes”cc_saml_verify_response failures carry a stable code:
| Code | Meaning |
|---|---|
signature |
missing/untrusted/tampered signature, or a disallowed algorithm/transform |
expired |
outside NotBefore/NotOnOrAfter (beyond skew) |
audience |
audience restriction does not name us |
destination |
response destination is not our ACS |
request_match |
InResponseTo does not match a pending request, or unsolicited while disallowed |
issuer |
issuer is not the configured IdP |
recipient |
subject-confirmation recipient is not our ACS |
malformed |
XML/schema-level failure |
status |
IdP-reported status was not Success |
invalid / internal |
anything else / seam failure |
Database surfaces
Section titled “Database surfaces”sso_connections(global.db) — one row per kind, CROSS-WORKSPACE BY DESIGN.users.sso_subject+users.sso_issuer— the provider-subject pin, unique per(issuer, subject)via a partial index.users.email_verified: whether the account’s address may match an SSO login or a SCIM push (see Account matching).users.deactivated_at— the SCIM deactivation stamp.- The SCIM bearer token and the OIDC client secret live in the 0600 secrets file, never the database.