Интеграции с системами аутентификации
- Елена Мухина (Unlicensed)
- Радик Шарафиев
- Катя Копылова (Алабугина)
- Кристина Смирнова
Общие сведения
Цель модуля
Бизнес-цель использования модуля OAuth – аутентификация на платформе посредством облачного сервиса управления удостоверениями и доступом.
Доступные системы аутентификации и их официальная документация:
Microsoft Azure - Поток кода авторизации OAuth 2.0 и платформа удостоверений Майкрософт - Microsoft Entra
Keycloak - Authorization Services Guide (keycloak.org)
Оkta
AD FS
Авторизация пользователей
Переход к авторизации пользователя по технологии SSO может быть осуществлен двумя способами:
При включённой интеграции с сервисами аутентификации и при активном чек-боксе “Авторизация по логину и паролю для всех пользователей”
Пользователь переходит на страницу авторизации на платформе. На странице отображается кнопка “Войти с помощью {Provider}”, где {Provider} – название подключённого провайдера (задается в Настройках), например “Войти с помощью Okta”.
При нажатии на кнопку “Войти с помощью {Provider}” платформа автоматически перенаправляет пользователя на страницу входа подключенной системы аутентификации.
Пользователь вводит логин и пароль от учетной записи системы аутентификации.
Если пользователь с таким email найден - то система аутентификации перенаправляет пользователя Motivity на главную страницу. Если пользователь с таким email не найден, то он не может попасть на главную страницу Motivity. Ему необходимо обратиться к администратору.
При включённой интеграции с сервисами аутентификации и при НЕ активном чек-боксе “Авторизация по логину и паролю для всех пользователей”
Пользователь переходит на страницу авторизации на платформе.
Платформа автоматически перенаправляет пользователя на страницу входа подключенной системы аутентификации.
Пользователь вводит логин и пароль от учетной записи системы аутентификации.
Если пользователь с таким email найден - то система аутентификации перенаправляет пользователя Motivity на главную страницу. Если пользователь с таким email не найден, то он не может попасть на главную страницу Motivity. Ему необходимо обратиться к администратору.
Важно! На портале при использовании авторизации только посредством OAuth, пользователям смена пароля в личном кабинете недоступна.
Как выйти с платформы
Для выхода из системы в ручном режиме необходимо выполнить следующие действия:
выйти из аккаунта системы аутентификации.
выйти из Motivity через кнопку “Выход” в шапке портала.
Требования для организации своевременной поддержки пользователей
Для осуществления своевременной и оперативной поддержки пользователей администраторы портала должны иметь доступ в систему (минимум 2 учетные записи).
Если вы планируете использовать такой способ аутентификации, необходимо обсудить с вашим аккаунт-менеджером условия доступа сотрудников Motivity.
Обратите внимание: возможность авторизации не предусматривает изменение и восстановление пароля.
В текущей реализации это невозможно. В случае необходимости администраторы могут обратиться к команде разработки.
Как настроить подключение
Страница систем OAuth
Управлять аутентификацией пользователей по технологии SSO можно в Панели управления → Настройки → OAuth.
Страница содержит вкладки:
Общие настройки
Провайдеры
Логи
Вкладка Провайдеры
На вкладке отображается список заранее настроенных систем управления доступами, которые добавляются разработчиками, со следующими столбцами в строках:
Активен – отображает текущее значение чек-бокса “Активировать“, имеет значения “Да” и “Нет”
Имя провайдера - ссылка, отображает наименование системы управления доступами
Ключ провайдера - ссылка, уникальный ключ системы управления доступами
Доступные действия на странице:
Переход на страницу Редактирование настроек системы управления доступами - происходит при нажатии на “Имя провайдера” или “Ключ провайдера“
Подключение и редактирование системы OAuth
Важно! Перед подключением системы аутентификации необходимо отключить опцию “Изменение пароля пользователя” и рассылку пригласительных писем.
Что отключить | Где находится | Скриншот |
|---|---|---|
Рассылка пригласительных писем |
|
|
Опция “Изменение пароля пользователя” |
|
Далее необходимо заполнить поля указанные ниже:
Поле | Описание | Пример заполнения |
|---|---|---|
Чек-бокс Активировать |
| — |
Поля запроса по API | Client id | — |
Client secret | — | |
Auth url | Например: https://login.microsoftonline.com/{Directory ID}/oauth2/v2.0/authorize | |
Token url | Например: https://login.microsoftonline.com/{Directory ID}/oauth2/v2.0/token | |
API url (при наличии) — предустановленное поле, не подлежит изменению. | — | |
Key url (при наличии) — предустановленное поле, не подлежит изменению. | — | |
Поле Идентификатор пользователя в API |
| — |
Поле Идентификатор пользователя в системе | Используется для провайдеров:
Представляет собой выпадающий список:
| — |
Чек-бокс Активировать аутентификацию по JWT-токену |
| — |
Поле Ссылка для валидации JWT-токена |
| — |
Поле Идентификатор пользователя в JWT-токене |
| — |
Поле Уникальный идентификатор пользователя в системе для JWT-токена |
| — |
Вкладка Логи
На вкладке отображаются зафиксированные ошибки при попытке авторизации
Записи вносятся в таблицу и располагаются в хронологическом порядке по убыванию даты изменений.
Фильтрация в этом разделе не предусмотрена.
Поля в таблице могут быть разными, в зависимости от ошибки и системы управления доступами
Список возможных ошибок и причины их возникновения приведены в таблице ниже:
Ошибка | Что логируется | Возможные причины |
|---|---|---|
statesDoNotMatch | Ничего | Пользователь был переадресован в провайдер с одним State, а вернулся с другим State, который теперь не совпадает с хранящимся у нас. |
userNotFound | Ничего | По предоставленному полю пользователь в Motivity не найден. |
canNotVerifyIdToken | Ничего | Ошибка в процессе верификации Токена |
noApiField | Ничего | В ответе с данными пользователя от провайдера отсутствует поле, по которому предполагался поиск пользователя в Motivity |
noSystemField | Ничего | В Motivity отсутствует системное поле, по которому предполагается поиск пользователя |
noCode | Ничего | Ошибка связанная с логикой работы приложения в процессе попытки аутентификации пользователя. Скорее она будет записана в системные логи |
differentHosts | Ничего | Актуальна для некоторых провайдеров (например Окта). Указаны разные хосты в настройках полей |
errorFromProvider | Все данные запроса к провайдеру и его ответ, если он есть | Ошибка 4** или 5** во время обмена сообщениями между Motivity и провайдером |
idTokenIsMissing | Все данные запроса от провайдера и все Токены от провайдера. | Не найден ID Токен в данных обмена Кода на Токены с провайдером |
Ошибки авторизации
Список ошибок, которые могу возникнуть:
Текст ошибки | Пример отображения | |
|---|---|---|
Параметр state в запросе отличается от того, что в сессии | ||
Что-то пошло не так. Попробовать еще раз
| “Попробовать еще раз” – это кнопка, по нажатию на которую осуществляется переход на главную страницу платформы | |
Повторите попытку | ||
Неверные настройки | ||
Системное поле не найдено. Пожалуйста, проверьте настройки | ||
Поле API не найдено. Пожалуйста, проверьте настройки | ||
Пользователь не найден | ||
Проверьте правильность настройки полей и наличие пользователя в системе | ||
Не получилось отправить запрос к oAuth сервису. Проверьте настройки и убедитесь, что сервис доступен | ||
Ошибка обмена данными | ||
Настройка Keycloak для использования сквозной авторизации по протоколу OAuth2
Зайдите в административную панель Keycloak. Вы можете использовать ваш текущий Realm либо создать новый.
Создайте новый клиент (client) с типом OpenID Connect. Для Client ID можно использовать любое валидное имя, например oauth.
В поле Authentication flow выберите Standard flow и Direct access grants, включите Client authentication и сохраните клиент.
После сохранения, нам открываются другие настройки клиента. В Valid redirect URIs необходимо добавить адрес платформы Motivity. Сохраните клиент. Важно: адрес должен быть со слешем в конце, например, http://client.motivity.ru/
Перейдите на вкладку Credentials и убедитесь, что в поле Client Authenticator выбрана опция Client Id and Secret. Сохраните значение поля Client secret, оно понадобится для настройки Motivity.
Перейдите в настройки OAuth, которые находятся в Параметры системы -> Авторизация (вы также можете дописать путь /admin/system/auth к вашему домену).
Заполните необходимые настройки для провайдера Keycloak:
Client id - введите значение из пункта 2.
Client secret - введите значение из пункта 5.
Auth url - адрес авторизации, формируется по принципу https://{domain}/auth/realms/{RealmID}/protocol/openid-connect/auth,где domain - домен, на котором расположен Keycloak, а RealmID - ID используемого realm. Например: https://keycloak.domain.ru/auth/realms/Master/protocol/openid-connect/auth
Token url - адрес получения токена доступа. Формируется по принципу https://{domain}/auth/realms/{RealmID}/protocol/openid-connect/token
API url - Точка доступа API с информацией о пользователе. Формируется по принципу https://{domain}/auth/realms/{RealmID}/protocol/openid-connect/userinfo
Поставьте галочку в поле Активировать и нажмите сохранить.
Убедитесь, что вы выполнили все рекомендации и отключили рассылку «Пригласительное письмо» и опцию «Изменение пароля».
Перейдите в Параметры системы - Авторизация на вкладку Общие настройки и убедитесь, что опция Авторизация по логину и паролю для пользователей с ролью «Администратор» активна. Если нет, то активируйте ее. Важно: если не верно настроить авторизацию и оставить ее включенной, можно потерять доступ к панели администратора, поэтому, даже если вы не планируете сохранить доступ к панели посредствам ввода логина/пароля, то мы рекомендуем выключить эту опцию только после того, как вы убедитесь, что все работает корректно.
Уточнения
Motivity придерживается протокола OAuth2 для сквозной авторизации.
Scope, с которым Motivity обращается к Keycloack - openid.
Также стоит отметить, что Keycloak используется только для сквозной аутентификации и валидный токен доступа не хранится в Motivity, он нужен только для того, чтобы идентифицировать пользователя по полю email.
В случае возникновения ошибок, большая их часть записывается в логи. Обратите внимание, что новый пользователь не регистрируется. Если в Motivity нет пользователя с таким же email, как у пользователя в Keycloak, то произойдет ошибка «Пользователь не найден».
Настройка Microsoft Azure для использования сквозной авторизации по протоколу OAuth2
Перед настройкой системы необходимо выполнить ряд действий:
Выключить рассылку «Приглашение на платформу»:
Панель управления → Уведомления → Центр уведомлений → Приглашение на платформу
Выключить опцию Включить изменение пароля пользователя:
Панель управления → Настройки → OАuth → Общие настройки
Включить опцию Авторизация по логину и паролю для пользователей с ролью «Администратор»:
Панель управления → Настройки → OАuth → Общие настройки
После успешной настройки системы рекомендуем выключить эту опцию, чтобы не потерять доступ к Панели управления
Когда все требования выполнены, можно приступать к настройке Microsoft Azure. Для этого важно следовать инструкции:
Перейти в Azure Active Directory через https://portal.azure.com/#home
Зайти в раздел Регистрация приложений
Зарегистрировать новое приложение, выбрав Веб, и внести туда URL перенаправления (redirect URL), который является адресом вашей платформы Motivity
Адрес должен заканчиваться слэшем (/)
Пример: http://client.motivity.ru/
В Разрешения API добавить:
Разрешения Microsoft Graph: User.Read.All — из Разрешений приложения
email — из Делегированных разрешений (раздел Разрешения OpenId)
offline_access — из Делегированных разрешений (раздел Разрешения OpenId)
openid — из Делегированных разрешений (раздел Разрешения OpenId)
profile — из Делегированных разрешений (раздел Разрешения OpenId)
Во вкладке Проверка подлинности активировать опции Токены доступа и Токены ИД
Перейти во вкладку Сертификаты и секреты, создать новый секрет, скопировать его значение (оно понадобится для настроек Motivity) и сохранить
На платформе перейти в Панель управления → Настройки → OАuth → Провайдеры → Microsoft Azure (вы также можете дописать путь
/admin/system/authк вашему домену) и заполнить необходимые настройки:
Client id — идентификатор приложения, который можно посмотреть на главной странице приложения
Client secret — необходимо вставить ранее скопированное значение (см. пункт №6)
Auth url — адрес авторизации
Формируется по принципу https://login.microsoftonline.com/{Directory ID}/oauth2/v2.0/authorize, где Directory ID — идентификатор каталога, который можно посмотреть на главной странице приложения
Token url — адрес получения токена доступа
Формируется по принципу https://login.microsoftonline.com/{Directory ID}/oauth2/v2.0/token
Идентификатор пользователя в API — поле из объекта User из Microsoft Graph, с которым будет сравниваться поле Уникальный идентификатор в Motivity
Поставить галочку в поле Активировать и нажать Сохранить
Уточнения
Motivity использует протокол OAuth2 для сквозной авторизации
Scope, с которым Motivity обращается к Oauth-провайдеру — OpenID
Oauth-провайдер используется только для сквозной аутентификации. Валидный токен доступа не хранится в Motivity: он нужен только для идентификации пользователя по полю Идентификатор пользователя в API
В случае возникновения ошибок большая их часть записывается в Панели управления → Настройки → OАuth → Логи
Новый пользователь не регистрируется. Если в Motivity нет пользователя с таким же уникальным идентификатором, как у пользователя в Oauth-провайдере, то произойдет ошибка Пользователь не найден
Дополнительные настройки систем OAuth
Microsoft Azure
В настройках должно быть разрешено приложению читать данные пользователя. Для этого необходимо:
Перейти в Активную директорию → Регистрация приложений и зайти в приложение, которое используется для авторизации по протоколу OAuth
Перейти в Разрешения API и добавить разрешение User.Read или User.All (User.Read должно хватить). Разрешение находится в Microsoft Graph → Делегированные разрешения → User
Дополнительно можно добавить profile и email из OpenID
Чтобы подключить дополнительный функционал авторизации по JWT-токену, на платформе нужно:
В Панели управления → Настройки → OАuth → Провайдеры → Microsoft Azure включить опцию Активировать аутентификацию по JWT-токену
Заполнить поля:
Ссылка для валидации JWT-токена — адрес валидации JWT-токена
Формируется по принципу https://login.microsoftonline.com/{Directory ID}/discovery/v2.0/keys
Идентификатор пользователя в JWT-токене — поле из объекта User из Microsoft Graph, с которым будет сравниваться поле Уникальный идентификатор пользователя в системе для JWT-токена в Motivity
Нажать Сохранить