# SSO для Ainergy: инструкция по подключению (OpenID Connect, Keycloak)

## Что получится

Сотрудники с адресами @ainergy.ru и @itglobal.com вводят рабочую почту на notes.vtorum.net, нажимают «Войти через Ainergy» и входят паролем от Windows на странице ADFS ITGLOBAL. Vtorum подключается к серверу входа Ainergy по стандарту OpenID Connect; сервер входа — программа Keycloak (realm ainergy), а учётные записи Keycloak берёт из ADFS fs.itglobal.com. Сотрудники попадают в пространство «Ainergy (Орг)» с ролью по группам Vtorum-Ainergy-*. Учётная запись при первом входе создаётся сама, в категории Simple Corporate.

Схема: Vtorum —OpenID Connect→ Keycloak (keycloak.is.ainergy.pro, realm ainergy) → ADFS fs.itglobal.com (AD). Keycloak и ADFS — программы, умеющие несколько стандартов; Vtorum работает только по OpenID Connect и только с Keycloak. Отдельное приложение в ADFS для Vtorum не нужно.

Общая инструкция по корпоративному входу — в документации Vtorum: «Корпоративный вход (SSO) в пространство компании». Здесь — только настройки для Ainergy, по версии 5.33.32. Состояние на 29.09.2026: шаги 1, 3 и 4 выполнены; блокер — шаг 2, в токене нет групп.

## Шаг 1. Vtorum: подготовить владельца пространства (системный администратор Vtorum) — выполнено

- Пространство — «Ainergy (Орг)», владелец — Владимир Молодык (vladimir.molodik@ainergy.ru).
- Выполнено: у владельца категория Corporate. Корпоративный вход — пакет «Интеграции пространства», он есть в Corporate и God; без него подключение не сохраняется никому, даже системному администратору. Где меняется: Настройки → Администрирование → Пользователи и квоты.
- Выполнено: Владимир отмечен владельцем пространства компании и настраивает подключение сам.
## Шаг 2. Keycloak Ainergy: клиент OpenID Connect vtorum (администратор Keycloak)

По ответам администратора клиент vtorum уже создан, и ограничение по группам настроено. Сверить:

- Client authentication — On (конфиденциальный клиент), Standard flow — On, PKCE S256 — Vtorum передаёт его всегда.
- Valid redirect URIs: https://notes.vtorum.net/api/auth/sso/oidc/callback и https://dev.vtorum.net/api/auth/sso/oidc/callback.
- Valid post logout redirect URIs: https://notes.vtorum.net — это ответ на вопрос «уточнить у Vtorum».
- Web origins: https://notes.vtorum.net.
- Client scopes: добавить offline_access. Без него токен продления живёт только в пределах сессии Keycloak, и проверка отзыва доступа раз в 30 минут перестанет работать через полчаса бездействия.
- Mapper «Group Membership» — НЕ НАСТРОЕН, это блокер: в токене тестового клиента demo-login поля groups нет, а без групп Vtorum никого не пустит («Нет доступа: учётной записи не выдана ни одна группа Vtorum»). Clients → vtorum → Client scopes → vtorum-dedicated → Add mapper → By configuration → Group Membership: Name и Token Claim Name — groups, Full group path — Off, Add to ID token — On, Add to userinfo — On.
- Группы: Vtorum-Ainergy-Admins, Vtorum-Ainergy-Editors, Vtorum-Ainergy-Viewers, сотрудники включены по нужной роли.
- В токене должны быть email (@ainergy.ru или @itglobal.com) и name — из AD через ADFS. На тестовом клиенте demo-login оба приходят (given_name и family_name при этом переставлены местами — на вход не влияет). Проверить на клиенте vtorum: Clients → vtorum → Client scopes → Evaluate → Scope parameter: openid profile email offline_access, Users: сотрудник → Generated ID token. Должно быть "groups": ["Vtorum-Ainergy-…"] без косой черты в начале.
- Отключение учётной записи в AD должно доходить до Keycloak синхронизацией: тогда продление токена вернёт invalid_grant, и Vtorum снимет доступ.
- Передать во Vtorum client_secret клиента vtorum — не по почте: через менеджер паролей или одноразовую ссылку.
## Шаг 3. Vtorum: завести подключение (владелец пространства или системный администратор) — выполнено 29.09.2026, «Проверить» прошла без ошибки

Настройки → Мои пространства → «Ainergy (Орг)» → вкладка «Интеграции» → «Корпоративный вход (SSO)». Заполнить:

- Программа сервера входа — Keycloak. Стандарт один — OpenID Connect; выбор программы только подставляет умолчания (claim с группами, префикс, scope).
- Название для экрана входа — Ainergy. Сейчас стоит «Ainergy корпоративный вход», и кнопка читается «Войти через Ainergy корпоративный вход» — лучше сократить до «Ainergy».
- Адрес сервера входа — https://keycloak.is.ainergy.pro, Realm — ainergy. Vtorum соберёт issuer https://keycloak.is.ainergy.pro/realms/ainergy сам.
- Идентификатор клиента — vtorum, Секрет клиента — полученный от администратора Keycloak.
- Claim со списком групп — groups (подставляется выбранной программой Keycloak).
- Префикс групп Vtorum — Vtorum-Ainergy- (вместо предложенного Vtorum-): остальные группы отбрасываются.
- Домены компании: ainergy.ru и itglobal.com — по одному в строке. Оба домена приходят в email из ADFS; домен, которого нет в списке, не войдёт.
- Группы и роли, по строке «группа = роль»:
- Vtorum-Ainergy-Admins = admin
- Vtorum-Ainergy-Editors = editor
- Vtorum-Ainergy-Viewers = viewer
- Роль без подходящей группы — «Вход запрещён», как просил администратор: нет группы Vtorum-Ainergy-* — нет входа.
- Срок сессии — рекомендуется 8 часов; сейчас стоит 30 — поменять, если это не сознательный выбор. Адрес возврата после выхода — https://notes.vtorum.net.
- «Корпоративный вход включён» — включить. «Только корпоративный вход» — пока выключить.
- Нажать «Подключить», затем «Проверить»: Vtorum прочитает описание сервера и покажет адреса входа, токенов, ключей и выхода. Ошибка — почти всегда недоступность keycloak.is.ainergy.pro из интернета или опечатка в адресе или realm.
## Шаг 4. Vtorum: подтвердить домены (только системный администратор Vtorum) — выполнено 29.09.2026

ainergy.ru и itglobal.com подтверждены. Системный администратор делает это в Настройки → Администрирование → Корпоративный вход: там подключения всех пространств, у каждого домена кнопки «Подтвердить» / «Снять подтверждение» и «Освободить». Владелец пространства видит состояние в карточке подключения, но менять его не может.

- Без подтверждения новые сотрудники входят, но у кого уже есть учётная запись Vtorum с тем же адресом (например, vladimir.molodik@ainergy.ru), тот через Keycloak не войдёт.
- itglobal.com подтверждать осознанно: подтверждение позволяет Keycloak Ainergy подхватывать существующие учётные записи Vtorum с адресами @itglobal.com.
## Шаг 5. Проверка входа

- Сотрудник из группы Vtorum-Ainergy-Editors: вводит почту на notes.vtorum.net → «Войти через Ainergy» → входит на ADFS → попадает в «Ainergy (Орг)» с ролью «Редактирование». Он появляется в карточке в списке «Сотрудники, входившие через каталог».
- Сотрудник без групп Vtorum-Ainergy-*: Keycloak отвечает «Access denied». Если всё же пропустил — Vtorum показывает «Нет доступа: учётной записи не выдана ни одна группа Vtorum».
- Тестовую учётную запись отключить в AD: после синхронизации с Keycloak Vtorum снимет доступ не позже чем через 30–60 минут, сессии корпоративного входа погаснут.
- Выход из Vtorum уводит на страницу выхода Keycloak и возвращает на notes.vtorum.net.
## Шаг 6. После проверки

- Включить «Только корпоративный вход»: для ainergy.ru и itglobal.com закрываются код на почту и пароль. Системный администратор Vtorum входит всегда.
- Существующие участники пространства с этими доменами после этого входят только через Keycloak.
## Что нужно от Ainergy

- client_secret клиента vtorum — защищённым каналом.
- Настроить mapper Group Membership в клиенте vtorum (см. шаг 2) и прислать Generated ID token клиента vtorum. Подтвердить, что в клиенте есть offline_access, post-logout URI https://notes.vtorum.net и redirect URI для dev.vtorum.net.
- Тестовые учётные записи: одна в группе Vtorum-Ainergy-Editors, одна без групп Vtorum-Ainergy-*, одна, которую можно отключить во время проверки.