# Двухфакторная аутентификация для ADFS

## Описание

При входе через AD FS пользователь проходит двухэтапную аутентификацию: вводит логин и пароль (первый фактор), после чего подтверждает вход вторым фактором Simple2FA.

Первый фактор AD FS проверяет самостоятельно через Active Directory. Второй фактор запрашивает адаптер Simple2FA (**OrbsoftTwoFaAdapter**), зарегистрированный в AD FS как дополнительный метод аутентификации (MFA).

Схема работы:

1. Пользователь открывает корпоративное приложение, защищённое AD FS.
2. AD FS запрашивает логин и пароль и проверяет их через Active Directory.
3. Если для приложения включена политика MFA, AD FS передаёт управление адаптеру Simple2FA.
4. Адаптер обращается к локальному инстансу Simple2FA, в браузере пользователя открывается окно подтверждения второго фактора.
5. Пользователь подтверждает вход.
6. После успешной проверки 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 ресурса — он понадобится в конфигурации адаптера.

В [глобальных настройках](../../admin/global-settings.md) убедитесь, что указан API-ключ организации для связи локального инстанса с облаком.

## Установка адаптера

**1) Распакуйте дистрибутив**

Скопируйте папку `dist-adfs` на сервер AD FS, например в `C:\Orbsoft2FA-Adfs\`. Состав дистрибутива:

```text
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`) скрипт формирует из шаблона автоматически.

```powershell
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:

```powershell
cd C:\Orbsoft2FA-Adfs
Set-ExecutionPolicy -Scope Process Bypass
.\install.ps1
```

Скрипт выполняет пять шагов и сам перезапускает службу AD FS — дополнительные действия не требуются:

1. Останавливает службу AD FS.
2. Копирует адаптер и сформированный конфиг в `C:\Windows\ADFS\`.
3. Запускает AD FS.
4. Регистрирует провайдер **OrbsoftTwoFaAdapter**, добавляет его в глобальную политику аутентификации как метод MFA и перезапускает AD FS.
5. Устанавливает `onload.js` в веб-тему и создаёт источник событий `Orbsoft2FA-ADFS` в журнале Application.

Успешное завершение выглядит так:

```text
[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:

```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-политика:

```powershell
Get-AdfsRelyingPartyTrust | Select Name, AccessControlPolicyName
Get-AdfsWebApiApplication | Select Name, AccessControlPolicyName
```

**Разрешить фрейм Simple2FA (Content-Security-Policy)**

Проверьте текущие заголовки:

```powershell
Get-AdfsResponseHeaders
```

Если в Content-Security-Policy нет `frame-src` с `access.simple2fa.ru`, добавьте его (на primary-узле, применяется ко всей ферме):

```powershell
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-сессия выдаётся без повторной аутентификации, и второй фактор не запрашивается до её истечения.

1. Откройте корпоративное приложение.
2. Введите логин и пароль.
3. Дождитесь окна подтверждения второго фактора Simple2FA.
4. Подтвердите вход вторым фактором.
5. После успешной проверки откроется приложение.

## Диагностика

**Проверка регистрации адаптера**

```powershell
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 — [«Попытки авторизации»](../../admin/auth-attempts.md) и [«История ошибок»](../../admin/error-history.md): запросы, дошедшие до локального инстанса.

**Типовые проблемы**

- **Второй фактор не запрашивается** — повторите вход в приватном окне (с живой 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 от имени администратора из папки дистрибутива:

```powershell
.\uninstall.ps1
```

Скрипт удаляет провайдер из политики аутентификации, снимает регистрацию и удаляет файлы адаптера из `C:\Windows\ADFS\`. Веб-тема и политики доступа приложений не изменяются — при необходимости верните им прежние значения вручную.

## Смотрите также

- [Рабочие столы и Windows](index.md)
- [Начало работы](../../start/index.md)
- [Сценарии использования](../../start/scenarios.md)