Вход через корпоративный каталог (внешние IdP)

Инструкция для администратора Zentro: как подключить внешний провайдер входа — корпоративный OIDC, Keycloak, LDAP, Active Directory, — чтобы люди входили в Zentro своим рабочим логином.

Два вида провайдеров

Вид	Типы	Как входит человек	Где работает
С переходом	OAuth2 / OIDC, Keycloak	Кнопка «Войти через …» → страница провайдера → обратно	Кабинет и панель — если у фронта заданы публичные адреса BFF (Единый вход, шаг 4)
По паролю	LDAP, Active Directory	Логин и пароль каталога в форме Zentro — Zentro проверяет их у каталога	Кабинет и панель

Провайдер с переходом возвращает человека в то приложение, где он начал вход, — если у фронта заданы публичные адреса BFF (ACCOUNT_PUBLIC_URL, PORTAL_PUBLIC_URL) и оба адреса возврата есть в списке провайдера. Иначе — на первый адрес списка.

Прежде чем начать

Нужна роль IDENTITY_ADMIN (или права IDENTITY:IDP:*) и второй фактор.
От владельцев каталога:
- OIDC / Keycloak: адрес провайдера (issuer), зарегистрированный для Zentro клиент — client_id и секрет; в провайдере как адрес возврата укажите адреса возврата кабинета и панели — https://account.example.com/bff/auth/idp/<имя>/callback и https://admin.example.com/bff/auth/idp/<имя>/callback (<имя> — то, что впишете в поле «Имя» ниже);
- LDAP / AD: адрес сервера и порт, сервисная учётка для поиска (bind DN и пароль), где искать людей (base DN) и как (фильтр).

Шаг 1. Добавить провайдера

Внешние IdP → Добавить провайдера.

Общее

Поле	Что вписать
Имя	Латиницей, без пробелов: `corp`. Входит в адрес возврата — потом не меняется
Тип	OAuth2 / OIDC, Keycloak, LDAP или Active Directory
Провижининг	JIT — учётка Zentro создаётся при первом входе; Только заранее заведённые — входят только те, кого завели (или привязали) в Zentro; Отключён — новых не создаём
Авто-привязка по подтверждённому email	Если в Zentro уже есть человек с той же подтверждённой почтой — вход через провайдера попадёт в его учётку. Без галки такой вход упрётся в «учётная запись уже существует — нужна привязка»

OAuth2 / OIDC, Keycloak

Поле	Что вписать
Issuer	Адрес провайдера — откуда Zentro возьмёт его настройки: `https://sso.corp.example.com/realms/main`
Client ID, Client secret	Из регистрации Zentro у провайдера. Секрет назад не показывается
Scopes	`openid email profile`
Redirect URI	Оба адреса, по одному в строке: `https://account.example.com/bff/auth/idp/corp/callback` (первым — на случай, если публичные адреса BFF не заданы) и `https://admin.example.com/bff/auth/idp/corp/callback`. Те же, что указаны у провайдера
Разрешённые домены email	`corp.example.com` — входить могут только адреса этих доменов. Пусто — любые
Использовать PKCE	Оставьте включённым, если провайдер поддерживает
Доверять второму фактору провайдера	См. ниже

LDAP, Active Directory

Поле	Что вписать
Хост, порт	`ldap.corp.example.com`, `636` (LDAPS) или `389` (STARTTLS)
TLS	LDAPS или STARTTLS. «Без TLS» — пароли пойдут по сети открытым текстом: только для теста
Bind DN, Bind password	Сервисная учётка только для чтения: `cn=zentro,ou=service,dc=corp,dc=example,dc=com`
Base DN	Где искать людей: `ou=people,dc=corp,dc=example,dc=com`
Фильтр пользователя	`%s` — то, что человек ввёл как логин: `(uid=%s)`, для AD — `(sAMAccountName=%s)`

«Проверить связь» в строке провайдера — Zentro попробует достучаться (для OIDC — прочитать настройки провайдера, для LDAP — войти сервисной учёткой). «✓ Связь есть» — можно пробовать вход.

Второй фактор провайдера

По умолчанию вход через провайдера — только пароль (AAL1), даже если провайдер спрашивал код. Такой человек войдёт в кабинет, но для админских разделов ему придётся завести второй фактор ещё и в Zentro.

«Доверять второму фактору провайдера» (только OIDC / Keycloak) — Zentro поверит тому, что провайдер сообщает о способе входа: ключ — как AAL3, другой второй фактор — как AAL2. Включайте только для своего провайдера, которому доверяете: эти сведения приходят от него, и скомпрометированный провайдер выдаст себе любой уровень. В списке такие отмечены «MFA провайдера». LDAP/AD о втором факторе ничего не сообщают — у них галки нет.

Шаг 2. Проверить вход

Экран входа кабинета — появилась кнопка «Войти через …» (для LDAP/AD — «Войти через …» с формой логина).
Войдите рабочей учёткой. С JIT учётка Zentro создастся сама; её видно в Пользователях.
Выдайте ей роли (Пользователи) — провайдер удостоверяет личность, права дают роли Zentro.

Если провайдер недоступен, экран входа сам прячет его кнопку и пишет почему — с кнопкой «всё равно попробовать».

Привязка к существующей учётке

Если у человека уже есть учётка Zentro (с паролем, ролями) и он хочет входить через провайдера:

сам — кабинет → Связанные аккаунты → Привязать аккаунт: выбрать провайдера и войти в него;
администратор — карточка пользователя → Внешняя привязка (Пользователи, «Внешние аккаунты»): человек подтверждает кодом из письма;
автоматически — галка «Авто-привязка по подтверждённому email» у провайдера.

Управлять

«Изменить» в строке провайдера: статус (Отключён — кнопка входа пропадает, привязки остаются), провижининг, адреса возврата, домены, новый client secret (пусто — не меняется), доверие второму фактору. Адрес провайдера, тип и LDAP-параметры меняются только пересозданием.

«Удалить» — провайдер исчезает с экрана входа; кто входил только через него, войти не сможет, пока ему не дадут пароль Zentro (сброс пароля, Пользователи).

Частые ошибки

Что видно	Причина	Что сделать
«✗ Нет связи»	Неверный issuer / хост, порт, TLS или сервисная учётка	Сверить с владельцами каталога; сервер Identity должен видеть провайдера по сети
Провайдер ругается на адрес возврата	Адрес у провайдера и в Zentro не совпадает	Одинаковый, с `/bff`: `https://account…/bff/auth/idp/<имя>/callback`
«Учётная запись с таким адресом уже существует — нужна привязка»	Почта занята учёткой Zentro	Привязать (сам или администратор) или включить авто-привязку
«Создание учётной записи через этого провайдера отключено»	Провижининг не JIT, а человека нет в Zentro	Завести его заранее или включить JIT
Вход через провайдера в панели уводит в кабинет	У фронта не задан `PORTAL_PUBLIC_URL` — Identity вернул на первый адрес	Задать публичные адреса BFF (Установка панели и кабинета, шаг 2)
«Вход через этого провайдера здесь не настроен»	Адреса возврата этого приложения нет в Redirect URI	Добавить адрес приложения в Redirect URI (и у провайдера)
Вошёл через провайдера, а админские разделы закрыты	Вход через провайдера — AAL1	Второй фактор в Zentro или доверие второму фактору провайдера
Кнопки провайдера нет на экране входа	Провайдер отключён или недоступен	Статус; «Проверить связь»