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

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 unsolicited Responses (no InResponseTo)
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

Process configuration

SSO connections are not seeded from the environment. One remaining process flag is about the browser handoff, not the connection row:

Variable / flag	Meaning
--web-client-url / CC_SERVER_WEB_CLIENT_URL	origin SSO callbacks bounce the browser to (credential rides the URL fragment). Unset keeps the handoff same-origin.

The issuer URL itself must be https (http is accepted for loopback issuers localhost, 127.0.0.1, and ::1 only).

HTTP endpoints

Endpoint	Auth	Purpose
GET /saml/login?relay=…	none (redirect)	start SP-initiated login; relay=desktop hands off to the app, relay=web-popup postMessages the waiting connect tab (which declares its client_origin, honoured only when the origin allow-list trusts it)
POST /saml/acs	none (IdP POST)	the assertion consumer — verifies, provisions, mints
GET /saml/metadata	none	our SP EntityDescriptor
GET /oidc/login?relay=… / GET /oidc/callback	none	the OIDC round-trip; 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

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

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

• 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.deactivated_at — the SCIM deactivation stamp.
• The SCIM bearer token and the OIDC client secret live in the 0600 secrets file, never the database.