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

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

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

Цель модуля

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Управлять аутентификацией пользователей по технологии SSO можно в Панели управленияНастройкиOAuth.

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

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

  • Провайдеры

  • Логи

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

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

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

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

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

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

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

Подключение и редактирование системы 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 — в поле Уникальный идентификатор
    Для каждой системы отображается свой список допустимых полей:

  • Microsoft Azure

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

    • id

    • mobilePhone

    • userPrincipalName

  • Keycloak

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

  • Okta

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

  • AD FS

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

    • unique_name

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

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

  • AD FS

  • Microsoft Azure

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

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

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

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

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

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

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

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

Чек-бокс Активировать аутентификацию по JWT-токену

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

  • Если активен, то будет происходить попытка авторизации пользователей на платформе через JWT-токен (при его наличии в заголовках запроса). Если токен отсутствует или авторизация по токену не удалась, авторизация пойдёт по стандартному настроенному сценарию (через логин/пароль или по технологии SSO)

Поле Ссылка для валидации JWT-токена

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

  • Должно содержать адрес c уточнением протокола

  • Обязательно для заполнения, если активен чек-бокс Активировать аутентификацию по JWT-токену

  • Недоступно для взаимодействия, если чек-бокс Активировать аутентификацию по JWT-токену неактивен

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

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

    • userPrincipalName

    • id

    • mail

    • mobilePhone

  • Обязательное поле, если активен чек-бокс Активировать аутентификацию по JWT-токену

  • Недоступно для взаимодействия, если чек-бокс Активировать аутентификацию по JWT-токену неактивен

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

Поле Уникальный идентификатор пользователя в системе для JWT-токена

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

  • Обязательное поле, если активен чек-бокс Активировать аутентификацию по JWT-токену

  • Недоступно для взаимодействия, если чек-бокс Активировать аутентификацию по JWT-токену неактивен

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

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

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

    • Уникальный идентификатор ([Название УИ]) — поле, которое в текущий момент выбрано как УИ на странице /admin/system/auth. При изменении УИ на странице /admin/system/auth УИ на странице провайдера изменяется на идентичный автоматически

Вкладка Логи

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

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

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

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

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

Ошибка

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

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

Ошибка

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

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

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. Для этого важно следовать инструкции:

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

  1. Зайти в раздел Регистрация приложений

  1. Зарегистрировать новое приложение, выбрав Веб, и внести туда URL перенаправления (redirect URL), который является адресом вашей платформы Motivity

Адрес должен заканчиваться слэшем (/)

Пример: http://client.motivity.ru/

  1. В Разрешения API добавить:

    • Разрешения Microsoft Graph: User.Read.All — из Разрешений приложения

    • email — из Делегированных разрешений (раздел Разрешения OpenId)

    • offline_access — из Делегированных разрешений (раздел Разрешения OpenId)

    • openid — из Делегированных разрешений (раздел Разрешения OpenId)

    • profile — из Делегированных разрешений (раздел Разрешения OpenId)

  1. Во вкладке Проверка подлинности активировать опции Токены доступа и Токены ИД

  1. Перейти во вкладку Сертификаты и секреты, создать новый секрет, скопировать его значение (оно понадобится для настроек Motivity) и сохранить

  1. На платформе перейти в Панель управленияНастройки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 — адрес получения токена доступа

  • Идентификатор пользователя в API — поле из объекта User из Microsoft Graph, с которым будет сравниваться поле Уникальный идентификатор в Motivity

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

Уточнения

  • Motivity использует протокол OAuth2 для сквозной авторизации

  • Scope, с которым Motivity обращается к Oauth-провайдеру — OpenID

  • Oauth-провайдер используется только для сквозной аутентификации. Валидный токен доступа не хранится в Motivity: он нужен только для идентификации пользователя по полю Идентификатор пользователя в API

  • В случае возникновения ошибок большая их часть записывается в Панели управленияНастройкиOАuth → Логи

  • Новый пользователь не регистрируется. Если в Motivity нет пользователя с таким же уникальным идентификатором, как у пользователя в Oauth-провайдере, то произойдет ошибка Пользователь не найден

Дополнительные настройки систем OAuth

Microsoft Azure

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

  1. Перейти в Активную директориюРегистрация приложений и зайти в приложение, которое используется для авторизации по протоколу OAuth

  2. Перейти в Разрешения API и добавить разрешение User.Read или User.All (User.Read должно хватить). Разрешение находится в Microsoft GraphДелегированные разрешенияUser

  3. Дополнительно можно добавить profile и email из OpenID

Чтобы подключить дополнительный функционал авторизации по JWT-токену, на платформе нужно:

  1. В Панели управленияНастройкиOАuth → ПровайдерыMicrosoft Azure включить опцию Активировать аутентификацию по JWT-токену

  2. Заполнить поля:

    • Ссылка для валидации JWT-токена — адрес валидации JWT-токена

    • Идентификатор пользователя в JWT-токене — поле из объекта User из Microsoft Graph, с которым будет сравниваться поле Уникальный идентификатор пользователя в системе для JWT-токена в Motivity

  3. Нажать Сохранить

Related content

Авторизация пользователей
Авторизация пользователей
Read with this
OAuth в приложении
OAuth в приложении
More like this
Публичный API
Публичный API
Read with this
Валидация пользователей при импорте
Валидация пользователей при импорте
More like this
API для регистрации пользователей на портале СД
API для регистрации пользователей на портале СД
Read with this
Установка платформы на сервер клиента: требуемые доступы к ресурсам
Установка платформы на сервер клиента: требуемые доступы к ресурсам
Read with this