# Настройка SAML-интеграции с Windows Server

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

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

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

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

Обратите внимание, для SAML‑интеграции с сервисом Microsoft Entra ID требуется дополнительная настройка на стороне Entra ID. Подробнее об этом читайте в статье [«Настройка SAML‑интеграции с Microsoft Entra ID»](saml-with-azure.md). Об интеграции с провайдером Keycloak читайте в статье [«Настройка SAML-интеграции с Keycloak»](saml-with-keycloak.md).

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

Для настройки SAML‑интеграции потребуется действующий TLS-сертификат, который будет использоваться для подписи запросов на стороне Service Provider.

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

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

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

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

**(saml.png)**

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

- **URL метаданных IdP\*** — URL метаданных вашего AD FS сервера, например, **https://your-domain.com/FederationMetadata/2007-06/FederationMetadata.xml**;

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

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

- [Создавать пользователей в момент авторизации](#create-users) — установите параметр в значение **Да**, чтобы несозданные в системе внутренние или внешние пользователи добавлялись автоматически при авторизации; 

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

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

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

	- **Портала** — для [внешних пользователей](external-users.md); 

	- **Стандартных** — для пользователей ELMA365. 

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

5. Перейдите по полученной ссылке и сохраните файл метаданных Service Provider в формате **.xml**. Он потребуется при настройке AD FS сервера.

### Создавать пользователей в момент авторизации

Если опция **Создавать пользователей в момент авторизации** включена, вне зависимости от того, связана ли SAML‑интеграция с модулем AD/LDAP, в системе будут создаваться отсутствующие внутренние или внешние пользователи. В зависимости от выбранной опции в поле **Использовать для пользователей** новые пользователи смогут авторизоваться через SAML в ELMA365 или на внешнем портале. 

Если опция отключена, отсутствующий в системе пользователь не сможет авторизоваться.

### Преобразовывать существующих пользователей

Опция **Преобразовывать существующих пользователей** влияет на обновление приглашённых пользователей или импортированных пользователей из несвязанной с SAML AD/LDAP‑интеграции. При обновлении такие пользователи конвертируются в SAML‑пользователей, при этом у них пропадает возможность авторизации прежним способом.

## Настройка связанной интеграции с AD/LDAP

Вы можете импортировать внутренних пользователей из [AD/LDAP](ad_ldap.md) и настроить для них авторизацию через SAML. Для этого перейдите в настройки соответствующей AD/LDAP‑интеграции и в поле **Тип аутентификации** выберите ранее созданную SAML‑интеграцию для пользователей ELMA365. Один сервер SAML можно использовать в нескольких серверах AD/LDAP.

Такие пользователи смогут авторизоваться через SAML, независимо от положения флага **Преобразовывать существующих пользователей**.

## Настройка аутентификации на сервере AD FS

После того как вы настроили интеграцию с SAML‑провайдером и получили файл метаданных, вам необходимо настроить сервер AD FS.

В этой статье приводятся инструкции для ОС Windows Server 2016. Для других версий шаги могут отличаться.

Настройка аутентификации на сервере AD FS выполняется в несколько этапов, описанных ниже. 

### Создание отношений доверия с проверяющей стороной

AD FS требует создавать отношение доверия с проверяющей стороной (relying party trust) для каждого поставщика услуг (Service Provider, SP), который будет использовать AD FS для аутентификации.

Создайте отношение доверия с проверяющей стороной для федерации:

1. Войдите на ваш сервер AD FS и откройте **Server Manager**.

2. Откройте консоль управления **AD FS**: **Tools > AD FS Management**.

3. В списке действий выберите **Add Relying Party Trust**.

4. Откроется окно помощника. На первой странице выберите **Claims aware** и нажмите **Start**.

5. Выберите **Import data about the relying party from a file** и укажите файл метаданных, полученный на предыдущем шаге при конфигурировании настроек интеграции SAML в ELMA365, нажмите **Next**.

6. Задайте имя, например, **ELMA365**, и нажмите **Next**.

7. На следующей странице можно выбрать, кому будет доступна аутентификация с помощью этой федерации. По умолчанию выбрана политика **Permit for everyone**, которая разрешает доступ для всех пользователей.

8. На странице **Ready to Add Trust** проверьте введённые данные и нажмите **Close**.

### Настройка Claims Mapping

Когда AD FS аутентифицирует пользователя, в Service Provider приходит SAML-сообщение с подтверждением об успешной аутентификации. Чтобы верно идентифицировать пользователя, необходимо настроить соответствие данных пользователя элементам SAML-сообщения.

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

Чтобы настроить сопоставление:

1. В консоли управления AD FS в блоке **Relying Party Trusts** нажмите правой кнопкой мыши на созданное ранее отношение доверия с проверяющей стороной и выберите **Edit Claim Issuance Policy**.

2. В открывшемся окне нажмите **Add Rule**.

3. Выберите **Send Claims Using a Custom Rule** и нажмите **Next**.

4. В поле **Claim Rule Name** введите имя правила, например, **CustomRule1**. В поле **Custom Rule** укажите правило:

````
c:\[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname", Issuer == "AD AUTHORITY"\]  
 => issue(store = "Active Directory", types =   
("http://schemas.xmlsoap.org/ws/2005/05/identity/claims/windowsaccountname",   
"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",   
"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",   
"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname",   
"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/externalCode",   
"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname",   
"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn",   
"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/otherphone"), query =   
";sAMAccountName,displayName,mail,givenName,distinguishedName,sn,userPrincipalName,telephoneNumber;\{0\}", param = c.Value);

````
Нажмите **Finish**.

#### Примечания:

- поля **"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/windowsaccountname"** и **"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/externalCode"** являются обязательными;

- значение поля **"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/externalCode"** должно совпадать со значением поля **Параметр "DN"** из связанной AD‑интеграции. По этому полю идентифицируется существующий пользователь при конвертации из AD в SAML‑пользователя и обратно;

- в качестве логина используется значение из поля **sAMAccountName**, если вам необходим логин в формате Email, используйте в качестве источника поле **userprincipalname**.

5. Введите ещё одно правило, для этого снова нажмите **Add Rule**.

6. Выберите **Send Claims Using a Custom Rule** и нажмите **Next**.

7. В поле **Claim Rule Name** введите имя правила, например, **CustomRule2**. В поле **Custom Rule** укажите правило:

````
c:\[Type == "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn"\] => issue(Type =   
"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier", Issuer = c.Issuer,   
OriginalIssuer = c.OriginalIssuer, Value = c.Value, ValueType = c.ValueType,   
Properties\["http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/format"\] =   
"urn:oasis:names:tc:SAML:2.0:nameid-format:transient");

````
Нажмите **Finish**.

8. Нажмите **OK**.

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

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

**(saml-2.png)**