Skip to content

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

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

SsoProvisioner resolves a login in this order and never by username:

  1. (users.sso_issuer, users.sso_subject) equal to the login’s issuer and subject (SAML NameID / OIDC sub).
  2. 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.
  3. Otherwise a new account when allowJit is 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.

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.

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.

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)

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