Интеграции с системами аутентификации
- Елена Мухина (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
Важно! Перед подключением системы аутентификации необходимо отключить опцию “Изменение пароля пользователя” и рассылку пригласительных писем.
Что отключить | Где находится | Скриншот |
|---|---|---|
Рассылка пригласительных писем |
|
|
Опция “Изменение пароля пользователя” |
|
Далее необходимо заполнить поля указанные ниже:
Поле | Описание | Пример заполнения |
|---|---|---|
Чек-бокс Активировать |
| — |
Поля запроса по 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 |
| — |
Поле Идентификатор пользователя в системе | Используется для провайдеров:
Представляет собой выпадающий список:
| — |
Кнопка Сохранить | При нажатии на кнопку происходит сохранение настроек системы управления доступами и закрытие страницы. | — |
Вкладка Логи
На вкладке отображаются зафиксированные ошибки при попытке авторизации
Записи вносятся в таблицу и располагаются в хронологическом порядке по убыванию даты изменений.
Фильтрация в этом разделе не предусмотрена.
Поля в таблице могут быть разными, в зависимости от ошибки и системы управления доступами
Список возможных ошибок и причины их возникновения приведены в таблице ниже:
Ошибка | Что логируется | Возможные причины |
|---|---|---|
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
Перейдите в Azure Active Directory через https://portal.azure.com/#home
Перейдите в «Регистрация приложений»
Зарегистрируйте новое приложение, выбрав Веб, внесите туда URL перенаправления (redirect URL), который является адресом вашей платформы Motivity.
Важно: адрес должен быть со слешем в конце, например http://client.motivity.ru/В «Разрешения API» добавьте разрешения Microsoft Graph: User.Read.All из Резрешений приложения и email, offline_access, openid, profile из Делегированных разрешений (раздел «Разрешения OpenId»)
На вкладке «Проверка подлинности» активируйте опции «Токены доступа» и «Токены ИД»
Перейдите во вкладку «Сертификаты и секреты», создайте новый секрет и копируйте его Значение, оно понадобятся для настроек Motivity, и сохраните их.
Перейдите в настройки OAuth, которые находятся в Параметры системы -> Авторизация (вы также можете дописать путь /admin/system/auth к вашему домену). Перейдите в провайдер Microsoft Azure.
Заполните необходимые настройки:
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
В случае возникновения ошибок, большая их часть записывается в логи.
Обратите внимание, что новый пользователь не регистрируется. Если в Motivity нет пользователя с таким же Уникальным идентификатором, как у пользователя в oauth провайдере, то произойдет ошибка «Пользователь не найден».
Дополнительные настройки систем OAuth
Microsoft Azure
В настройках должно быть разрешено приложению читать данные пользователя. Для этого необходимо:
Перейти в Активную директорию -> Регистрация приложений и зайти в приложение, которое используете для авторизации по протоколу OAuth.
Перейти в Разрешения API и добавить разрешение User.Read или User.All (User.Read должно хватить). Разрешение находится в Microsoft Graph -> Делегированные разрешения -> User.
Дополнительно можно добавить profile и email из OpenId (как на картинке).