Dokumentacja referencyjna konfiguracji SSO

Wszystko, co da się skonfigurować w logowaniu jednokrotnym, w jednym miejscu. Wartości znajdują się w wierszach sso_connections w global.db (z założenia obejmują cały serwer) i są edytowane przez Ustawienia → Serwer → Logowanie jednokrotne albo operacje RPC sso.*. Zapisany wiersz jest jedynym źródłem prawdy — nie istnieje ścieżka zmiennych środowiskowych CC_SAML_* / CC_OIDC_* (połączenie, które mogłoby przyjść z dwóch miejsc, to takie, co do którego ekran ustawień może się nie zgadzać).

Pola połączenia

Pole	Dotyczy	Domyślnie	Znaczenie
enabled	oba	wyłączone	logowania mogą korzystać z tego połączenia
idpMetadataXml	SAML	—	XML EntityDescriptor dostawcy tożsamości (wymagany, aby włączyć)
spEntityId	SAML	<origin>/saml	nasz identyfikator encji, przypinany, gdy origin się zmienia
emailAttribute	SAML	email	atrybut przenoszący adres e-mail; zapasowym rozwiązaniem jest NameID w kształcie adresu e-mail
displayNameAttribute	SAML	displayName	atrybut nazwy wyświetlanej
groupsAttribute	SAML	groups	atrybut nazw grup
clockSkewSeconds	SAML	90	dopuszczalne odchylenie zegara przy walidacji okresu ważności
allowIdpInitiated	SAML	wyłączone	akceptuj niezamówione odpowiedzi (bez InResponseTo)
wantResponseSigned	SAML	wyłączone	wymagaj podpisu koperty odpowiedzi (podpisy asercji są zawsze wymagane)
issuer	OIDC	—	bazowy adres URL wystawcy (wymagany, aby włączyć)
clientId	OIDC	—	identyfikator klienta publicznego (wymagany, aby włączyć)
clientSecret	OIDC	—	wyłącznie dla klientów poufnych; przechowywany w pliku sekretów z uprawnieniami 0600, nigdy w bazie danych — tylko do zapisu przez RPC (sso.getConfig zwraca clientSecretPresent)
groupsClaim	OIDC	groups	claim przenoszący nazwy grup
defaultRole	oba	member	rola, gdy żadna grupa nie pasuje — nigdy owner
groupRoleMap	oba	{}	grupa → rola; mapowania na właściciela są odrzucane przy zapisie
autoMember	oba	włączone	automatycznie dodawaj użytkowników do każdego obszaru roboczego przy pierwszym logowaniu
allowJit	oba	włączone	aprowizuj nieznanych użytkowników przy logowaniu

Konfiguracja procesu

Połączenia SSO nie są zasiewane ze środowiska. Jedna pozostała flaga procesu dotyczy przekazania przeglądarki, a nie wiersza połączenia:

Zmienna / flaga	Znaczenie
--web-client-url / CC_SERVER_WEB_CLIENT_URL	origin, na który wywołania zwrotne SSO przekierowują przeglądarkę (poświadczenie jedzie we fragmencie adresu URL). Nieustawiona zachowuje przekazanie w obrębie tego samego originu.

Sam adres URL wystawcy musi używać protokołu https (http jest akceptowany wyłącznie dla wystawców działających na interfejsie loopback: localhost, 127.0.0.1 i ::1).

Punkty końcowe HTTP

Punkt końcowy	Uwierzytelnianie	Przeznaczenie
GET /saml/login?relay=…	brak (przekierowanie)	rozpoczyna logowanie inicjowane przez SP; relay=desktop przekazuje sterowanie aplikacji, relay=web-popup wysyła wiadomość przez postMessage do oczekującej karty łączenia (która deklaruje swój client_origin, uwzględniany tylko wtedy, gdy lista dozwolonych originów mu ufa)
POST /saml/acs	brak (POST od IdP)	konsument asercji — weryfikuje, aprowizuje, generuje
GET /saml/metadata	brak	nasz EntityDescriptor SP
GET /oidc/login?relay=… / GET /oidc/callback	brak	runda OIDC; relay=desktop przekazuje sterowanie aplikacji, relay=web-popup — oczekującej karcie łączenia (ta sama konwencja client_origin)
GET /auth/providers	brak, CORS *	sonda ekranu łączenia: oferowane połączenia SSO (id/kind/label) + pairingEnabled
/scim/v2/Users…	Bearer (token SCIM)	tworzenie/pobieranie/listowanie z filtrowaniem/PUT/PATCH/DELETE użytkowników
/scim/v2/Groups	Bearer	tylko do odczytu; wypychanie grup odpowiada 501 z założenia
/scim/v2/ServiceProviderConfig	Bearer	dokument możliwości

Operacje RPC

Wszystkie operacje sso.* mają zasięg serwera i są dostępne wyłącznie dla właściciela serwera (operatora instalacji, ServerAuthority.serverOwner). Posiadanie obszaru roboczego nie wystarcza; samo parowanie nigdy ich nie przyznaje.

Operacja	Przeznaczenie
sso.getConfig	zapisane połączenie danego rodzaju
sso.saveConfig	waliduje, zapisuje trwale i stosuje na żywo
sso.status	flagi włączenia/skonfigurowania, obecność tokenu SCIM, kanoniczny origin
sso.testConnection	testuje połączenie bez pełnej rundy przez przeglądarkę (SAML: parsowanie metadanych + budowa AuthnRequest; OIDC: discovery wystawcy), z opcjonalnymi niezapisanymi wartościami z ekranu
sso.spMetadata	zwraca EntityDescriptor SP dla danego originu
sso.setPairingEnabled	zezwala na ręczne parowanie (kody zaproszeń, klucze parowania) lub zabrania go; odmowa wyłączenia go, dopóki nie istnieje działające połączenie SSO, chroni przed zablokowaniem dostępu
sso.sessionPolicy	odczytuje maksymalny wiek poświadczeń urządzenia i limit bezczynności instalacji (w minutach; 0 = nieustawione)
sso.setSessionPolicy	ustawia te ograniczenia; egzekwowane przy sprawdzaniu poświadczeń urządzenia, nieujawniane klientom
sso.scimRegenerateToken	generuje i zwraca token bearer SCIM (jednorazowo)

Kody błędów walidacji

Awarie cc_saml_verify_response niosą stabilny kod:

Kod	Znaczenie
signature	brakujący, niezaufany lub zmodyfikowany podpis albo niedozwolony algorytm/transformacja
expired	poza NotBefore/NotOnOrAfter (ponad dopuszczalne odchylenie)
audience	ograniczenie odbiorcy nie wskazuje nas
destination	miejsce docelowe odpowiedzi nie jest naszym ACS
request_match	InResponseTo nie pasuje do oczekującego żądania albo odpowiedź jest niezamówiona, gdy jest to zabronione
issuer	wystawca nie jest skonfigurowanym IdP
recipient	odbiorca potwierdzenia podmiotu nie jest naszym ACS
malformed	błąd na poziomie XML/schematu
status	status zgłoszony przez IdP nie był Success
invalid / internal	wszystko inne / awaria na styku

Powierzchnie bazy danych

• sso_connections (global.db) — jeden wiersz na rodzaj, Z ZAŁOŻENIA WSPÓLNY DLA WSZYSTKICH OBSZARÓW ROBOCZYCH.
• users.sso_subject + users.sso_issuer — przypięcie podmiotu dostawcy, unikalne dla pary (issuer, subject) dzięki indeksowi częściowemu.
• users.deactivated_at — znacznik dezaktywacji przez SCIM.
• Token bearer SCIM i sekret klienta OIDC znajdują się w pliku sekretów z uprawnieniami 0600, nigdy w bazie danych.