Riferimento della configurazione SSO

Tutto ciò che è configurabile dell’accesso singolo, in un unico posto. I valori vivono nelle righe di sso_connections di global.db (a livello di server per scelta progettuale) e si modificano tramite Impostazioni → Server → Accesso single sign-on oppure le operazioni RPC sso.*. La riga salvata è l’unica fonte di verità: non esiste un percorso tramite variabili d’ambiente CC_SAML_* / CC_OIDC_* (una connessione che potrebbe arrivare da due posti è una connessione su cui la schermata delle impostazioni può essere in disaccordo).

Campi della connessione

Campo	Si applica a	Predefinito	Significato
enabled	entrambi	disattivato	gli accessi possono usare questa connessione
idpMetadataXml	SAML	—	l’XML EntityDescriptor dell’IdP (obbligatorio per attivare)
spEntityId	SAML	<origin>/saml	il nostro entity ID, fissato quando l’origine varia
emailAttribute	SAML	email	attributo che porta l’email; un NameID in forma di email è il fallback
displayNameAttribute	SAML	displayName	attributo del nome visualizzato
groupsAttribute	SAML	groups	attributo dei nomi di gruppo
clockSkewSeconds	SAML	90	scostamento consentito nella convalida della validità
allowIdpInitiated	SAML	disattivato	accetta Response non richieste (senza InResponseTo)
wantResponseSigned	SAML	disattivato	richiede una firma sulla radice della Response (le firme delle assertion sono sempre obbligatorie)
issuer	OIDC	—	URL di base dell’issuer (obbligatorio per attivare)
clientId	OIDC	—	id del client pubblico (obbligatorio per attivare)
clientSecret	OIDC	—	solo per i client confidenziali; memorizzato nel file dei segreti con permessi 0600, mai nel database — in sola scrittura via RPC (sso.getConfig riporta clientSecretPresent)
groupsClaim	OIDC	groups	claim che porta i nomi dei gruppi
defaultRole	entrambi	member	ruolo quando nessun gruppo corrisponde — mai owner
groupRoleMap	entrambi	{}	gruppo → ruolo; le mappature verso il proprietario vengono rifiutate al salvataggio
autoMember	entrambi	attivato	aggiunge automaticamente gli utenti a ogni spazio di lavoro al primo accesso
allowJit	entrambi	attivato	esegue il provisioning degli utenti sconosciuti all’accesso

Configurazione del processo

Le connessioni SSO non vengono inizializzate dall’ambiente. Un unico flag di processo rimasto riguarda il passaggio al browser, non la riga della connessione:

Variabile / flag	Significato
--web-client-url / CC_SERVER_WEB_CLIENT_URL	origine verso cui i callback SSO rimbalzano il browser (la credenziale viaggia nel frammento dell’URL). Se non impostata, il passaggio resta sulla stessa origine.

L’URL dell’issuer stesso deve essere https (http è accettato solo per gli issuer di loopback localhost, 127.0.0.1 e ::1).

Endpoint HTTP

Endpoint	Autenticazione	Scopo
GET /saml/login?relay=…	nessuna (redirect)	avvia l’accesso avviato dall’SP; relay=desktop cede il controllo all’app, relay=web-popup invia un postMessage alla scheda di connessione in attesa (che dichiara il proprio client_origin, onorato solo se la allow-list delle origini se ne fida)
POST /saml/acs	nessuna (POST dell’IdP)	l’assertion consumer — verifica, esegue il provisioning, conia la credenziale
GET /saml/metadata	nessuna	il nostro EntityDescriptor SP
GET /oidc/login?relay=… / GET /oidc/callback	nessuna	il round-trip OIDC; relay=desktop cede il controllo all’app, relay=web-popup alla scheda di connessione in attesa (stessa convenzione client_origin)
GET /auth/providers	nessuna, CORS *	la sonda della schermata di connessione: le connessioni SSO offerte (id/kind/label) + pairingEnabled
/scim/v2/Users…	Bearer (token SCIM)	Utenti create/get/list+filter/PUT/PATCH/DELETE
/scim/v2/Groups	Bearer	sola lettura; il push dei gruppi risponde 501 per scelta progettuale
/scim/v2/ServiceProviderConfig	Bearer	documento delle capacità

Operazioni RPC

Tutte le operazioni sso.* hanno ambito server e sono riservate al proprietario del server (l’operatore dell’installazione, ServerAuthority.serverOwner). Possedere uno spazio di lavoro non basta; il solo abbinamento non le concede mai.

Operazione	Scopo
sso.getConfig	la connessione salvata per un tipo
sso.saveConfig	convalida, salva e applica a caldo
sso.status	flag di attivazione/configurazione, presenza del token SCIM, origine canonica
sso.testConnection	verifica una connessione senza il round-trip del browser (SAML: parsing dei metadati + costruzione dell’AuthnRequest; OIDC: discovery dell’issuer), con valori opzionali non ancora salvati mostrati sullo schermo
sso.spMetadata	emette l’EntityDescriptor SP per un’origine
sso.setPairingEnabled	consente/vieta l’abbinamento manuale (codici invito, chiavi di abbinamento); il rifiuto di disattivarlo quando non esiste una connessione SSO funzionante protegge dal blocco dell’accesso
sso.sessionPolicy	legge l’età massima della credenziale del dispositivo e il timeout di inattività dell’installazione (minuti; 0 = non impostato)
sso.setSessionPolicy	imposta quei limiti; applicati al controllo del dispositivo, non pubblicizzati ai client
sso.scimRegenerateToken	genera e restituisce il token bearer SCIM (una sola volta)

Codici di errore di convalida

I fallimenti di cc_saml_verify_response portano un codice stabile:

Codice	Significato
signature	firma mancante/non attendibile/manomessa, oppure algoritmo/trasformazione non consentiti
expired	fuori da NotBefore/NotOnOrAfter (oltre lo scostamento)
audience	la restrizione di audience non ci nomina
destination	la destinazione della Response non è il nostro ACS
request_match	InResponseTo non corrisponde a una richiesta in sospeso, oppure non richiesta mentre è disattivato
issuer	l’issuer non è l’IdP configurato
recipient	il destinatario della conferma del subject non è il nostro ACS
malformed	errore a livello di XML/schema
status	lo stato riportato dall’IdP non era Success
invalid / internal	qualunque altro caso / errore di cucitura

Superfici del database

• sso_connections (global.db) — una riga per tipo, TRA SPAZI DI LAVORO PER SCELTA PROGETTUALE.
• users.sso_subject + users.sso_issuer — il pinning del subject del provider, univoco per (issuer, subject) tramite un indice parziale.
• users.deactivated_at — la marcatura di disattivazione SCIM.
• Il token bearer SCIM e il segreto client OIDC vivono nel file dei segreti con permessi 0600, mai nel database.