Referencia de configuración de SSO

Todo lo configurable del inicio de sesión único, en un solo sitio. Los valores viven en las filas de sso_connections de global.db (de ámbito de servidor por diseño) y se editan desde Ajustes → Servidor → Inicio de sesión único o con las operaciones RPC sso.*. La fila guardada es la única fuente de verdad: no hay ninguna vía por variables de entorno CC_SAML_* / CC_OIDC_* (una conexión que pudiera llegar desde dos sitios es una con la que la pantalla de ajustes puede discrepar).

Campos de la conexión

Campo	Se aplica a	Predeterminado	Significado
enabled	ambas	desactivado	los inicios de sesión pueden usar esta conexión
idpMetadataXml	SAML	—	el XML EntityDescriptor del IdP (obligatorio para activarla)
spEntityId	SAML	<origin>/saml	nuestro id de entidad, fijado cuando el origen varía
emailAttribute	SAML	email	atributo que lleva el correo electrónico; un NameID con forma de correo es la alternativa
displayNameAttribute	SAML	displayName	atributo de nombre para mostrar
groupsAttribute	SAML	groups	atributo de nombres de grupo
clockSkewSeconds	SAML	90	margen de desfase al validar la vigencia
allowIdpInitiated	SAML	desactivado	aceptar respuestas no solicitadas (sin InResponseTo)
wantResponseSigned	SAML	desactivado	exigir una firma en la raíz de la respuesta (las firmas de aserción siempre son obligatorias)
issuer	OIDC	—	URL base del emisor (obligatoria para activarla)
clientId	OIDC	—	id de cliente público (obligatorio para activarla)
clientSecret	OIDC	—	solo para clientes confidenciales; se guarda en el archivo de secretos con permisos 0600, nunca en la base de datos — solo escritura por RPC (sso.getConfig informa de clientSecretPresent)
groupsClaim	OIDC	groups	reclamación que lleva los nombres de grupo
defaultRole	ambas	member	rol cuando ningún grupo se asigna — nunca owner
groupRoleMap	ambas	{}	grupo → rol; las asignaciones a owner se rechazan al guardar
autoMember	ambas	activado	añadir automáticamente a los usuarios a cada espacio de trabajo en el primer inicio de sesión
allowJit	ambas	activado	aprovisionar usuarios desconocidos al iniciar sesión

Configuración del proceso

Las conexiones SSO no se siembran desde el entorno. Queda un flag de proceso, y no se refiere a la fila de la conexión sino al traspaso al navegador:

Variable / flag	Significado
--web-client-url / CC_SERVER_WEB_CLIENT_URL	origen al que las devoluciones de llamada SSO redirigen el navegador (la credencial viaja en el fragmento de la URL). Si no se define, el traspaso se mantiene en el mismo origen.

La propia URL del emisor debe ser https (http solo se acepta para emisores de loopback: localhost, 127.0.0.1 y ::1).

Endpoints HTTP

Endpoint	Autenticación	Propósito
GET /saml/login?relay=…	ninguna (redirección)	iniciar el inicio de sesión iniciado por el SP; relay=desktop se lo entrega a la aplicación y relay=web-popup envía un postMessage a la pestaña de conexión en espera (que declara su client_origin, admitido solo si la lista de orígenes permitidos confía en él)
POST /saml/acs	ninguna (POST del IdP)	el consumidor de aserciones: verifica, aprovisiona y emite
GET /saml/metadata	ninguna	nuestro EntityDescriptor de SP
GET /oidc/login?relay=… / GET /oidc/callback	ninguna	el ciclo de ida y vuelta de OIDC; relay=desktop se lo entrega a la aplicación y relay=web-popup a la pestaña de conexión en espera (misma convención de client_origin)
GET /auth/providers	ninguna, CORS *	la sonda de la pantalla de conexión: las conexiones SSO ofrecidas (id/kind/label) + pairingEnabled
/scim/v2/Users…	Bearer (token SCIM)	Users: crear/obtener/listar+filtrar/PUT/PATCH/DELETE
/scim/v2/Groups	Bearer	solo lectura; el envío de grupos responde 501 por diseño
/scim/v2/ServiceProviderConfig	Bearer	documento de capacidades

Operaciones RPC

Todas las operaciones sso.* tienen ámbito de servidor y están restringidas al propietario del servidor (el operador de la instalación, ServerAuthority.serverOwner). Ser propietario de un espacio de trabajo no basta, y el mero emparejamiento nunca las concede.

Operación	Propósito
sso.getConfig	la conexión guardada para un tipo
sso.saveConfig	validar, persistir y aplicar en vivo
sso.status	indicadores de activado/configurado, presencia del token SCIM, origen canónico
sso.testConnection	probar una conexión sin llegar al ciclo de ida y vuelta por el navegador (SAML: análisis de metadatos + construcción de AuthnRequest; OIDC: descubrimiento del emisor), con valores opcionales en pantalla aún sin guardar
sso.spMetadata	emitir el EntityDescriptor de SP para un origen
sso.setPairingEnabled	permitir o prohibir el emparejamiento manual (códigos de invitación, claves de emparejamiento); negarse a desactivarlo mientras no exista ninguna conexión SSO funcional protege contra un bloqueo de acceso
sso.sessionPolicy	leer la antigüedad máxima de las credenciales de dispositivo de la instalación y el tiempo de inactividad máximo (en minutos; 0 = sin definir)
sso.setSessionPolicy	fijar esos límites; se aplican en la comprobación del dispositivo, no se anuncian a los clientes
sso.scimRegenerateToken	generar y devolver el token bearer SCIM (una sola vez)

Códigos de error de validación

Los fallos de cc_saml_verify_response llevan un código estable:

Código	Significado
signature	firma ausente, no confiable o manipulada, o un algoritmo o transformación no permitido
expired	fuera de NotBefore/NotOnOrAfter (más allá del desfase)
audience	la restricción de audiencia no nos nombra
destination	el destino de la respuesta no es nuestra ACS
request_match	InResponseTo no coincide con ninguna solicitud pendiente, o es una respuesta no solicitada mientras están desactivadas
issuer	el emisor no es el IdP configurado
recipient	el destinatario de la confirmación del sujeto no es nuestra ACS
malformed	fallo a nivel de XML o de esquema
status	el estado informado por el IdP no era Success
invalid / internal	cualquier otra cosa / fallo en la costura

Superficies de base de datos

• sso_connections (global.db) — una fila por tipo, TRANSVERSAL A LOS ESPACIOS DE TRABAJO POR DISEÑO.
• users.sso_subject + users.sso_issuer — la fijación del sujeto del proveedor, única por (issuer, subject) mediante un índice parcial.
• users.deactivated_at — la marca de desactivación de SCIM.
• El token bearer SCIM y el secreto de cliente de OIDC viven en el archivo de secretos con permisos 0600, nunca en la base de datos.