Настройка 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:

1. В консоли 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 -AdfsSignCertificateThumbprint $ADFSSigningCertificateThumbprint
   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-переменная:

   • $ADFSSigningCertificateThumbprint содержит отпечаток (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%.

На стороне сервера AD FS:

1. Через 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%.

2. Через 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 через веб-приложение административной консоли:

1. Создать приложение с типом SAML:
   1. Указать наименование приложения, к примеру, «AD FS»;
   2. Указать значение параметра «Issuer» – URL вида http://%хост_AD_FS%/adfs/services/trust; пример значения для параметра Issuer: http://ADFS.avanpost.ru/adfs/services/trust;
   3. Указать значение параметра «ACS» – URL вида http(s)://%хост_AD_FS%/adfs/ls; пример значения для параметра ACS: http://adfs.avanpost.ru/adfs/ls;
   4. Значение параметра «Базовый URL» можно оставить пустым либо заполнить адресом сервиса ADFS, к примеру, http://adfs.avanpost.ru/; на функционирование интеграции данный параметр не влияет;
   5. Значение параметра «Logout» оставить пустым;
   6. Указать значение параметра «NameID Format», выбрав вариант «Не указан»;
   7. Указать значение параметра «Значение NameID», выбрав вариант «Адрес электронной почты».
2. После создания приложения проверить значения параметров в карточке приложения на вкладке «Настройки»:
   1. Параметр «Подпись» должен иметь значение «Подписывать сообщение»;
   2. Параметр «Signing Algorithm» должен иметь значение «SHA256»;
3. В карточке приложения на вкладке «Attributes» создать новый атрибут:
   1. Наименование – «http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn»;
   2. Тип атрибута – «Значение из атрибута»;
   3. Значение – «user.email»; либо можно использовать другой атрибут, который будет содержать корректное значение атрибута UPN (UserPrincipalName) с точки зрения Microsoft Exchange для сопоставления пользователя FAM с пользователем Microsoft Exchange.
4. Указать в приложении сценарий аутентификации. Для тестирования интеграции можно настроить сценарий, состоящий из одного шага, на котором указан либо шаг «Идентификация», либо шаг «Password». 

Настройка выполнена. Можно перейти к проверке настройки либо рассмотреть возможность отключения способа входа через 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.