# Настройка SAML-интеграции с Keycloak
> [HTML Version](saml-with-keycloak.html)
SAML‑интеграция позволяет использовать Keycloak для аутентификации и автоматического создания внутренних и внешних пользователей в ELMA365.
В момент авторизации в ELMA365 будет создаваться новый внутренний пользователь, а запись о нём появится в справочнике [Пользователи](360004833572.md). Если авторизация происходит на портале, то запись о пользователе появится в системном справочнике [Внешние пользователи](external-users.md).
Обратите внимание, чтобы незарегистрированный пользователь вошёл на портал через SAML, ему не нужно высылать [индивидуальную ссылку-приглашение](add-external-users.md#get_link). Достаточно предоставить ему ссылку на страницу портала.
Перед началом настройки интеграции выполните установку Keycloak согласно [официальной документации](https://www.keycloak.org/guides).
Для корректной работы требуется шифрованное соединение с сертификатами 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.png)
- **Наименование\*** — название для интеграции;
- **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‑сообщении, определяется при [создании параметров на стороне провайдера аутентификации](#add-parameters). Обратите внимание, если в SAML‑сообщении получены пустые значения, они также заменяют существующие данные пользователя в ELMA365;
- **Использовать для пользователей** — укажите, для кого будет возможна авторизация через SAML: для пользователей внешнего портала или для внутренних пользователей ELMA365.
4. Нажмите **Сохранить**. После этого будет сгенерирована ссылка на файл метаданных, которая отобразится в поле **URL метаданных**.
5. Перейдите по полученной ссылке и сохраните файл метаданных 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 включено [обновление данных пользователей при аутентификации](#update-user-data), добавленные параметры также определяют, какие данные будут обновляться.
Для добавления параметров перейдите из левого меню в раздел **Clients** и выберите созданное приложение. Затем откройте вкладку **Client scopes** и снова выберите созданное приложение.
4. На открывшейся странице на вкладке **Mappers** нажмите кнопку **Add predefined mapper**. Из открывшегося списка выберите **role\_list**.
5. На вкладке **Mappers** нажмите кнопку **Add mapper**. Из списка выберите **By configuration**. В открывшемся модальном окне выберите **User attributes**.
6. Создайте два параметра со следующими данными:
- **для 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.
7. Так как Keycloak будет являться поставщиком удостоверений, необходимо создать нового пользователя. Для этого из левого меню перейдите в раздел **Users** и создайте пользователя. Затем откройте вкладку **Credentials** и задайте для него пароль.
8. На вкладке **Attributes** укажите значения для следующих атрибутов:
- **externalCode** — идентификатор пользователя, аналог objectGUID в ActiveDirectory;
- **windowsaccountname** — логин пользователя из интерфейса ELMA365.
Также укажите электронную почту и имя пользователя.
9. Нажмите **Save**.
## Удаление SAML-провайдера
Если в системе нет пользователей, авторизованных через SAML-провайдера, его можно удалить. Для этого в настройках модуля SAML нажмите на значок корзины справа от названия и подтвердите действие.
**(saml-4.png)**