Довідка з конфігурації SSO

Усе, що можна налаштувати для єдиного входу, — в одному місці. Значення зберігаються в рядках sso_connections бази global.db (за задумом — на весь сервер) і редагуються через Налаштування → Сервер → Єдиний вхід або RPC-операції sso.*. Збережений рядок — єдине джерело істини: шляху через змінні середовища CC_SAML_* / CC_OIDC_* немає (з’єднання, яке могло б надходити з двох місць, — це з’єднання, з яким екран налаштувань може розійтися).

Поля з’єднання

Поле	Застосовується до	Типово	Значення
enabled	обидва	вимк.	входи можуть використовувати це з’єднання
idpMetadataXml	SAML	—	XML EntityDescriptor вашого IdP (потрібно, щоб увімкнути)
spEntityId	SAML	<origin>/saml	наш entity ID, зафіксований на випадок зміни джерела
emailAttribute	SAML	email	атрибут з адресою електронної пошти; запасний варіант — NameID у формі адреси
displayNameAttribute	SAML	displayName	атрибут відображуваного імені
groupsAttribute	SAML	groups	атрибут назв груп
clockSkewSeconds	SAML	90	допуск на розбіжність під час перевірки часу життя
allowIdpInitiated	SAML	вимк.	приймати незапрошені відповіді Response (без InResponseTo)
wantResponseSigned	SAML	вимк.	вимагати підпис у корені Response (підписи Assertion обов’язкові завжди)
issuer	OIDC	—	базова URL-адреса видавця (потрібно, щоб увімкнути)
clientId	OIDC	—	ідентифікатор публічного клієнта (потрібно, щоб увімкнути)
clientSecret	OIDC	—	лише для конфіденційних клієнтів; зберігається у файлі секретів із правами 0600, ніколи не в базі даних — через RPC доступний лише для запису (sso.getConfig повідомляє clientSecretPresent)
groupsClaim	OIDC	groups	клейм із назвами груп
defaultRole	обидва	member	роль, коли жодна група не зіставлена, — ніколи owner
groupRoleMap	обидва	{}	група → роль; зіставлення з роллю owner відхиляються під час збереження
autoMember	обидва	увімк.	автоматично додавати користувачів до кожного робочого простору під час першого входу
allowJit	обидва	увімк.	створювати невідомих користувачів під час входу

Конфігурація процесу

З’єднання SSO не заповнюються із середовища. Єдиний прапорець процесу, що залишився, стосується передавання браузеру, а не рядка з’єднання:

Змінна / прапорець	Значення
--web-client-url / CC_SERVER_WEB_CLIENT_URL	джерело, на яке SSO-зворотні виклики перекидають браузер (облікові дані їдуть у фрагменті URL). Якщо не задано, передавання залишається в межах того самого джерела.

Сама URL-адреса видавця має бути https (http приймають лише для видавців на loopback: localhost, 127.0.0.1 і ::1).

HTTP-кінцеві точки

Кінцева точка	Автентифікація	Призначення
GET /saml/login?relay=…	немає (перенаправлення)	розпочати вхід, ініційований SP; relay=desktop передає керування застосунку, relay=web-popup надсилає postMessage вкладці підключення, що очікує (вона оголошує свій client_origin, який беруть до уваги, лише якщо йому довіряє список дозволених джерел)
POST /saml/acs	немає (POST від IdP)	споживач твердження — перевіряє, створює користувача, випускає облікові дані
GET /saml/metadata	немає	наш SP EntityDescriptor
GET /oidc/login?relay=… / GET /oidc/callback	немає	обмін OIDC; relay=desktop передає керування застосунку, relay=web-popup — вкладці підключення, що очікує (та сама умовність client_origin)
GET /auth/providers	немає, CORS *	проба екрана підключення: запропоновані з’єднання SSO (id/kind/label) + pairingEnabled
/scim/v2/Users…	Bearer (токен SCIM)	Users: створення/отримання/список+фільтр/PUT/PATCH/DELETE
/scim/v2/Groups	Bearer	лише читання; push груп за задумом відповідає 501
/scim/v2/ServiceProviderConfig	Bearer	документ можливостей

RPC-операції

Усі операції sso.* мають область сервера й доступні лише власнику сервера (операторові інсталяції, ServerAuthority.serverOwner). Володіння робочим простором цього не дає; саме лише парування ніколи їх не надає.

Операція	Призначення
sso.getConfig	збережене з’єднання для певного типу
sso.saveConfig	перевірити, зберегти й застосувати на льоту
sso.status	прапорці «увімкнено/налаштовано», наявність токена SCIM, канонічне джерело
sso.testConnection	перевірити з’єднання без обміну через браузер (SAML: розбір метаданих + побудова AuthnRequest; OIDC: виявлення видавця), з необов’язковими незбереженими значеннями з екрана
sso.spMetadata	випустити SP EntityDescriptor для джерела
sso.setPairingEnabled	дозволити/заборонити ручне парування (коди запрошень, ключі парування); відмова вимкнути його, поки немає жодного робочого з’єднання SSO, захищає від блокування доступу
sso.sessionPolicy	прочитати максимальний вік облікових даних пристрою та час простою для інсталяції (у хвилинах; 0 = не задано)
sso.setSessionPolicy	задати ці межі; застосовуються під час перевірки пристрою, клієнтам не повідомляються
sso.scimRegenerateToken	згенерувати й повернути bearer-токен SCIM (один раз)

Коди помилок перевірки

Невдачі cc_saml_verify_response супроводжуються стабільним кодом:

Код	Значення
signature	підпис відсутній/недовірений/підроблений або заборонений алгоритм/перетворення
expired	поза межами NotBefore/NotOnOrAfter (за межами розбіжності)
audience	обмеження аудиторії не вказує на нас
destination	призначення відповіді — не наш ACS
request_match	InResponseTo не збігається із запитом, що очікує, або відповідь незапрошена, коли це заборонено
issuer	видавець — не налаштований IdP
recipient	одержувач підтвердження суб’єкта — не наш ACS
malformed	збій на рівні XML/схеми
status	статус, повідомлений IdP, — не Success
invalid / internal	усе інше / збій на стику

Поверхні бази даних

• sso_connections (global.db) — один рядок на тип, ЗА ЗАДУМОМ НАСКРІЗНИЙ ДЛЯ ВСІХ РОБОЧИХ ПРОСТОРІВ.
• users.sso_subject + users.sso_issuer — закріплення суб’єкта провайдера, унікальне для (issuer, subject) через частковий індекс.
• users.deactivated_at — позначка деактивації SCIM.
• Bearer-токен SCIM і секрет клієнта OIDC зберігаються у файлі секретів із правами 0600, ніколи не в базі даних.