Рецепты интеграции Zentro Identity

Как подключить к Zentro Identity типовые системы: вход сотрудников через Zentro (SSO по OpenID Connect) и вход в Zentro через корпоративный каталог (Active Directory).

Система	Что получаем	Рецепт
GitLab	вход через Zentro, MFA Zentro вместо 2FA GitLab, администраторы по правам	gitlab.md
Grafana	вход через Zentro, роли Viewer / Editor / Admin по правам Zentro	grafana.md
Nextcloud	вход через Zentro, группы по правам Zentro	nextcloud.md
1С:Предприятие	вход в веб-клиент через Zentro (8.3.14+)	1c.md
Битрикс24 (коробка)	вход через Zentro модулем OpenID Connect	bitrix24.md
Active Directory	сотрудники входят в Zentro паролем AD (и дальше во все приложения)	active-directory.md

Ниже — общее для всех OIDC-приложений. https://id.example.com — адрес вашей установки Zentro (PUBLIC_BASE_URL).

Адреса Zentro

Что	Значение
Discovery (большинству систем достаточно его)	https://id.example.com/.well-known/openid-configuration
Issuer	https://id.example.com
Authorization endpoint	https://id.example.com/oidc/authorize
Token endpoint	https://id.example.com/oidc/token
Userinfo	https://id.example.com/oidc/userinfo
JWKS	https://id.example.com/.well-known/jwks.json
Выход (end session)	https://id.example.com/oidc/end_session

Поддерживается Authorization Code (+ PKCE S256, + refresh); implicit flow не поддерживается — в настройках приложения выбирайте response_type=code. Подпись токенов — RS256 по умолчанию.

Зарегистрировать приложение (OIDC-клиент)

Админка → Приложения → Добавить, или API (нужен админ с подтверждённым вторым фактором):

curl -X POST https://id.example.com/api/v1/admin/oauth-clients -H "Authorization: Bearer $TOKEN" -d '{
  "name": "GitLab",
  "redirect_uris": ["https://gitlab.example.com/users/auth/openid_connect/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "scopes": ["openid", "email", "profile"],
  "token_endpoint_auth_method": "client_secret_basic",
  "first_party": true,
  "permission_namespace": "GITLAB"
}'

• В ответе — client_id и client_secret. Секрет показывается один раз — сразу перенесите его в приложение (потеряли — ротация секрета в карточке приложения).
• first_party: true — приложение вашей организации: экран согласия «разрешить доступ к данным» не показывается.
• permission_namespace — пространство прав приложения: права пользователя вида GITLAB:*:ADMIN уходят приложению в claim permissions (по нему назначают роли / администраторов, см. рецепты). Роли с этими правами заводятся в админке (Роли) или мастером сервиса одной операцией — POST /api/v1/admin/services (описание — документация API установки, https://id.example.com/docs).
• После создания — «Проверить» в карточке приложения (POST /api/v1/admin/oauth-clients/{client_id}/check): согласованность настроек и доступность адресов приложения.

Что Zentro отдаёт приложению (claims)

Claim	Когда	Где
sub	всегда — постоянный id пользователя (pairwise-клиенту — свой для каждого приложения)	id_token, userinfo
email, email_verified	scope email и у пользователя есть почта	id_token, userinfo
preferred_username	scope profile — логин пользователя	id_token, userinfo
permissions	у приложения задан permission_namespace — права пользователя в этом пространстве	id_token, userinfo
amr	методы входа: pwd, otp (код), hwk (ключ/passkey), mfa — при втором факторе	id_token
acr	уровень входа: AAL1 (пароль), AAL2 (второй фактор), AAL3 (аппаратный ключ)	id_token

Отдельного claim с ФИО (name) нет: для отображаемого имени используйте preferred_username или email.

email_verified — подтвердил ли пользователь почту (самостоятельная регистрация / смена почты по ссылке). У пользователя, заведённого администратором, почта не подтверждена, пока он сам её не подтвердит: приложения, которые доверяют только подтверждённой почте (привязка аккаунтов по email), такого пользователя по почте не свяжут.

Выход

end_session_endpoint поддерживается (с id_token_hint / post_logout_redirect_uri из списка клиента). Чтобы выход из Zentro завершал сессию и в приложении — backchannel_logout_uri (сервер приложения) или frontchannel_logout_uri (iframe в браузере), если приложение их поддерживает.

Тариф

Число приложений со входом пользователей ограничено тарифом (Free — 2, Бизнес — 20, Корпоративный — без ограничений); внешние каталоги (AD/LDAP/внешний OIDC) — с тарифа Бизнес.