Настройка MFA/SSO через ADFS для Exchange Outlook Web Access (OWA) и Exchange Control Panel (ECP)

Общие сведения

Avanpost FAM позволяет обеспечить двухфакторную аутентификацию (2FA), многофакторную аутентификацию (MFA) и Single-Sign On (SSO) для пользователей, выполняющих подключение к почтовому веб-клиенту Exchange Outlook Web Access (OWA) и административному веб-интерфейсу Exchange Control Panel (ECP) из состава Microsoft Exchange. В инструкции описывается настройка 2FA для OWA и ECP по протоколу SAML с использованием Microsoft AD FS (Microsoft Active Directory Federation Services) в роли WS-Federation Identity Provider.

Для Microsoft Exchange Outlook Web Access при использовании Avanpost FAM посредством SAML через AD FS могут использоваться следующие факторы аутентификации:

• Мобильное приложение Avanpost Authenticator (push + TOTP);
• SMS;
• TOTP;
• E-mail;
• Мессенджер Telegram;
• Электронная подпись;
• FIDO WebAuthn/U2F;
• Доменная Kerberos-аутентификация;
• ЕСИА (Единая система идентификации и аутентификации) в режиме Federation;
• OpenID Connect-провайдер в режиме Federation;
• SAML-провайдер в режиме Federation.

Необходимость использования Microsoft AD FS обоснована наличием поддержки на стороне Microsoft Exchange OWA и Microsoft Exchange CP протокола WS-Federation, не совместимого со стандартным для таких задач протоколом SAML. Поэтому Microsoft AD FS выступает в данной схеме в качестве средства трансляции SAML-взаимодействия между Avanpost FAM и AD FS в WS-Federation-взаимодействие между AD FS и Exchange OWA/Exchange ECP. 

Системные требования для интеграции Microsoft Exchange Outlook Web Access:

• Сервер Avanpost FAM 1.4.0 или выше;
• Сервер Microsoft Exchange 2016+ с настроенным веб-приложением Outlook Web Access.
• Сервер Microsoft Active Directory Federation Services (AD FS).

Для выполнения настройки 2FA/MFA/SSO в соответствии с инструкцией необходимо выполнить следующие предварительные условия:

1. Установить в сети сервер Microsoft Exchange и опубликовать веб-приложение Outlook Web Access;
2. Установить в сети сервер Microsoft AD FS, обеспечить сетевую доступность для сервера Avanpost FAM;
3. Установить в сети компонент Avanpost FAM Server, обеспечить сетевую доступность с сервера Microsoft Exchange интерфейса аутентификации SAML развёрнутой системы Avanpost FAM (как минимум документа http(s)://%Avanpost_FAM_base_URL%/.well-known/samlidp.xml).

Дополнительно может потребоваться при необходимости аутентификации:

• через мобильное приложение Avanpost Authenticator – установить компоненты Avanpost FAM Mobile Services;
• через мобильное приложение SafeTech PayControl – установить сервер SafeTech PayControl;
• через SMS – настроить подключение к внешнему SMS-шлюзу, который предоставляет услугу доставки SMS-сообщений;
• через E-mail – настроить подключение к SMTP-шлюзу, который обеспечивает доставку почтовых сообщений;
• через Telegram – настроить подключение к Telegram Bot API;
• посредством электронной подписи – настроить криптопровайдер и установить плагин в браузер;
• посредством FIDO WebAuthn/U2F – настроить сертификат;
• посредством Kerberos – настроить keytab-файл;
• посредством Federation через ЕСИА – настроить подключение к ЕСИА;
• посредством Federation через OpenID Connect-провайдер – настроить подключение к OpenID Connect-провайдеру;
• посредством Federation через SAML-провайдер – настроить подключение к SAML-провайдеру.

Настройка на стороне сервера Microsoft Exchange

Настройку на стороне сервера Microsoft Exchange необходимо выполнять следующим образом:

1. От имени администратора открыть Powershell (нажать Win+R и ввести powershell) и перейти в консоль PowerShell Exchange при помощи команды:

   Add-PSSnapin Microsoft.Exchange.Management.PowerShell.SnapIn

2. В консоли PowerShell Exchange на стороне сервера Microsoft Exchange подготовить и выполнить с правами администратора указанный ниже скрипт, внеся целевые значения параметров вместо %заменителей%:

   $ADFSSigningCertificateThumbprint="%значение_отпечатка_сертификата_на_стороне_AD_FS%"
   $owaURL="%URL-адрес_OWA%"
   $ecpURL="%URL-адрес_ECP%"
   $ADFSIssuerURL="%URL-адрес_Issuer_AD_FS%"
   
   $uris = @($owaURL,$ecpURL)
   Set-OrganizationConfig -AdfsIssuer $ADFSIssuerURL -AdfsAudienceUris $uris -AdfsSignCertificateThumbprints $ADFSSigningCertificateThumbprints
   Get-EcpVirtualDirectory | Set-EcpVirtualDirectory -AdfsAuthentication $true -BasicAuthentication $false -DigestAuthentication $false -FormsAuthentication $false -WindowsAuthentication $false
   Get-OwaVirtualDirectory | Set-OwaVirtualDirectory -AdfsAuthentication $true -BasicAuthentication $false -DigestAuthentication $false -FormsAuthentication $false -WindowsAuthentication $false

   где PowerShell-переменная:

   • $ADFSSigningCertificateThumbprints содержит отпечаток (thumbprint) сертификата на стороне AD FS (пример значения – «2F4A8553226E3AC3BCDBA171A4F73E9B23A486DD»); целевое значение параметра следует указать вместо заменителя %значение_отпечатка_сертифката_на_стороне_AD_FS%; методика получения отпечатка сертификата описана в Приложении 1 текущей инструкции;
   • $owaURL содержит URL-адрес веб-интерфейса Exchange OWA (пример значения – «https://mail.avanpost.ru/owa»); целевое значение параметра следует указать вместо заменителя %URL-адрес_OWA%;
   • $ecpURL содержит URL-адрес веб-интерфейса ECP (пример значения – «https://mail.avanpost.ru/ecp»); целевое значение параметра следует указать вместо заменителя %URL-адрес_ECP%;
   • $ADFSIssuerURL содержит URL-адрес сервера аутентификации (пример значения – «https://adfs.avanpost.ru/adfs/ls/»); целевое значение параметра следует указать вместо заменителя %URL-адрес_Issuer_AD_FS%.
3. Убедиться в корректности настройки интеграции Microsoft Exchange и AD FS. Для этого следует запросить параметры конфигурации Microsoft Exchange, связанные с AD FS, посредством команды:

   Get-OrganizationConfig | f1 Adfs* 

Настройка на стороне сервера AD FS

Настройку на стороне сервера AD FS необходимо выполнять следующим образом:

1. От имени администратора открыть Powershell.

2. Через PowerShell выполнить сценарий с правами администратора на сервере AD FS, создающий «Доверие проверяющей стороны» (Relying Party Trust) для Exchange OWA и Exchange CP (либо выполнить настройку через графический интерфейс AD FS вместо выполнения PowerShell-команды в соответствии с Приложением 2 текущей инструкции):

   $owaURL="%URL-адрес_OWA%"
   $ecpURL="%URL-адрес_ECP%"
   
   $IssuanceAuthorizationRules=@'
       @RuleTemplate = "AllowAllAuthzRule"
       => issue(Type = "http://schemas.microsoft.com/authorization/claims/permit",
       Value = "true");
   '@
   
   $IssuanceTransformRules=@'
       @RuleName = "UPN"
       c:[Type == "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn"]
        => issue(claim = c);
   '@
   
   Add-ADFSRelyingPartyTrust -Name "OWA" -Enabled $true -WSFedEndpoint $owaURL -Identifier $owaURL -IssuanceTransformRules $IssuanceTransformRules -IssuanceAuthorizationRules $IssuanceAuthorizationRules
   Add-ADFSRelyingPartyTrust -Name "ECP" -Enabled $true -WSFedEndpoint $ecpURL -Identifier $ecpURL -IssuanceTransformRules $IssuanceTransformRules -IssuanceAuthorizationRules $IssuanceAuthorizationRules

   где PowerShell-переменная:

   • $owaURL содержит URL-адрес веб-интерфейса Exchange OWA (пример значения – «https://mail.avanpost.ru/owa»); целевое значение параметра следует указать вместо заменителя %URL-адрес_OWA%;
   • $ecpURL содержит URL-адрес веб-интерфейса ECP (пример значения – «https://mail.avanpost.ru/ecp»); целевое значение параметра следует указать вместо заменителя %URL-адрес_ECP%.

3. Через PowerShell выполнить сценарий с правами администратора на сервере AD FS, создающий «Доверие поставщиков утверждений» (Claims Provider Trust) для Avanpost FAM (либо выполнить настройку через графический интерфейс AD FS в соответствии с Приложением 3 текущей инструкции):

   $AvanpostFAMMetadataURL="%URL-адрес_SAML_Discovery-документа_Avanpost_FAM%" 
   
   $AcceptanceTransformRules=@'
       @RuleName = "UPN"
       c:[Type == "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn"]
        => issue(claim = c);
   '@
    
   Add-AdfsClaimsProviderTrust -Name "Avanpost FAM" -Enabled $true -AcceptanceTransformRules $AcceptanceTransformRules -MetadataURL $AvanpostFAMMetadataURL

   где PowerShell-переменная:

   • $AvanpostFAMMetadataURL содержит URL-адрес SAML Discovery-документа Avanpost FAM (обычно http(s)://%Avanpost_FAM_base_URL%/.well-known/samlidp.xml, где %Avanpost_FAM_base_URL% – базовый URL Avanpost FAM); целевое значение параметра следует указать в PowerShell-сценарии вместо заменителя %URL-адрес_SAML_Discovery-документа_Avanpost_FAM%.

Настройка на стороне Avanpost FAM

Перед настройкой следует убедиться, что скорректированы CSP (Content-Security-Policy) на стороне сервера Nginx, где располагается Avanpost FAM. В секции location должна быть предусмотрена следующая строка:

add_header Content-Security-Policy "default-src 'self'; img-src 'self' data: https: *; style-src 'self' 'unsafe-inline' *; connect-src 'self' *; script-src 'self' 'unsafe-inline' https://idp.avanpost.local;";

Настройку на стороне административной консоли Avanpost FAM необходимо выполнять следующим образом:

1. Перейти во вкладку создания приложения, нажав кнопку "Добавить приложение" в сервисе "Приложения".

2. На этапе "Основные настройки" требуется ввести наименование (например, AD FS) и выбрать тип SAML (более подробно процесс создания и управления приложениями описан в разделах Управление приложениями и Управление SAML-приложениями).

3. На этапе "Настройки интеграции" необходимо установить настройки приложения (в URL, представленных в таблице в качестве примеров, вместо значения  “ADFS” необходимо указывать DNS сервера, на котором развернут Avanpost FAM ADFS Plugin):

   Параметр	Значение
   Issuer	http://ADFS/adfs/services/trust
   ACS	http://ADFS/adfs/ls
   Base URL	http://ADFS/adfs/ks/idpinitiatedsignon
   Backchannel-logout URL	http://ADFS/adfs/logout
   Подпись	Рекомендуется выбрать "Подписывать сообщение".
   Значение NameID	Рекомендуется выбрать "Адрес электронной почты".

4. На этапе "Настройки аутентификации" выбрать факторы аутентификации для приложения, установив переключатели напротив тех или иных факторов.
5. На этапе "Завершение" установить флажок "Сделать приложение активным" и сохранить.
6. Перейти в профиль созданного приложения из режима "Приложения" и войти во вкладку "Attributes".
7. Добавить следующие атрибуты для схем утверждений (claims):

   Наименование атрибута	Тип атрибута	Описание
   http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress	Значение из атрибута	Данному атрибуту присваивается значение электронной почты пользователя.
   http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name	Значение из атрибута	Данному атрибуту присваивается значение основных атрибутов имени и фамилии пользователя.
   http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn	Значение из атрибута	Данному атрибуту присваивается значение дополнительного атрибута UPN.

8. Во вкладке "Настройки" рекомендуется присвоить параметру Signing Algorithm значения SHA-256.   
9. Проверить корректность настроек и нажать кнопку "Сохранить". 

После завершения настройки рекомендуется:

• выполнить проверку корректности настройки в соответствии с данной инструкцией 
• отключить вход через Active Directory на стороне AD FS в соответствии с Приложением 4 текущей инструкции.

Для корректной обработки процедуры выхода Single Logout ADFS должен инициировать Logout-запрос на SAML Logout Endpoint на стороне FAM по следующему алгоритму:

1. Выполнение процедуры Logout из Exchange.
2. Exchange должен послать Logout-запрос в ADFS по стандарту WS-Federation.
3. ADFS должен отправить Logout-запрос в SAML Logout Endpoint Avanpost FAM.

Проверка настройки

Перед проверкой настройки необходимо выполнить следующие условия:

1. Пользователь имеет доступ к приложению AD FS в Avanpost FAM через группы (более подробно описано в статье Управление доступом).
2. У пользователя выполнена настройка необходимого аутентификатора (фактора аутентификации).
3. У пользователя должен быть заполнен атрибут «E-mail».
4. Проверяемый пользователь может быть идентифицирован Microsoft Exchange по значению E-mail, передаваемому в соответствующий атрибут UPN в ADFS и далее ретранслируемому средствами ADFS в Microsoft Exchange OWA и Microsoft ECP.

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

1. Инициировать выполнение аутентификации в Microsoft Exchange OWA или Microsoft ECP через браузер.
2. Дождаться, когда Microsoft Exchange перенаправить пользователя в AD FS.
3. На стороне AD FS выбрать вариант входа через Avanpost FAM.
4. Используя веб-интерфейс аутентификации Avanpost FAM, пройти аутентификацию с использованием настроенного сценария.
5. После завершения аутентификации пользователь должен авторизоваться в Microsoft Exchange OWA или Microsoft ECP.

В случае успешного выполнения указанной проверки настройка интеграции считается завершенной.

Диагностика ошибок

Сбор диагностической информации может осуществляться следующими способами:

1. Сбор сообщений об ошибке в браузере при взаимодействии с Microsoft Exchange OWA или Microsoft ECP в процессе аутентификации;
2. Сбор сообщений об ошибке в браузере при взаимодействии с Microsoft AD FS в процессе аутентификации;
3. Сбор сообщений об ошибке через eventvwr.msc на сервере Microsoft Exchange;
4. Сбор сообщений об ошибке через eventvwr.msc на сервере Microsoft AD FS;
5. Сбор сообщений об ошибке через systemctl для службы Avanpost FAM или просмотр файла журнала на сервере Avanpost FAM.

Приложение 1. Получение отпечатка (thumbprint) сертификата AD FS Signing

Для получения отпечатка сертификата AD FS Signing на сервере с AD FS открыть панель управления AD FS, далее открыть раздел «Служба» → «Сертификаты» и найти сертификат с «CN=ADFS Signing». В меню выбрать пункт «Просмотр сертификата» и скопировать его отпечаток:

Отпечаток (thumbprint) сертификата AD FS Signing получен и может быть использован в настройке.

Приложение 2. Добавление доверия проверяющей стороны (Relying Party Trust) OWA и ECP на стороне AD FS через панель управления AD FS

Данный вариант настройки подойдёт в качестве альтернативы при невозможности выполнения настройки через консоль AD FS PowerShell, описанную в основном разделе настройки.

Через консоль управления AD FS добавить «Доверие проверяющей стороны» на OWA и ECP, где в «Мастере добавления отношений доверия проверяющей стороны» на вкладке:

1. «Добро пожаловать» – выбрать вариант –  «поддерживающее утверждения»:
   
2. «Выбор источника данных» – «Ввод данных о проверяющей стороне вручную»:
   
3. «Отображаемое имя» – «OWA»:
   
4. «Настройка сертификата» – через кнопку «Обзор» указать доверенный сертификат (файл сертификата с Avanpost FAM):
   
5. «Настройка URL-адреса» – включить чекбокс «Включить поддержку пассивного протокола WS-Federation» и указать для параметра «URL-адрес пассивного протокола WS-Federation проверяющей стороны» в качестве значения URL, на котором размещён Exchange OWA (например, «https://mail.avanpost.ru/owa»):
   
6. «Настройка идентификатора» – указать значение, аналогичное указанному на предыдущей вкладке (например, «https://mail.avanpost.ru/owa»):
   
7. «Выбрать политику управления доступом» – выбрать вариант «Разрешение для каждого», если не требуется применение другой политики доступа со стороны Microsoft AD FS либо со стороны Microsoft Exchange:
   
8. «Готовность для добавления отношения доверия» – оставить по умолчанию.

Сохранить внесённые изменения.

Приложение 3. Добавление доверия поставщика утверждений Avanpost FAM (Claims Provider Trust) на стороне AD FS через панель управления AD FS

• http(s)://%Avanpost_FAM_base_URL%/.well-known/samlidp.xml

1. Через консоль управления AD FS добавить «Доверие поставщика утверждений» (Claims Provider Trust) к Avanpost FAM, где в «Мастере добавления отношений доверия поставщиков утверждений» на вкладке «Выбор источника данных» – для параметра «Адрес метаданных федерации» указать в качестве значения URL SAML Discovery-документа Avanpost FAM (обычно http(s)://%Avanpost_FAM_base_URL%/.well-known/samlidp.xml, где %Avanpost_FAM_base_URL% – базовый URL Avanpost FAM; пример значения для параметра – https://famdemo.avanpost.ru/.well-known/samlidp.xml):
   
2. Далее перейти в свойства созданной на предыдущем шаге записи доверия поставщика утверждений и открыть вкладку «Сертификаты». На данной вкладке необходимо добавить в доверенные корневые центры сертификации файл сертификата с Avanpost FAM:
   
3. Далее выбрать в списке созданную запись доверия поставщика утверждений и открыть меню «Изменить правила утверждений»:
   
4. Для того, чтобы ADFS извлекал необходимое для Microsoft Exchange утверждение из SAML Response, формируемого Avanpost FAM (в нашем случае – UPN, UserPrincipalName), необходимо добавить правило, выбрав шаблон «Проход через входящие утверждения или его фильтрация»:
   
5. На следующем шаге необходимо указать в параметре «Имя правила утверждения» – «UPN», выбрать тип входящего утверждения — «UPN» и выбрать вариант «Пройти по всем значениям утверждений»:
   

Сохранить внесённые изменения. 

Приложение 4. Отключение в AD FS стандартного метода аутентификации через Active Directory

Отключение стандартного метода входа в Microsoft Outlook Web Access через Active Directory позволяет:

• Исключить аутентификацию только по доменному логину и паролю в обход функции 2FA/MFA, обеспечиваемой интеграцией с Avanpost FAM;
• Обеспечить прозрачное автоматическое перенаправление пользователя с ADFS на аутентификацию через Avanpost FAM.

Для выполнения такой настройки в PowerShell на сервере Microsoft AD FS версии 2019 и старше следует выполнить от имени администратора команду:

Set-ADFSProperties -EnableLocalAuthenticationTypes $false

Для предыдущих версии Microsoft AD FS (младше 2019) можно использовать команду

Set-ADFSProperty -EnableLocalAuthenticationTypes $false

Для отмены выполненной настройки и возврата возможности вход через Active Directory следует выполнить такую же команду, заменив значение $false на $true.