Двухфакторная аутентификация для ADFS
Описание
При входе через AD FS пользователь проходит двухэтапную аутентификацию: вводит логин и пароль (первый фактор), после чего подтверждает вход вторым фактором Simple2FA.
Первый фактор AD FS проверяет самостоятельно через Active Directory. Второй фактор запрашивает адаптер Simple2FA (OrbsoftTwoFaAdapter), зарегистрированный в AD FS как дополнительный метод аутентификации (MFA).
Схема работы:
- Пользователь открывает корпоративное приложение, защищённое AD FS.
- AD FS запрашивает логин и пароль и проверяет их через Active Directory.
- Если для приложения включена политика MFA, AD FS передаёт управление адаптеру Simple2FA.
- Адаптер обращается к локальному инстансу Simple2FA, в браузере пользователя открывается окно подтверждения второго фактора.
- Пользователь подтверждает вход.
- После успешной проверки AD FS выдаёт токен, и пользователь попадает в приложение.
Требования
Сервер AD FS
- Windows Server 2016 или новее с ролью AD FS.
- PowerShell от имени администратора.
- Корректное системное время на сервере AD FS и на сервере локального инстанса Simple2FA (расхождение во времени ломает проверку одноразовых кодов).
Сетевой доступ
- С сервера AD FS — к локальному инстансу Simple2FA по HTTPS (адрес указывается в
$ApiUrl). - С сервера локального инстанса — к
api.cloud.simple2fa.ru, TCP 443 (напрямую или через HTTP-прокси). - Из браузера пользователя — к
access.simple2fa.ru, TCP 443 (в этом окне пользователь подтверждает второй фактор).
Сертификат локального инстанса
Адаптер обращается к локальному инстансу по HTTPS и проверяет сертификат. Если на локальном инстансе самоподписанный сертификат, добавьте его в хранилище Trusted Root Certification Authorities на каждом узле AD FS. Для рабочей эксплуатации рекомендуется сертификат внутреннего удостоверяющего центра или доверенный публичный.
Content-Security-Policy на AD FS
Окно подтверждения второго фактора открывается во фрейме с access.simple2fa.ru. Если на AD FS включён заголовок Content-Security-Policy с default-src 'self' (в AD FS 2019 включён по умолчанию), браузер заблокирует фрейм. Настройка — в разделе «Настройка политик в AD FS».
Подготовка в Simple2FA
Войдите в панель администратора локального инстанса, перейдите в раздел «Настройка ресурсов» и создайте новый ресурс:
| Поле | Значение |
|---|---|
| Название | ADFS (или любое удобное) |
| Описание | Краткое описание ресурса |
| Проверка первого фактора | Отключена — первый фактор проверяет AD FS |
После сохранения скопируйте API key ресурса — он понадобится в конфигурации адаптера.
В глобальных настройках убедитесь, что указан API-ключ организации для связи локального инстанса с облаком.
Установка адаптера
1) Распакуйте дистрибутив
Скопируйте папку dist-adfs на сервер AD FS, например в C:\Orbsoft2FA-Adfs\. Состав дистрибутива:
dist-adfs\
├── install.ps1 — установочный скрипт
├── uninstall.ps1 — скрипт удаления
├── install.config.ps1 — файл конфигурации (редактируется вручную)
├── Orbsoft.TwoFa.Adfs.Adapter.dll — адаптер
├── Orbsoft.TwoFa.Adfs.Adapter.dll.config.template — шаблон конфига адаптера (не редактировать)
├── adfs-theme-onload.js — скрипт для веб-темы AD FS
└── README.md
2) Заполните install.config.ps1
Единственный файл, который нужно редактировать вручную, — install.config.ps1. Итоговый конфиг адаптера (Orbsoft.TwoFa.Adfs.Adapter.dll.config) скрипт формирует из шаблона автоматически.
notepad install.config.ps1
Параметры:
$ApiUrl— URL локального инстанса Simple2FA, доступный с сервера AD FS по HTTPS. Например:https://local2fa.company.local.$ResourceApiKey— API key ресурса из панели Simple2FA (см. «Подготовка в Simple2FA»).$WebThemeName— имя веб-темы AD FS, в которую устанавливаетсяonload.js. Если оставить пустым, скрипт использует активную тему (при встроенной теме Default создаёт её копию).$PassiveWtRealm— URL приложения, на которое возвращать пользователя после выхода (wsignout). Обычно — корневой URL OWA, напримерhttps://mail.company.local/owa/. Если AD FS не используется для OWA, можно оставить пустым.$PassiveWctx— контекст passive-входа, для OWA оставьте значение по умолчаниюrm=0&id=passive&ru=/owa/.$SessionTimeoutSeconds— время (сек.), в течение которого AD FS не запрашивает второй фактор повторно для того же пользователя. По умолчанию 840.$TimeoutSeconds— таймаут ожидания ответа локального инстанса, сек. По умолчанию 35.$FailOpen— поведение при недоступности локального инстанса:$false(по умолчанию) — вход запрещается;$true— вход разрешается без второго фактора. Включать только осознанно.$AllowInsecureTls— разрешить самоподписанный сертификат локального инстанса. По умолчанию$false; в рабочей эксплуатации используйте доверенный сертификат.$AuthHeaderMode— режим передачи API-ключа, оставьтеBearer.
3) Запустите установку
В PowerShell от имени администратора на сервере AD FS:
cd C:\Orbsoft2FA-Adfs
Set-ExecutionPolicy -Scope Process Bypass
.\install.ps1
Скрипт выполняет пять шагов и сам перезапускает службу AD FS — дополнительные действия не требуются:
- Останавливает службу AD FS.
- Копирует адаптер и сформированный конфиг в
C:\Windows\ADFS\. - Запускает AD FS.
- Регистрирует провайдер OrbsoftTwoFaAdapter, добавляет его в глобальную политику аутентификации как метод MFA и перезапускает AD FS.
- Устанавливает
onload.jsв веб-тему и создаёт источник событийOrbsoft2FA-ADFSв журнале Application.
Успешное завершение выглядит так:
[4/5] Registering authentication provider ...
Node role: PrimaryComputer
Registered and activated 'OrbsoftTwoFaAdapter'.
AD FS restarted.
[5/5] Installing web theme onload.js ...
Theme updated.
Installation complete.
Предупреждение PS0105: No authentication provider with name 'OrbsoftTwoFaAdapter' is present in the policy store при первой установке — штатное, означает, что провайдер регистрируется впервые.
4) Ферма AD FS
Если AD FS развёрнут фермой, запустите install.ps1 на каждом узле. На secondary-узлах скрипт только копирует адаптер и конфиг; регистрация провайдера выполняется на primary-узле и реплицируется на остальные. После установки на всех узлах перезапустите службу AD FS на secondary-узлах. Сертификат локального инстанса (если самоподписанный) должен быть добавлен в доверенные на каждом узле. Изменения политик, идентификаторов и заголовков, сделанные на primary, доезжают до secondary-узлов с задержкой репликации (по умолчанию до 5 минут) — учитывайте это при проверке.
Настройка политик в AD FS
Установка регистрирует метод MFA, но не включает его требование для приложений — это делается политикой доступа отдельно для каждого приложения.
Проверка метода MFA
Откройте AD FS Management → Service → Authentication Methods → Additional Authentication Methods и убедитесь, что OrbsoftTwoFaAdapter присутствует и отмечен. Или в PowerShell:
(Get-AdfsGlobalAuthenticationPolicy).AdditionalAuthenticationProvider
Relying Party Trust (SAML / WS-Federation, например OWA)
AD FS Management → Relying Party Trusts → выберите приложение → Edit Access Control Policy → выберите политику с требованием MFA, например Permit everyone and require MFA.
Application Group (OAuth 2.0 / OpenID Connect)
В Application Group политика доступа задаётся на компоненте Web API (relying party), а не на Native application или Server application. Откройте AD FS Management → Application Groups → группа → компонент Web API → Access Control Policy → политика с требованием MFA.
Политика Web API применяется только к запросам токена для этого Web API: AD FS определяет его по параметру resource в запросе /adfs/oauth2/authorize и сопоставляет со значением на вкладке Identifiers. Если приложение использует AD FS только для входа (запрашивает id_token без resource) или передаёт идентификатор, не совпадающий с Web API, политика не проверяется, и второй фактор не запрашивается. Варианты решения:
- настроить приложение так, чтобы оно передавало
resourceс идентификатором Web API; - либо добавить в Identifiers Web API значение, равное
client_idклиентского приложения, — тогда AD FS применит политику Web API и к запросамid_token.
Проверить, к каким приложениям применена MFA-политика:
Get-AdfsRelyingPartyTrust | Select Name, AccessControlPolicyName
Get-AdfsWebApiApplication | Select Name, AccessControlPolicyName
Разрешить фрейм Simple2FA (Content-Security-Policy)
Проверьте текущие заголовки:
Get-AdfsResponseHeaders
Если в Content-Security-Policy нет frame-src с access.simple2fa.ru, добавьте его (на primary-узле, применяется ко всей ферме):
Set-AdfsResponseHeaders -EnableResponseHeaders $true
Set-AdfsResponseHeaders -SetHeaderName "Content-Security-Policy" `
-SetHeaderValue "default-src 'self' 'unsafe-inline' 'unsafe-eval'; img-src 'self' data:; frame-src 'self' https://access.simple2fa.ru"
Если у вас уже задана своя политика — добавьте в неё только директиву frame-src 'self' https://access.simple2fa.ru, не заменяя остальное. Настройка выполняется один раз на сервере, на рабочих местах пользователей ничего менять не нужно.
Проверка работы
Проверяйте вход в приватном окне браузера: если пользователь уже вошёл в AD FS ранее, SSO-сессия выдаётся без повторной аутентификации, и второй фактор не запрашивается до её истечения.
- Откройте корпоративное приложение.
- Введите логин и пароль.
- Дождитесь окна подтверждения второго фактора Simple2FA.
- Подтвердите вход вторым фактором.
- После успешной проверки откроется приложение.
Диагностика
Проверка регистрации адаптера
Get-AdfsAuthenticationProvider -Name OrbsoftTwoFaAdapter
(Get-AdfsGlobalAuthenticationPolicy).AdditionalAuthenticationProvider
Журналы
- Event Viewer → Applications and Services Logs → AD FS → Admin — ошибки загрузки адаптера и обработки MFA на стороне AD FS.
- Event Viewer → Windows Logs → Application, источник Orbsoft2FA-ADFS — события самого адаптера (обращения к локальному инстансу, результаты проверки). В ферме смотрите на том узле, который обработал вход (Node name на странице ошибки AD FS).
- Панель Simple2FA — «Попытки авторизации» и «История ошибок»: запросы, дошедшие до локального инстанса.
Типовые проблемы
- Второй фактор не запрашивается — повторите вход в приватном окне (с живой SSO-сессией AD FS повторную аутентификацию не запрашивает) и проверьте, что MFA-политика применена к нужному приложению. Для Application Group убедитесь, что приложение запрашивает токен именно для Web API с политикой (параметр
resourceсовпадает с его Identifier) — см. раздел «Настройка политик». Какой объект обработал вход, видно в событиях 1200/1202 журнала Security послеSet-AdfsProperties -AuditLevel Verbose. - «Could not start 2FA session» после ввода пароля — адаптер не смог обратиться к локальному инстансу. В журнале Application (источник Orbsoft2FA-ADFS) будет причина: Network error calling /api/initiate-2fa означает сетевую или TLS-ошибку — проверьте доступность
$ApiUrlс узла AD FS (Invoke-WebRequest -Uri $ApiUrl -UseBasicParsing) и доверие к сертификату локального инстанса; ошибка авторизации — проверьте API key ресурса. - Окно Simple2FA пустое или не загружается — откройте консоль браузера (F12). Ошибка Framing ‘https://access.simple2fa.ru/’ violates the following Content Security Policy directive означает, что фрейм заблокирован политикой AD FS — см. «Разрешить фрейм Simple2FA». Если ошибки нет — с рабочего места недоступен
access.simple2fa.ru:443. - Второй фактор не приходит или не принимается — проверьте связь локального инстанса с облаком (
api.cloud.simple2fa.ru:443) и синхронизацию времени на серверах.
Удаление
В PowerShell от имени администратора из папки дистрибутива:
.\uninstall.ps1
Скрипт удаляет провайдер из политики аутентификации, снимает регистрацию и удаляет файлы адаптера из C:\Windows\ADFS\. Веб-тема и политики доступа приложений не изменяются — при необходимости верните им прежние значения вручную.