# Настройка SAML-интеграции с Microsoft Entra ID

> [HTML Version](saml-with-azure.html)

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

В момент авторизации в ELMA365 будет создаваться новый внутренний пользователь, а запись о нём появится в справочнике [Пользователи](360004833572.md). Если авторизация происходит на портале, то запись о пользователе появится в системном справочнике [Внешние пользователи](external-users.md). 

Обратите внимание, чтобы незарегистрированный пользователь вошёл на портал через SAML, ему не нужно высылать [индивидуальную ссылку‑приглашение](add-external-users.md#get_link). Достаточно предоставить ему ссылку на страницу портала. 

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

1. Перейдите в раздел Microsoft Entra ID** Корпоративные приложения**. Нажмите на **+ Новое приложение**, а затем на **+ Создайте собственное приложение**. 

2. Задайте имя приложению, например, **ELMA365**. Удостоверьтесь, что выбран пункт **Integrate any other application you don't find in the gallery (Non-gallery)** и нажмите кнопку **Создать**.

3. Откроется окно настройки приложения. Скопируйте URL файла метаданных приложения. Для этого нажмите на пункт **2. Настройка единого входа** и выберите **SAML**.

4. Здесь в пункте** 3. Сертификат подписи SAML** скопируйте ссылку на файл метаданных из поля **URL‑адрес метаданных федерации приложений **и перейдите к настройке SAML‑интеграции в ELMA365.

## Настроить интеграцию с SAML в ELMA365

Для настройки SAML‑интеграции потребуется действующий TLS-сертификат, который нужно будет предоставить SAML‑интеграции ELMA365 и приложению Microsoft Entra ID.

Чтобы настроить интеграцию с SAML: 

1. Перейдите в **Администрирование > Модули > SAML**.

2. Выберите опцию **Включить модуль** и нажмите **Добавить элемент**. 

3. В открывшемся окне настроек провайдера заполните поля. 

**(saml.png)**

- **Наименование\*** — название для интеграции;

- **URL метаданных IdP\*** — URL метаданных вашего AD FS сервера, который был получен при первоначальной настройке приложения SAML в Microsoft Entra ID; 

- **Публичный ключ\*** — строковое представление вашего публичного ключа в **.pem** формате: 

````
\-----BEGIN CERTIFICATE-----  
…  
\-----END CERTIFICATE-----

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

````
\-----BEGIN PRIVATE KEY-----  
…  
\-----END PRIVATE KEY-----

- ````
**Создавать пользователей в момент авторизации** — установите параметр в значение **Да**, чтобы отсутствующие внешние или внутренние пользователи создавались автоматически при попытке авторизации пользователя в системе;

- **Преобразовывать существующих пользователей** — установите параметр в значение **Да**, если необходимо обновлять существующих пользователей в момент авторизации. При обновлении пользователь будет преобразован во внешнего SAML‑пользователя, при этом у него пропадёт возможность авторизации прежним способом.

````
начало внимание

````
На данный момент доступно обновление только приглашённых пользователей при совпадении email приглашённого пользователя с email или login SAML пользователя.

````
конец внимание

- ````
**Обновлять данные существующих пользователей** — установите параметр в значение **Да**, чтобы в момент аутентификации пользователя его данные в ELMA365 обновлялись на данные, полученные в SAML‑сообщении. Набор данных, которые отправляются в SAML-сообщении, определяется на стороне провайдера аутентификации в процессе [добавления утверждений](#claims). Обратите внимание, если в SAML-сообщении получены пустые значения, они также заменяют существующие данные пользователя в ELMA365;

- **Использовать для пользователей** — укажите, для кого будет возможна авторизация через SAML: для пользователей внешнего портала или для внутренних пользователей ELMA365.

4. Нажмите кнопку **Сохранить**. После этого будет сгенерирована ссылка на файл метаданных, которая отобразится в поле **URL метаданных**. 

5. Перейдите по полученной ссылке и сохраните файл метаданных Service Provider в **.xml **формате. Он потребуется для финальной настройки SAML приложения на стороне Microsoft Entra ID.

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

1. Перейдите к настройке SAML. В разделе **2. Настройка единого входа — SAML** выберите пункт **1. Базовая конфигурация SAML**.

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

Чтобы загрузить данные с помощью файла, нажмите на кнопку **Отправить файл метаданных.** Укажите ранее полученный файл метаданных из SAML‑интеграции ELMA365 и нажмите **Добавить**. 

Для ручного заполнения полей базовой конфигурации в поле **Идентификатор (сущности)** замените значение, определённое по умолчанию, значением атрибута **entityID** ключа **EntityDescriptor **из **.xml** файла метаданных ELMA365, например, **https://yourCompanyName.elma365.ru/api/integrations/saml/85c86556-5c9e-4616-9742-a0f19ab6280c/metadata**.

В поле **URL-адрес ответа (URL-адрес службы обработчика утверждений) **укажите значение атрибута **Location** ключа **AssertionConsumerService** из **.xml** файла метаданных ELMA365, например, **https://elma365.ru/guard/login/saml/85c86556-5c9e-4616-9742-a0f19ab6280c?company=yourCompanyName**.

2. Добавьте новые утверждения в параметр **Утверждения и атрибуты пользователя**. В них указывается, какие атрибуты пользователя передаются в SAML‑сообщении в процессе аутентификации. Если в настройках модуля **SAML** в ELMA365 включено [обновление данных пользователей при аутентификации](#update-user-data), добавленные атрибуты определяют, какие данные будут обновляться.

1. **Имя** —** **externalCode;

**Пространство имен** — http://schemas.xmlsoap.org/ws/2005/05/identity/claims;

**Источник** — атрибут;

**Атрибут источника** — user.objectid.

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

2. **Имя** — windowsaccountname;

**Пространство имен** — http://schemas.xmlsoap.org/ws/2005/05/identity/claims;

**Источник** — атрибут;

**Атрибут источника** — user.userprincipalname;

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

3. **Имя** — emailaddress;

**Пространство имен** — http://schemas.xmlsoap.org/ws/2005/05/identity/claims;

**Источник** — атрибут;

**Атрибут источника** — user.mail.

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

4. **Имя** — givenname;

**Пространство имен** — http://schemas.xmlsoap.org/ws/2005/05/identity/claims;

**Источник** — атрибут;

**Атрибут источника** — user.givenname.

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

5. **Имя** — surname;

**Пространство имен** — http://schemas.xmlsoap.org/ws/2005/05/identity/claims;

**Источник** — атрибут;

**Атрибут источника** — user.surname.

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

6. **Имя** — name;

**Пространство имен** — http://schemas.xmlsoap.org/ws/2005/05/identity/claims;

**Источник** — атрибут;

**Атрибут источника** — user.displayname.

Атрибут будет сопоставлен с атрибутами имени, отчества и фамилии пользователя в системе ELMA365, если атрибуты givenname и surname будут содержать пустые значения.

3. Перейдите в пункт **Сертификат подписи SAML**. Импортируйте ранее подготовленный сертификат и активируйте его. Он будет использоваться при настройке SAML‑интеграции в ELMA365. 

4. В боковом меню выберите **Обзор** и перейдите в пункт **1. Назначение пользователей и групп**. Добавьте пользователей, которым будет доступна авторизация через созданное приложение. 

## Обновление файла метаданных в настроенной SAML‑интеграции в ELMA365

После того как в Microsoft Entra ID был изменён сертификат, необходимо обновить файл метаданных приложения Microsoft Entra ID на стороне SAML‑интеграции в ELMA365. Для этого откройте настройки ранее сконфигурированной SAML‑интеграции и нажмите кнопку **Сохранить**. После этого метаданные приложения Microsoft Entra ID будут обновлены.

## Удаление SAML-провайдера

Если в системе нет пользователей, авторизованных через SAML-провайдера, его можно удалить. Для этого в настройках модуля SAML нажмите на значок корзины справа от названия и подтвердите действие.

**(saml-3.png)**