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

This content is not available in your language yet.

Как подключить к 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) — с тарифа Бизнес.