SSO и SCIM
Порядок настройки входа через корпоративную учётную запись (IdP) и автоматической синхронизации пользователей.
Компания может подключить Keural к своему IdP (Okta, Microsoft Entra ID, Google Workspace и другие). После подключения сотрудники входят в Keural с корпоративными учётными записями и при первом входе автоматически присоединяются к организации.
Спецификация для администраторов IdP и разработчиков см. в разделе Спецификация интеграции SSO·SCIM.
Подготовка
| Что нужно | Зачем |
|---|---|
| Учётная запись владельца организации Keural | Изменять настройки SSO может только владелец. |
| Права администратора IdP | Приложение Keural создаётся в IdP. |
| Права на управление DNS корпоративного домена | Владение доменом подтверждается записью TXT. |
Поддерживаемые способы
| Способ | Назначение |
|---|---|
| OpenID Connect (OIDC) | Вход с корпоративной учётной записью |
| SAML 2.0 | Вход с корпоративной учётной записью. Запрос аутентификации отправляется через Redirect, ответ принимается через HTTP-POST. |
| SCIM 2.0 | Добавление или деактивация пользователей в IdP автоматически отражаются в учётных записях Keural |
Выберите OIDC или SAML. Если IdP поддерживает оба варианта, рекомендуется OIDC, так как его проще настроить.
Порядок настройки
- Подтвердите корпоративный домен
- Создайте приложение в IdP
- Введите значения в Keural и сохраните
- Включите SSO и проверьте вход
- Подключите SCIM (необязательно)
Все настройки выполняются в разделе Управление организацией → SSO.
1. Подтвердите корпоративный домен
Сначала подтвердите владение почтовым доменом, который будет использоваться для SSO. Домен, который не подтверждён, не сохраняется на шаге 3.
В разделе Домены организации введите корпоративный домен (например, acme.com) и нажмите Добавить домен.
В строке домена нажмите Подтвердить. В окне Подтвердить домен отображается значение записи TXT (keural-verify=…). Скопируйте его.
В управлении DNS добавьте для этого домена запись TXT и вставьте скопированное значение. Хост (имя): сам домен (обычно @).
Вернитесь в Keural и нажмите Подтвердить проверку. Когда в строке появится Подтверждено, домен готов. Применение изменений DNS может занять несколько десятков минут. Если проверка не прошла, повторите её позже.
Если у компании несколько доменов, добавьте и подтвердите каждый. Публичные почтовые домены, например gmail.com, использовать нельзя.
2. Создайте приложение в IdP
В верхней части настроек SSO в поле Протокол выберите OpenID Connect (OIDC) или SAML 2.0: отобразятся значения Keural для регистрации в IdP. Введите их в приложение IdP и сохраните значения, которые выдаёт IdP.
| Направление | Параметр | Описание |
|---|---|---|
| Keural → IdP | URI обратного вызова | Вставьте в URI перенаправления приложения IdP. |
| IdP → Keural | Issuer URL | Адрес издателя в IdP. |
| IdP → Keural | Client ID · Client Secret | Значения, которые IdP выдаёт при создании приложения. |
Вход выполняется только тогда, когда IdP передаёт адрес электронной почты пользователя.
| IdP | Где создать | Поле для URI обратного вызова | Issuer URL |
|---|---|---|---|
| Okta | Applications → Create App Integration → OIDC · Web Application | Sign-in redirect URIs | https://<домен Okta> |
| Microsoft Entra ID | App registrations → New registration | Redirect URI (Web) | https://login.microsoftonline.com/<ID клиента>/v2.0 |
| Google Workspace | Консоль Google Cloud → API и сервисы → Учётные данные → Идентификатор клиента OAuth (веб-приложение) | Авторизованные URI перенаправления | https://accounts.google.com |
- Microsoft Entra ID: Client Secret: значение (Value) секрета, созданного в разделе Certificates & secrets. В разделе Token configuration добавьте для ID-токена необязательное утверждение
email. - Okta: в разделе Assignments приложения укажите пользователей или группы, которые будут использовать Keural.
3. Введите значения в Keural и сохраните
- Введите значения IdP, полученные на шаге 2.
- В поле Домены электронной почты введите домен, подтверждённый на шаге 1, и разделяйте несколько доменов запятыми. При входе с адресом этого домена открывается экран входа компании.
- Задайте параметр Автоматически создавать пользователей при первом входе (JIT). Если он включён, для сотрудника без учётной записи Keural она создаётся при первом входе через SSO. Если выключен, войти могут только пользователи с существующей учётной записью.
- Нажмите Сохранить.
Для OIDC, если IdP не предоставляет стандартные адреса (discovery), введите конечные точки вручную в разделе Показать расширенные настройки. Для большинства IdP поля оставляют пустыми.
4. Включите SSO и проверьте вход
- Включите Включить SSO и нажмите Сохранить.
- Нажмите Тестовый вход. В новом окне откроется экран входа компании.
- Войдите с корпоративной учётной записью и вернитесь в Keural. Подключение завершено.
Тестовый вход работает только при включённом SSO. Если возникла проблема, выключите Включить SSO и сохраните. Пока SSO выключен, сотрудники этого домена входят по ссылке из письма.
Вход сотрудников
- Введите корпоративный адрес электронной почты на экране входа в Keural: откроется экран входа компании, после входа вы вернётесь в Keural.
- В настольном приложении вход выполняется по ссылке из письма, а не через экран входа компании.
- Сотрудник, который впервые вошёл через SSO, присоединяется к организации как Член. Роль администратора назначается в разделе Управление организацией.
В следующих случаях вход выполняется, но пользователь не присоединяется к организации автоматически.
- Все места, купленные организацией, заняты.
- Учётная запись уже принадлежит другой организации.
5. Подключите SCIM (необязательно)
Если подключить SCIM, добавление или деактивация пользователей в IdP сразу отражаются в учётных записях Keural. Настраивайте SCIM после подключения SSO.
В разделе Подготовка SCIM включите Включить подготовку SCIM.
Нажмите Выпустить токен и скопируйте токен. Токен отображается только один раз.
В настройках подготовки IdP введите SCIM Base URL (URL тенанта) и токен. Способ аутентификации: Bearer-токен.
| IdP | Где ввести |
|---|---|
| Okta | Приложение → Provisioning → SCIM connector base URL. Authentication Mode: HTTP Header |
| Microsoft Entra ID | Enterprise application → Provisioning → Automatic → Tenant URL · Secret Token |
Действия в IdP отражаются в Keural следующим образом.
| В IdP | В Keural |
|---|---|
| Назначить пользователя | Создаётся учётная запись и добавляется в организацию. Имя пользователя: адрес электронной почты. |
| Деактивировать пользователя или снять назначение | Учётная запись приостанавливается, вход блокируется. Данные не удаляются. |
| Активировать снова | Приостановка снимается. |
| Добавить в группу Keural Admins или исключить из неё | Пользователь получает роль администратора или становится членом. Владелец не меняется. |
Если токен утерян, нажмите Перевыпустить токен и введите новый токен в IdP. Прежний токен сразу перестаёт действовать.
Устранение неполадок
| Симптом | Действие |
|---|---|
| Домен электронной почты не сохраняется | Проверьте, что подтверждение домена на шаге 1 выполнено и что домен не является публичным почтовым доменом. |
| Подтверждение домена не проходит | Проверьте, что значение TXT введено полностью, начиная с keural-verify=, дождитесь применения DNS и нажмите кнопку ещё раз. |
| После нажатия «Тестовый вход» не открывается экран входа компании | Проверьте, что Включить SSO включено и настройки сохранены. |
| После входа в компанию возвращаетесь на экран входа Keural | Для OIDC проверьте URI обратного вызова, Issuer URL, Client Secret и утверждение email. Для SAML: SP EntityID, ACS URL, сертификат и атрибут email. |
| Вход отклоняется из-за отсутствия учётной записи | Параметр Автоматически создавать пользователей при первом входе (JIT) выключен. Включите его или сначала пригласите сотрудника. |
| Вход выполняется, но рабочее пространство организации не отображается | Проверьте, остались ли свободные места и не принадлежит ли учётная запись другой организации. |
| Вход не работает при открытии приложения из портала IdP (SAML) | Начинайте вход с экрана входа Keural, указав корпоративный адрес электронной почты. |
| Тест подключения SCIM не проходит | Введите Base URL и токен заново. Если токен был перевыпущен, замените его новым. |