Единый вход (SSO) для on-premise установки

Эта страница предназначена для администраторов on-premise установки MonoChat. Она объясняет, как позволить сотрудникам входить через поставщика удостоверений (IdP) вашей компании по OpenID Connect (OIDC), например Microsoft Entra ID, Okta, Keycloak, AD FS или Google Workspace.

Единый вход настраивается для всей установки в настройках сервера, а не для отдельной организации. Учётная запись MonoChat может принадлежать нескольким организациям, и вход выполняется до выбора одной из них. Вход даёт учётную запись, но не доступ: человек видит организацию только после того, как она пригласит его и назначит ему роль.

Как работает вход

Когда кто-то нажимает кнопку SSO на странице входа, MonoChat открывает страницу входа вашего IdP во всплывающем окне. После того как человек войдёт там, IdP возвращает браузер в MonoChat с одноразовым кодом. Сервер MonoChat обменивает код на ID-токен и проверяет его, прежде чем впустить человека:

• Конечные точки и ключи подписи IdP при каждом входе считываются из его документа обнаружения, <issuer>/.well-known/openid-configuration.
• Вход использует поток authorization code с PKCE (S256), параметром state и nonce. Запрос на вход действителен 10 минут и может быть использован один раз.
• ID-токен должен быть подписан одним из ключей IdP и содержать ваш issuer (iss), ваш client ID (aud), nonce запроса и срок действия (exp), который ещё не истёк.
• ID-токен должен содержать адрес электронной почты человека (email). Вход отклоняется, если IdP сообщает, что адрес не подтверждён (email_verified: false).

1. Зарегистрируйте MonoChat у поставщика удостоверений

Создайте в своём IdP приложение (клиент) для MonoChat со следующими значениями:

Параметр в IdP	Значение
Тип приложения	Веб-приложение с секретом клиента (конфиденциальный клиент)
URI перенаправления после входа	https://<your MonoChat domain>/api/oauth/oidc/redirect
Тип гранта	Authorization code
Области (scopes)	openid email profile
Аутентификация клиента на конечной точке токена	Секрет клиента, передаваемый через HTTP Basic-аутентификацию (client_secret_basic)

Убедитесь, что ID-токен содержит claim email. Запишите client ID, секрет клиента и issuer. Issuer — это значение issuer в документе обнаружения IdP. Типичные формы:

Поставщик удостоверений	Issuer
Microsoft Entra ID	https://login.microsoftonline.com/<tenant id>/v2.0
Okta	https://<your Okta domain>/oauth2/default или https://<your Okta domain>
Keycloak	https://<your Keycloak host>/realms/<realm>
AD FS (2016 или новее)	https://<your AD FS host>/adfs
Google Workspace	https://accounts.google.com

Откройте <issuer>/.well-known/openid-configuration в браузере и скопируйте значение issuer в точности, включая завершающий /, если он есть. MonoChat никого не впустит, если значения различаются.

2. Добавьте настройки

Добавьте блоки oidc в настройки сервера и перезапустите MonoChat. Публичный блок размещается в public.oauth, секретный — в oauth:

{
  "oauth": {
    "oidc": {
      "clientSecret": "<client secret>",
      "autoCreateAccounts": true,
      "allowedEmailDomains": ["company.com"]
    }
  },
  "public": {
    "oauth": {
      "oidc": {
        "issuer": "https://login.microsoftonline.com/<tenant id>/v2.0",
        "clientId": "<client id>",
        "redirectPath": "/api/oauth/oidc/redirect",
        "scope": "openid email profile",
        "buttonLabel": "Sign in with Company SSO"
      }
    }
  }
}

Параметр	Что делает
public.oauth.oidc.issuer	Issuer из шага 1
public.oauth.oidc.clientId	Client ID из шага 1
public.oauth.oidc.redirectPath	Путь URI перенаправления из шага 1
public.oauth.oidc.scope	Области, которые запрашивает MonoChat
public.oauth.oidc.buttonLabel	Текст кнопки входа. Если пусто, показывается «Войти через SSO» на языке человека
oauth.oidc.clientSecret	Секрет клиента. Остаётся на сервере
oauth.oidc.autoCreateAccounts	true создаёт учётную запись MonoChat при первом входе человека через SSO, даже если регистрация возможна только по приглашению (public.disableSignup)
oauth.oidc.allowedEmailDomains	Через SSO могут входить только люди с адресом электронной почты в одном из этих доменов. Не указывайте, чтобы разрешить все домены

После этого кнопка SSO появится на странице входа.

Кто может войти

• Новые люди. При autoCreateAccounts: true первый вход человека через SSO создаёт его учётную запись. Без этого учётная запись создаётся, только если public.disableSignup выключен или человек входит по приглашению.
• Люди, у которых уже есть учётная запись с тем же адресом. При oauth.autoMerge: true первый вход через SSO привязывает SSO к существующей учётной записи, но только если ID-токен сообщает, что адрес подтверждён (email_verified: true). В остальных случаях, а без autoMerge всегда, MonoChat просит человека один раз войти с паролем и тогда привязывает SSO к учётной записи; принятие приглашения в организацию тоже привязывает SSO. Microsoft Entra ID и AD FS не передают email_verified, поэтому с ними оставьте вход с паролем разрешённым, пока все не привяжут SSO, или пригласите людей заново.
• Разрешённые домены. При allowedEmailDomains адрес из любого другого домена отклоняется. Для Google Workspace (issuer https://accounts.google.com) MonoChat проверяет claim hd — домен Workspace учётной записи — вместо адреса электронной почты, потому что личная учётная запись Google может использовать адрес из любого домена.

Сделайте SSO единственным способом входа

1. Установите public.auth.methods в ["oidc"]. Тогда страница входа показывает только кнопку SSO, а сервер отклоняет вход по паролю и через соцсети.
2. Пользователи root super (с ролью root super в корневой организации) по-прежнему могут войти с паролем по адресу /auth/signin?fallback=1, поэтому установка никогда не окажется заблокированной, если IdP недоступен.
3. Чтобы новые учётные записи SSO не открывали собственные организации, установите public.disableTenantCreation в true. Тогда создавать организации внутри организации смогут только люди с соответствующей ролью в ней.

Сеть

• Оставьте /api/oauth/oidc/authorize и ваш redirectPath доступными для тех, кто входит. Оба открываются в их браузере.
• Сервер MonoChat должен иметь доступ по HTTPS к документу обнаружения, конечной точке токена и набору ключей (jwks_uri) вашего IdP.

Ограничения

• Мобильное приложение MonoChat пока не поддерживает SSO. Если сделать SSO единственным способом входа, агенты не смогут войти в мобильное приложение.
• Выход из MonoChat не завершает сеанс в IdP, а выход из IdP пока не завершает сеанс в MonoChat.

Проверьте настройку

1. Откройте страницу входа и нажмите кнопку SSO. Войдите в IdP; всплывающее окно закроется, и вы войдёте в MonoChat.
2. Войдите от имени человека, у которого ещё нет учётной записи MonoChat, и убедитесь, что учётная запись создана (или вход отклонён, если вы не включили autoCreateAccounts).
3. Если вы задали allowedEmailDomains, попробуйте войти от имени человека из другого домена и убедитесь, что вход отклонён.
4. Если вы задали public.auth.methods, убедитесь, что вход по паролю отклоняется, а пользователь root super по-прежнему может войти по адресу /auth/signin?fallback=1.