search string side menu

Интеграция с SAML / Настройка SAML-интеграции с Keycloak

Настройка SAML-интеграции с Keycloak

SAML‑интеграция позволяет использовать Keycloak для аутентификации и автоматического создания внутренних и внешних пользователей в ELMA365.

В момент авторизации в ELMA365 будет создаваться новый внутренний пользователь, а запись о нём появится в справочнике Пользователи. Если авторизация происходит на портале, то запись о пользователе появится в системном справочнике Внешние пользователи.

Обратите внимание, чтобы незарегистрированный пользователь вошёл на портал через SAML, ему не нужно высылать индивидуальную ссылку-приглашение. Достаточно предоставить ему ссылку на страницу портала.

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

Для корректной работы требуется шифрованное соединение с сертификатами tls на серверах Keycloak и ELMA365.

Первоначальная настройка приложения SAML в Keycloak

  1. Откройте настройки Keycloak по адресу http://my_domen.com:8443, где:
    • my_domen.com — адрес вашего сайта;
    • :8443 — стандартный порт, используемый Keycloak при шифрованном соединении. Его можно изменить при конфигурировании рабочей среды.
  2. Перейдите в Administration Console. Для подтверждения действия введите логин и пароль от своей учётной записи.
  3. На открывшейся странице создайте новое окружение. Введите название окружения и нажмите кнопку Create.
  4. Из левого меню перейдите в раздел Realm setting. На вкладке General из поля Endpoints скопируйте ссылку на метаданные Keycloak для интеграции с SAML.

Настройка интеграции с SAML в ELMA365

  1. Перейдите в Администрирование > Модули > SAML.
  2. Поставьте флажок напротив опции Включить модуль и нажмите Добавить элемент.
  3. В открывшемся окне настроек провайдера заполните поля:

saml

  • Наименование* — название для интеграции;
  • URL метаданных IdP* — URL метаданных вашего Keycloak сервера, который был получен при первоначальной настройке приложения SAML в Keycloak на шаге 4;
  • Публичный ключ* — строковое представление вашего публичного ключа в .pem формате:  

-----BEGIN CERTIFICATE-----
…
-----END CERTIFICATE-----

  • Закрытый ключ* — строковое представление вашего закрытого ключа в .pem формате:

-----BEGIN PRIVATE KEY-----
…
-----END PRIVATE KEY-----

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

openssl req -x509 -newkey rsa:2048 -keyout service.key -out service.cert -days 365 -nodes -subj "/CN=mydomain.pro"

Где mydomain.pro — ваше доменное имя keycloak.

Для последующей настройки интеграции вам потребуется импортировать публичный ключ в формате PKCS12. Для его экспорта используйте следующую команду:

openssl pkcs12 -export -out cert.p12 -in service.cert -inkey service.key -name learn 

  • Создавать пользователей в момент авторизации — установите параметр в значение Да, чтобы отсутствующие внешние или внутренние пользователи создавались автоматически при попытке авторизации пользователя в системе;
  • Преобразовывать существующих пользователей — установите параметр в значение Да, если необходимо обновлять существующих пользователей в момент авторизации. При обновлении пользователь будет преобразован во внешнего SAML‑пользователя, при этом у него пропадёт возможность авторизации прежним способом;
  • Обновлять данные существующих пользователей — установите параметр в значение Да, чтобы в момент аутентификации пользователя его данные в ELMA365 обновлялись на данные, полученные в SAML‑сообщении. Набор данных, которые отправляются в SAML‑сообщении, определяется при создании параметров на стороне провайдера аутентификации. Обратите внимание, если в SAML‑сообщении получены пустые значения, они также заменяют существующие данные пользователя в ELMA365;
  • Использовать для пользователей — укажите, для кого будет возможна авторизация через SAML: для пользователей внешнего портала или для внутренних пользователей ELMA365.
  1. Нажмите Сохранить. После этого будет сгенерирована ссылка на файл метаданных, которая отобразится в поле URL метаданных.
  2. Перейдите по полученной ссылке и сохраните файл метаданных Service Provider в .xml формате. Он потребуется для финальной настройки SAML‑приложения на стороне Keycloak.

Финальная настройка приложения SAML в Keycloak

  1. Вернитесь в интерфейс настройки Keycloak и импортируйте клиента с помощью файла метаданных, полученных при настройке интеграции SAML в ELMA365 на шаге 5. Для этого из левого меню перейдите в раздел Clients и нажмите кнопку Import client. На отрывшейся странице загрузите файл метаданных с помощью кнопки Browse. После сохранения откроется окно настройки приложения.
  2. Перейдите на вкладку Keys и с помощью кнопки Import Key импортируйте хранилище ключей cert.p12, созданное при настройке интеграции SAML в ELMA365 на шаге 3. Укажите формат архивирования (в нашем примере это PKCS12), лэйбл, указанный после директивы -name при экспорте ключа, и пароль от хранилища.  
  3. Для корректной работы интеграции на стороне Keycloak необходимо создать два обязательных для SAML‑параметра: windowsaccountname и externalCode. Если в настройках модуля SAML в ELMA365 включено обновление данных пользователей при аутентификации, добавленные параметры также определяют, какие данные будут обновляться.

Для добавления параметров перейдите из левого меню в раздел Clients и выберите созданное приложение. Затем откройте вкладку Client scopes и снова выберите созданное приложение.

  1. На открывшейся странице на вкладке Mappers нажмите кнопку Add predefined mapper. Из открывшегося списка выберите role_list.
  2. На вкладке Mappers нажмите кнопку Add mapper. Из списка выберите By configuration. В открывшемся модальном окне выберите User attributes.
  3. Создайте два параметра со следующими данными:
  • для windowsaccountname:
    • Name* — http://schemas.xmlsoap.org/ws/2005/05/identity/claims/windowsaccountname;
    • User Attribute — windowsaccountname;
    • SAML Attribute Name — http://schemas.xmlsoap.org/ws/2005/05/identity/claims/windowsaccountname;
    • SAML Attribute NameFormat — URL Reference.

Параметр является обязательным. Атрибут будет сопоставлен с логином пользователя в ELMA365.

  • для externalCode:
    • Name* — http://schemas.xmlsoap.org/ws/2005/05/identity/claims/externalCode;
    • User Attribute — externalCode;
    • SAML Attribute Name — http://schemas.xmlsoap.org/ws/2005/05/identity/claims/externalCode;
    • SAML Attribute NameFormat — URL Reference.

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

  1. Так как Keycloak будет являться поставщиком удостоверений, необходимо создать нового пользователя. Для этого из левого меню перейдите в раздел Users и создайте пользователя. Затем откройте вкладку Credentials и задайте для него пароль.
  2. На вкладке Attributes укажите значения для следующих атрибутов:  
  • externalCode — идентификатор пользователя, аналог objectGUID в ActiveDirectory;
  • windowsaccountname — логин пользователя из интерфейса ELMA365.

Также укажите электронную почту и имя пользователя.  

  1. Нажмите Save.
saml-with-azure.html audit_service.html