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

Общая информация

Keycloak — это система аутентификации с открытым исходным кодом (Open Source), которая позволяет контролировать доступ пользователей к приложениям и данным, обеспечивая единую точку входа (SSO).

SSO (Single Sign-On) — используемая в Keycloak технология единого входа, благодаря которой пользователи могут авторизоваться в нескольких приложениях с помощью одного набора учетных данных.

Realm — область для клиентов (приложений), в которой настраивается управление пользователями, приложениями, ролями и группами. Каждый Realm обладает собственным набором политик безопасности, конфигураций и механизмов аутентификации.

Клиенты — приложения и сервисы, которые используют Keycloak для аутентификации и авторизации пользователей.

Атрибуты — данные из профиля пользователя. Доступ к атрибутам и их управление осуществляются с помощью специальных операций. По умолчанию для каждого пользователя в Keycloak доступны такие атрибуты, как имя, фамилия и адрес электронной почты.

Мапперы — позволяют включать данные пользователя (электронную почту, роли, группы, в которые он входит) в атрибуты SAML, выдаваемые клиентам при аутентификации.

Предварительные требования

Чтобы настроить интеграцию Pyrus c Keycloak с помощью технологии SAML, вам потребуется:

• установить решение Keycloak — рекомендуемая версия 26 и выше, официально технология SAML поддерживается в Keycloak начиная с версии 17 и выше;
• создать организацию в Pyrus.

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

1. Авторизуйтесь в Pyrus.

2. Нажмите значок шестеренки в левом нижнем углу экрана, чтобы войти в общие настройки.

   

3. В блоке Настройки SAML нажмите Настроить.

   

4. Заполните настройки SAML:

   URL IdP: https://{KEYCLOAK_DOMAIN_NAME}/realms/{REALM_NAME}/protocol/saml

   Сертификат провайдера можно получить по ссылке: https://{KEY CLOAK_DOMAIN_NAME}/realms/{REALM_NAME}/protocol/saml/descriptor внутри тега <ds:X509Certificate>. Перед вставкой его необходимо заключить в Pem-блок:

   -----BEGIN CERTIFICATE-----

   Certificate

   -----END CERTIFICATE-----

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

Создание клиента

1. Создайте Клиент:

   • получите конфигурацию клиента по ссылке вида: https://pyrus.com/auth/saml/metadata/{ORG_ID}
   • импортируйте клиент из полученной конфигурации.

2. В настройках клиента, в разделе SAML capabilities установите для поля Name ID format значение email.

   

Настройка обмена данными между Pyrus и Keycloak

Чтобы данные пользователя (имя, фамилия, телефон) автоматически подгружались в Pyrus из сервиса Keycloak, нужно настроить обмен информацией между Pyrus и атрибутами пользователя в Keycloak. Для этого выполните следующие действия.

1. Создайте клиентскую область — Client Scope.

   

2. В Client Scope создайте мапперы типа User Attribute с полем SAML Attribute NameFormat в значении URI Reference для следующих атрибутов:

   • атрибут firstName

   SAML Attribute Name: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname

   

   • атрибут lastName

   SAML Attribute Name: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname

   

   • атрибут phone

   SAML Attribute Name: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/otherphone

   

   Подсказка: если атрибут phone отсутствует, его можно создать. Для этого войдите в раздел Realm settings, а затем в User profile.

3. Войдите в раздел Clients, откройте вкладку Client Name, а затем — Client Scopes. Добавьте созданный вами ранее Client scope в статусе Default.

   

Ограничения

Чтобы пользователь мог входить в Pyrus по SAML-протоколу, он должен быть добавлен в вашу организацию.

Как добавить пользователя в организацию

Приложение Pyrus Sync не поддерживает синхронизацию пользователей из сервиса Keycloak, но если Keycloak использует в качестве поставщика удостоверений (IdP) Active Directory, синхронизацию можно организовать через него.