Интеграции с системами аутентификации

Общие сведения

Цель модуля

Бизнес-цель использования модуля OAuth – аутентификация на платформе посредством облачного сервиса управления удостоверениями и доступом.

Доступные системы аутентификации и их официальная документация:

Авторизация пользователей

Переход к авторизации пользователя по технологии SSO может быть осуществлен двумя способами:

  • При включённой интеграции с сервисами аутентификации и при активном чек-боксе “Авторизация по логину и паролю для всех пользователей

    • Пользователь переходит на страницу авторизации на платформе. На странице отображается кнопка “Войти с помощью {Provider}”, где {Provider} – название подключённого провайдера (задается в Настройках), например “Войти с помощью Okta”.

    • При нажатии на кнопку “Войти с помощью {Provider}” платформа автоматически перенаправляет пользователя на страницу входа подключенной системы аутентификации.

    • Пользователь вводит логин и пароль от учетной записи системы аутентификации.

    • Если пользователь с таким email найден - то система аутентификации перенаправляет пользователя Motivity на главную страницу. Если пользователь с таким email не найден, то он не может попасть на главную страницу Motivity. Ему необходимо обратиться к администратору.

  • При включённой интеграции с сервисами аутентификации и при НЕ активном чек-боксе “Авторизация по логину и паролю для всех пользователей

    • Пользователь переходит на страницу авторизации на платформе.

    • Платформа автоматически перенаправляет пользователя на страницу входа подключенной системы аутентификации.

    • Пользователь вводит логин и пароль от учетной записи системы аутентификации.

    • Если пользователь с таким email найден - то система аутентификации перенаправляет пользователя Motivity на главную страницу. Если пользователь с таким email не найден, то он не может попасть на главную страницу Motivity. Ему необходимо обратиться к администратору.

Важно! На портале при использовании авторизации только посредством OAuth, пользователям смена пароля в личном кабинете недоступна.

Как выйти с платформы

Для выхода из системы в ручном режиме необходимо выполнить следующие действия:

  • выйти из аккаунта системы аутентификации.

  • выйти из Motivity через кнопку “Выход” в шапке портала.

Требования для организации своевременной поддержки пользователей

Для осуществления своевременной и оперативной поддержки пользователей администраторы портала должны иметь доступ в систему (минимум 2 учетные записи).
Если вы планируете использовать такой способ аутентификации, необходимо обсудить с вашим аккаунт-менеджером условия доступа сотрудников Motivity.

Обратите внимание: возможность авторизации не предусматривает изменение и восстановление пароля.
В текущей реализации это невозможно. В случае необходимости администраторы могут обратиться к команде разработки.

Как настроить подключение

Страница систем OAuth

Управление аутентификацией пользователей по технологии SSO в панели администрирования производится в разделе Параметры системы - Авторизация.

Страница содержит вкладки:

  • Общие настройки

  • Провайдеры

  • Логи

Вкладка Провайдеры

На вкладке отображается список заранее настроенных систем управления доступами, которые добавляются разработчиками, со следующими столбцами в строках:

  • Активен – отображает текущее значение чек-бокса “Активировать“, имеет значения “Да” и “Нет”

  • Имя провайдера - ссылка, отображает наименование системы управления доступами

  • Ключ провайдера - ссылка, уникальный ключ системы управления доступами

Доступные действия на странице:

  • Переход на страницу Редактирование настроек системы управления доступами - происходит при нажатии на “Имя провайдера” или “Ключ провайдера“

Подключение и редактирование системы OAuth

Важно! Перед подключением системы аутентификации необходимо отключить опцию “Изменение пароля пользователя” и рассылку пригласительных писем.

Что отключить

Где находится

Скриншот

Что отключить

Где находится

Скриншот

Рассылка пригласительных писем

/admin/sender/email_constructor/edit/user_invite

 

Опция “Изменение пароля пользователя”

/admin/system/auth

Далее необходимо заполнить поля указанные ниже:

Поле

Описание

Пример заполнения

Поле

Описание

Пример заполнения

Чек-бокс Активировать

  • Если активен, то для авторизации пользователей на портале используется система управления доступами.

  • Чек-бокс недоступен для выбора, если активирована двухфакторная аутентификация (чек-бокс Включить двухфакторную аутентификацию по e-mail)

Поля запроса по 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

  • Обязательное поле

  • Если поле скрыто, это значит, что для выбора доступно только одно значение, которое уже является значением по умолчанию

  • Для Okta и Keycloak значение в поле должно совпадать со значением в поле Уникальный идентификатор в ПА, на странице Oauth — в поле Уникальный идентификатор.
    Для каждой системы отображается свой список допустимых полей:

  • Azure

    • mail (По умолчанию)

    • id

    • mobilePhone

    • userPrincipalName

  • Keycloak

    • mail (По умолчанию)(не выводится в админпанель)

  • Okta

    • mail (По умолчанию)(не выводится в админпанель)

  • AD FS

    • upn (По умолчанию)

    • unique_name

Поле Идентификатор пользователя в системе

Используется для провайдеров:

  • AD FS

  • Microsoft Azure

Представляет собой выпадающий список:

  • Обязательное

  • Множественный выбор недоступен

  • Значение по умолчанию: Уникальный идентификатор ([Название УИ])

  • Значения в выпадающем списке:

    • Внешний идентификатор — системное поле из конструктора полей

    • Уникальный идентификатор ([Название УИ]) — поле, которое в текущий момент выбрано как УИ на странице Oauth

      • При изменении УИ на странице Oauth УИ на странице провайдера изменяется на идентичный автоматически

Кнопка Сохранить

При нажатии на кнопку происходит сохранение настроек системы управления доступами и закрытие страницы.

Вкладка Логи

На вкладке отображаются зафиксированные ошибки при попытке авторизации

Записи вносятся в таблицу и располагаются в хронологическом порядке по убыванию даты изменений.

Фильтрация в этом разделе не предусмотрена.

Поля в таблице могут быть разными, в зависимости от ошибки и системы управления доступами

Список возможных ошибок и причины их возникновения приведены в таблице ниже:

Ошибка

Что логируется

Возможные причины

Ошибка

Что логируется

Возможные причины

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

  1. Перейдите в Azure Active Directory через https://portal.azure.com/#home

  2. Перейдите в «Регистрация приложений»

  3. Зарегистрируйте новое приложение, выбрав Веб, внесите туда URL перенаправления (redirect URL), который является адресом вашей платформы Motivity.
    Важно: адрес должен быть со слешем в конце, например http://client.motivity.ru/

  4. В «Разрешения API» добавьте разрешения Microsoft Graph: User.Read.All из Резрешений приложения и email, offline_access, openid, profile из Делегированных разрешений (раздел «Разрешения OpenId»)

  5. На вкладке «Проверка подлинности» активируйте опции «Токены доступа» и «Токены ИД»

  6. Перейдите во вкладку «Сертификаты и секреты», создайте новый секрет и копируйте его Значение, оно понадобятся для настроек Motivity, и сохраните их.

  7. Перейдите в настройки OAuth, которые находятся в Параметры системы -> Авторизация (вы также можете дописать путь /admin/system/auth к вашему домену). Перейдите в провайдер Microsoft Azure.

  8. Заполните необходимые настройки:

    1. Client id - Идентификатор приложения. Его можно посмотреть на главной странице приложения.

    2. Client secret - введите значение из пункта 6.

    3. Auth url - адрес авторизации, формируется по принципу https://login.microsoftonline.com/{Directory ID}/oauth2/v2.0/authorize, где Directory ID - Идентификатор каталога. Его можно посмотреть на главной странице приложения.

    4. Token url - адрес получения токена доступа. Формируется по принципу  https://login.microsoftonline.com/{Directory ID}/oauth2/v2.0/token

    5. Идентификатор пользователя в API - поле из объекта User из Microsoft Graph с которым будет сравниваться поле «Уникальный идентификатор» в Motivity.

  9. Поставьте галочку в поле Активировать и нажмите сохранить.

  10. Убедитесь, что вы выполнили все рекомендации и отключили рассылку «Пригласительное письмо» (ПА -> Рассылка -> Рассылки -> Приглашение на портал -> дезактивировать чек-бокс “Рассылка активна”) и опцию «Изменение пароля» (ПА -> Параметры системы -> Авторизация -> дезактивировать чек-бокс “Изменение пароля пользователя”).

  11. Перейдите в Параметры системы -> Авторизация и убедитесь, что опция Авторизация по логину и паролю для пользователей с ролью «Администратор» активна. Если нет, то активируйте ее.
    Важно: если неверно настроить авторизацию и оставить ее включенной, можно потерять доступ к панели администратора, поэтому, даже если вы не планируете сохранить доступ к панели посредствам ввода логина/пароля, то мы рекомендуем выключить эту опцию только после того, как вы убедитесь, что все работает корректно

Уточнения

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 (как на картинке).