Как подключить сервис к Zentro Identity

Инструкция для администратора Zentro. Сервис подключается мастером Сервисы → Подключить сервис: роли, приложения и API заводятся одной операцией. Дальше — выдать роли людям, передать команде сервиса адреса и секреты, при необходимости донастроить приложения.

Пример по ходу текста — панель RHM. Подставляйте имя своего сервиса.

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

Нужна роль IDENTITY_ADMIN (или права IDENTITY:SERVICE:*, IDENTITY:ROLE:*, IDENTITY:OAUTH_CLIENT:*, IDENTITY:OAUTH_RESOURCE:*).
Нужен второй фактор. Подключение — привилегированная операция. Панель сама попросит подтвердить себя (ключом, кодом или паролем) и продолжит. Если порог поднят до AAL3 — подтверждать придётся ключом (passkey).
Узнайте у команды сервиса:
- адреса, куда вернуть пользователя после входа — по одному на каждую среду (https://rhm.example.com/auth/callback), и куда вернуть после выхода;
- есть ли у сервиса свой API, в который будут ходить приложения, — и его адрес;
- нужен ли бэкенду сервиса доступ без пользователя (фоновые задачи, интеграции);
- какие права понимает сервис (RHM:ENV:WRITE, …) — роли строятся из них.
Среды заводятся отдельно. Dev и prod — разные инсталляции Identity, всё ниже повторяется в каждой.

Шаг 1. Подключить сервис мастером

Сервисы → Подключить сервис. Одна страница с секциями; справа — сводка «Будет создано» и кнопки.

Сервис

Поле	Что вписать
Название	Человекочитаемое: `RHM Panel`
Ключ (пространство прав)	Короткое имя заглавными латинскими буквами, 2–32: `RHM`. Предлагается из названия (кириллица переводится в латиницу) — поправьте на короткое. Потом не меняется: это префикс всех прав сервиса, по нему Identity решает, какие права пользователя отдать сервису. `IDENTITY` занято
Описание	По желанию

Роли

Уже заполнен шаблон — просмотр, работа, администрирование: RHM_VIEWER (RHM:*:VIEW), RHM_OPERATOR (RHM:*:VIEW, RHM:*:WRITE), RHM_ADMIN (RHM:*:*). Поменяйте права на те, что понимает сервис, лишние роли уберите, недостающие добавьте («+ роль»). Сменили ключ — префикс в ролях шаблона поменяется сам.

Формат права — СЕРВИС:РЕСУРС:ДЕЙСТВИЕ, заглавными; сегмент может быть целиком * («любой»): RHM:*:VIEW, RHM:*:*. Права другого пространства в роли сервиса не принимаются — панель подсветит их сразу.

Приложения

«+ для людей» — панель или сайт сервиса, куда входят через Zentro:
- Redirect URI — адреса возврата после входа, по одному в строке; совпадение точное (схема, хост, порт, путь);
- Post-logout redirect URI — куда вернуть после выхода;
- Передавать приложению права пользователя в RHM — оставьте включённым, иначе сервис не узнает, что человеку можно;
- Приложение организации — не спрашивать согласие — только для своих приложений: пользователь не увидит «Разрешить». Стороннему сервису не ставьте — согласие защищает пользователя;
- Публичный клиент — только если у приложения нет своего бэкенда (целиком в браузере или на телефоне): тогда у него не будет секрета.
«+ для сервиса» — бэкенд сервиса, который ходит без пользователя. Нужно только название (rhm-panel-m2m).

Выход (back-/front-channel), тип subject и прочее настраивается после подключения, в строке приложения (шаг 5).

API сервиса

Если у сервиса есть свой API — «+ API»: название и адрес (audience) — идентификатор API в токене (https://rhm.example.com/api или rhm-api). Команда сервиса будет проверять его в каждом токене. У приложений в сервисе появится выбор, как они ходят в этот API:

Выбор	Что уйдёт в токене
Все права	все права пользователя в `RHM` (по умолчанию — у приложений для людей)
Только чтение	только `…:VIEW`, даже если у пользователя есть запись
Без прав (адресат)	прав нет, только доступ — так ходят сервисные приложения (по умолчанию у них)
Не ходит	токена для этого API приложение не получит

Проверить и подключить

Ошибки видно сразу — у своей строки и счётом в сводке; пока они есть, кнопки закрыты.
«Проверить» — сервер проверит всё на настоящей базе и ничего не создаст. Если что-то не пройдёт (например, адрес API уже занят), ошибка появится у нужной строки.
«Подключить» — всё создаётся одной операцией: либо всё, либо ничего.

После подключения панель покажет у каждого приложения client_id, секрет — один раз и сводку «Что передать команде сервиса».

Секрет больше не покажется нигде. Скопируйте сразу и передайте команде сервиса защищённым каналом: не в чат и не в тикет открытым текстом. Потеряли или он утёк — «Новый секрет» в строке приложения (OAuth-клиенты): client_id, привязки и согласия сохранятся.

Если после «Подключить» пропала связь и при повторе панель пишет «Сервис с ключом RHM уже есть» — сервис подключился, но ответ с секретами потерялся. Откройте его в Сервисах и выпустите приложениям новые секреты.

Шаг 2. Выдать роли людям

Пользователи → карточка пользователя → Назначить роль.

Выберите роль сервиса (RHM_OPERATOR).
JIT — если доступ нужен на время: через сколько минут роль истечёт. Пусто — бессрочно.

Права пользователя в сервисе — объединение всех его активных ролей. Снятая или истёкшая роль перестаёт действовать сразу для живых запросов сервиса и не позже срока токена доступа (по умолчанию 15 минут) для уже выданных токенов. Сколько людей носит каждую роль — в карточке сервиса.

Шаг 3. Передать команде сервиса

Сводка «Что передать команде сервиса» у каждого приложения — с кнопкой копирования:

Приложение:        rhm-panel
Issuer:            https://id.example.com                                ← адрес Identity этой среды
Discovery:         https://id.example.com/.well-known/openid-configuration
Client ID:         cid_…
Client secret:     передаётся отдельно
Redirect URI:      https://rhm.example.com/auth/callback
Пространство прав: RHM

Секрета в сводке нет намеренно — её можно переслать, секрет передайте отдельно. Допишите список ролей сервиса. Если у сервиса есть API — команде API его адрес (audience) и пространство прав; приложение, которое в него ходит, запрашивает токен с resource=<адрес>.

Как сервису проверять токены — Подключение приложения, «Что делает команда приложения».

Шаг 4. Проверить

Сервисы → карточка → «Проверить все приложения»: панель по очереди проверит настройки и адреса каждого приложения сервиса и покажет сводку; «подробнее» — что именно не так (как «Проверить» в Приложениях).
Откройте сервис и нажмите «Войти» — должен открыться экран входа Zentro.
Войдите пользователем с ролью сервиса. Если приложение не помечено как «приложение организации», появится экран согласия с названием приложения — «Разрешить».
Вы вернулись в сервис, и он видит ваши права.
Снимите роль у пользователя — сервис перестаёт пускать (сразу или в течение срока токена, по умолчанию 15 минут).

Шаг 5. Управлять подключённым сервисом

Сервисы → сервис. В карточке — роли (с числом носителей), приложения и API (кто в него ходит и с какими правами).

Добавить в сервис — «+ роль», «+ приложение», «+ API» в своей секции: новое создаётся сразу в пространстве сервиса.
Включить существующее — для того, что заводили вручную до мастера: роли, все права которых в пространстве сервиса; приложения без пространства прав или с ним; API с этим пространством.
Вывести из сервиса — элемент остаётся, но при отключении сервиса уже не удалится.
Переименовать — название и описание. Ключ не меняется.
Донастроить приложение или API — ссылки внизу секций ведут на OAuth-клиенты (выход, тип subject, свои потолки прав, новый секрет) и Ресурсы OAuth.

Приостановить сервис

«Приостановить сервис» в карточке — обратимая остановка: приложения и API сервиса выключаются, вход и выдача токенов прекращаются сразу (уже выданные токены живут до конца своего срока, по умолчанию до 15 минут). Роли, привязки и согласия остаются. «Возобновить сервис» включает всё обратно — в том числе приложения, которые вы выключили вручную ещё до приостановки. Пока сервис стоит, у названия видно «приостановлен».

Отключить сервис

«Отключить сервис» в карточке. Панель покажет, что уйдёт: роли (и у скольких людей сразу пропадут права), приложения, API. Для подтверждения введите ключ сервиса.

Отключение — одной операцией и необратимо: сессии приложений и согласия пользователей отзываются сразу, выданные токены — тоже; API, которые проверяют токен у себя, могут пускать по уже выданному до конца его срока (по умолчанию до 15 минут). Подключить сервис заново с тем же ключом, именами ролей и адресом API можно — секреты у приложений будут новые.

Чтобы временно остановить одно приложение, не трогая сервис, — OAuth-клиенты → Изменить → Статус: Отключён: вход и токены прекращаются сразу, включили обратно — работает как было.

Если приложение скомпрометировано (утёк секрет, ведёт себя странно), а останавливать сервис нельзя — OAuth-клиенты → «Отозвать токены»: все выходят из приложения, выданное ему перестаёт действовать, дальше оно получает токены заново. Подробно — Подключение приложения, «Управлять приложением».

Тонкая настройка по отдельным экранам

Всё, что делает мастер, можно сделать и вручную, — это нужно для настроек, которых в мастере нет.

OAuth-клиенты → Изменить в строке приложения:

Поле	Зачем
Тип subject	`public` — у пользователя один идентификатор во всех сервисах (нужно, если сервис сопоставляет людей с другими системами); `pairwise` — у каждого сервиса свой псевдоним. Меняется только пересозданием приложения
Back-channel logout URI	Адрес, куда Identity сообщит о выходе пользователя. Нужен `https` и публичный адрес
Разрешить доставку во внутреннюю сеть	Если адрес выхода внутренний (`http://rhm-bff:3000/…`). Работает, только когда задана настройка `oidc.backchannel_private_cidrs`
Front-channel logout URI	Ненадёжно (браузеры блокируют). Лучше back-channel
Scopes	`openid profile email`: `openid` обязателен, `profile` — логин, `email` — почта

OAuth-клиенты → Ресурсы в строке приложения — свой потолок прав к API, например RHM:ENV:VIEW вместо «всё / только чтение». Потолок действует со следующего токена.

Ресурсы OAuth — выключить API временно (токены перестанут выдаваться, привязки сохранятся), посмотреть, кто в него ходит («Клиенты»). Адрес и пространство прав API не меняются.

Сроки токенов сервиса — в карточке сервиса: срок токена доступа, простой и предел сессий его приложений. Приложения сервиса с «Наследуется» берут их отсюда, сервис с «Наследуется» — из настроек установки (Настройки, «Сроки входа и токенов»); рядом показано действующее значение. Приложение может задать свои, API — ограничить срок токенов к себе. Подробно — Подключение приложения, «Сроки токенов».

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

Что видно	Причина	Что сделать
После входа ошибка про redirect_uri у сервиса	Адрес возврата не совпал с зарегистрированным	Сверить Redirect URI посимвольно: `http`/`https`, порт, слэш в конце
Вход обрывается на пустой странице	У Identity не настроен адрес экрана входа (`OIDC_AUTHORIZE_UI_URL`)	Вопрос к тем, кто разворачивал Identity
Сервис не видит прав пользователя	У приложения выключено «Передавать права» или у человека нет роли сервиса	Шаг 1 (приложения), шаг 2
`invalid_target` у сервиса	Приложение не ходит в этот API («Не ходит») или API выключен	Карточка сервиса → API; Ресурсы OAuth — статус
«право не из пространства сервиса»	В роли право другого сервиса	Права роли — только `RHM:…`
«Сервис с ключом … уже есть»	Ключ занят другим сервисом — или вы уже подключили этот, а ответ потерялся	Другой ключ; или найти сервис в списке и выпустить новые секреты
«Доставка во внутреннюю сеть не настроена…»	Галка «внутренняя сеть» без настройки `oidc.backchannel_private_cidrs`	Задать сети: Настройки, ссылка есть прямо в ошибке
«Роль с таким именем уже есть»	Имя занято	Другое имя, или включить существующую роль в сервис
Секрет потерян или утёк	Секрет показывается один раз	«Новый секрет» в строке приложения; при утечке — «перестаёт работать сразу»
Панель просит подтвердить себя	Операция привилегированная	Подтвердить ключом или кодом, операция продолжится