Справочник по конфигурации SSO

Всё, что можно настроить в едином входе, — в одном месте. Значения живут в строках sso_connections базы global.db (по замыслу общих для всего сервера) и редактируются через Настройки → Сервер → Единый вход или RPC-операции sso.*. Сохранённая строка — единственный источник истины: пути через переменные окружения CC_SAML_* / CC_OIDC_* нет (подключение, которое могло бы прийти из двух мест, — это подключение, с которым экран настроек способен разойтись).

Поля подключения

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

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

Подключения SSO не задаются из окружения. Один оставшийся флаг процесса относится к передаче браузеру, а не к строке подключения:

Переменная / флаг	Значение
--web-client-url / CC_SERVER_WEB_CLIENT_URL	origin, на который SSO-колбэки перенаправляют браузер (учётные данные передаются во фрагменте URL). Если не задан, передача остаётся на том же origin.

Сам URL издателя обязан быть https (http принимается только для издателей на loopback-адресах localhost, 127.0.0.1 и ::1).

HTTP-эндпоинты

Эндпоинт	Аутентификация	Назначение
GET /saml/login?relay=…	нет (перенаправление)	запустить вход, инициированный SP; relay=desktop передаёт управление приложению, relay=web-popup отправляет postMessage ожидающей вкладке подключения (она объявляет свой client_origin, который учитывается, только если ему доверяет список разрешённых origin)
POST /saml/acs	нет (POST от IdP)	потребитель утверждений: проверяет, провизионит, выпускает учётные данные
GET /saml/metadata	нет	наш EntityDescriptor SP
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)	создание, получение, список с фильтром, PUT, PATCH и DELETE пользователей
/scim/v2/Groups	Bearer	только чтение; передача групп отвечает 501 намеренно
/scim/v2/ServiceProviderConfig	Bearer	документ возможностей

RPC-операции

Все операции sso.* относятся к серверу и доступны только владельцу сервера (оператору установки, ServerAuthority.serverOwner). Владения рабочим пространством недостаточно; одно лишь сопряжение их никогда не даёт.

Операция	Назначение
sso.getConfig	сохранённое подключение для вида
sso.saveConfig	проверить, сохранить и применить на лету
sso.status	флаги включено/настроено, наличие токена SCIM, канонический origin
sso.testConnection	проверить подключение без похода в браузер (SAML: разбор метаданных + сборка AuthnRequest; OIDC: обнаружение издателя), с необязательными несохранёнными значениями из формы
sso.spMetadata	выдать EntityDescriptor SP для origin
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 и никогда — в базе данных.