# Двухфакторная аутентификация для входа в Windows (Winlogon)

## Описание

Simple2FA Credential Provider добавляет второй фактор к штатному входу в Windows по паролю. Провайдер работает как обёртка над системным парольным провайдером: пользователь вводит пароль как обычно, после чего подтверждает вход вторым фактором.

При входе в систему второй фактор запрашивается всегда. Для разблокировки экрана, входа по RDP и повышения прав (UAC) он включается отдельными параметрами. Если у пользователя второй фактор ещё не настроен, на плитке входа выводится QR-код со ссылкой на мастер настройки.

Пароль Windows проверяется локально на рабочей станции и на сервер Simple2FA не передаётся.

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

1. Пользователь выбирает свою учётную запись на экране входа (или вводит имя на плитке «Другой пользователь») и вводит пароль Windows.
2. Провайдер проверяет пароль локально. При неверном пароле вход отклоняется сразу — запрос второго фактора не отправляется.
3. Провайдер запрашивает у сервера Simple2FA способы подтверждения пользователя. Если их несколько, на плитке появляется список «Способ подтверждения входа».
4. Пользователь подтверждает вход: подтверждением на устройстве либо вводом одноразового кода в поле на плитке и повторным нажатием «Вход».
5. После успешной проверки обоих факторов пароль передаётся системе, и Windows завершает вход.

!!! note "Если пароль нельзя проверить заранее"
    Локальная проверка отклоняет вход только при заведомо неверных учётных данных: неверный пароль, отключённая, заблокированная или просроченная учётная запись, запрет входа по времени или по имени рабочей станции. Если пароль не удалось проверить по другой причине — например, недоступен контроллер домена, — провайдер выполняет безопасный откат: запрашивает второй фактор, а пароль проверяется системой уже после него. Предварительную проверку можно отключить параметром `VerifyPasswordFirst`.

## Требования

- Windows 10 версии 1809 и новее, Windows 11, Windows Server 2019 и 2022;
- архитектура пакета установки должна совпадать с архитектурой рабочих станций — x64 или ARM64. Для парка из разных архитектур используйте два пакета: библиотека другой архитектуры не установится;
- права администратора на рабочей станции;
- сетевой доступ рабочих станций к серверу Simple2FA по HTTPS;
- сертификат сервера Simple2FA должен быть доверенным в хранилище компьютера. Если используется собственный удостоверяющий центр, заранее распространите его корневой сертификат в **Локальный компьютер → Доверенные корневые центры сертификации**: иначе соединение не установится и провайдер отработает по правилу `OfflineMode`.

Дополнительные среды выполнения (VC++ Redistributable и т.п.) на целевых машинах не требуются.

!!! note "Работа через прокси"
    Провайдер обращается к серверу до входа пользователя, от имени системы, поэтому использует не пользовательские настройки прокси, а машинные настройки WinHTTP. Если доступ к серверу Simple2FA возможен только через прокси, задайте его на рабочих станциях командой `netsh winhttp set proxy <адрес:порт>`.

## Подготовка в Simple2FA

Войдите в панель администратора локального инстанса, перейдите в раздел «Настройка ресурсов» и создайте новый ресурс:

| Поле | Значение |
| --- | --- |
| Название | Вход в Windows (или любое удобное) |
| Протокол | HTTP |
| API Key | Ключ ресурса, который будет указан в настройках провайдера на рабочих станциях. Создаётся автоматически |
| Проверять первый фактор | Выключить — пароль Windows проверяется локально на рабочей станции и в Simple2FA не передаётся |

В глобальных настройках убедитесь, что указан корректный API-ключ организации для связи локального инстанса с облаком.

## Настройка пакета установки

Пакет установки содержит папку `installer` со скриптами, файлом настроек, библиотекой провайдера и шаблонами для групповых политик. Перед установкой заполните файл настроек `installer\install.settings.psd1`:

```powershell
@{
    BackendBaseUrl      = 'https://2fa.corp.example'   # URL сервера Simple2FA, без / в конце
    ApiKey              = 'REPLACE_WITH_RESOURCE_API_KEY'

    OfflineMode         = 'open'      # open: вход по паролю при недоступном сервере; closed: запрет
    EnforcementMode     = 'enforce'   # enforce | permissive | monitor — что делать при сбое второго фактора
    EnrollPolicy        = 'block'     # block: QR и запрет входа; grace: QR и разрешение входа
    UiLanguage          = 'ru'        # ru | en

    HideOtherProviders  = $true       # скрыть пароль/PIN/Hello/биометрию; требует перезагрузки
    VerifyPasswordFirst = $true       # проверять пароль Windows до второго фактора
    RequireOnUnlock     = $true       # второй фактор при разблокировке
    RequireOnRdp        = $true       # второй фактор при входе по RDP
    UacMode             = $false      # второй фактор при повышении прав (UAC)
    EmergencyLogins     = ''          # аварийный вход: только пароль Windows, без обращения к серверу

    HttpTimeoutMs       = 35000       # ожидание подтверждения, не меньше 32000
    InstallDir          = 'C:\Program Files\Orbsoft\Simple2FA'
    SourceDll           = ''          # пусто: библиотека ищется автоматически
    LogFile             = ''          # пусто: журнал установки не ведётся
}
```

| Параметр | По умолчанию | Назначение |
| --- | --- | --- |
| `BackendBaseUrl` | — | Адрес сервера Simple2FA, без `/` в конце |
| `ApiKey` | — | API Key из карточки ресурса Simple2FA |
| `OfflineMode` | `open` | Поведение при недоступном сервере: `open` разрешает вход по одному паролю, `closed` запрещает вход |
| `EnforcementMode` | `enforce` | Поведение при сбое второго фактора после верного пароля, см. [«Режимы применения»](#режимы-применения) |
| `EnrollPolicy` | `block` | Поведение для пользователей без настроенного второго фактора: `block` показывает QR-код и блокирует вход, `grace` показывает QR-код и разрешает вход |
| `UiLanguage` | `ru` | Язык интерфейса на экране входа: `ru` или `en` |
| `HideOtherProviders` | `$true` | Скрывает остальные способы входа (PIN, Windows Hello, биометрию, отдельную плитку пароля), закрывая обход второго фактора через «Параметры входа». Вступает в силу после перезагрузки |
| `VerifyPasswordFirst` | `$true` | Проверять пароль Windows до запроса второго фактора |
| `RequireOnUnlock` | `$true` | Требовать второй фактор при разблокировке экрана |
| `RequireOnRdp` | `$true` | Требовать второй фактор в сеансе удалённого рабочего стола — и при входе, и при разблокировке внутри сеанса |
| `UacMode` | `$false` | Требовать второй фактор при повышении прав (UAC) |
| `EmergencyLogins` | — | Учётные записи аварийного входа через запятую, см. [«Аварийный вход»](#аварийный-вход) |
| `HttpTimeoutMs` | `35000` | Общее время ожидания подтверждения в миллисекундах. Не задавайте меньше 32000: ожидание подтверждения на сервере длится около 31 секунды |
| `InstallDir` | `C:\Program Files\Orbsoft\Simple2FA` | Каталог установки библиотеки |
| `SourceDll` | — | Путь к библиотеке провайдера, если автоматический поиск не подходит |
| `LogFile` | — | Путь к журналу установки |

### Режимы применения

`EnforcementMode` определяет, что происходит, когда пароль Windows верен, а второй фактор подтвердить не удалось. Пароль обязателен в любом режиме.

| Ситуация | `enforce` | `permissive` | `monitor` |
| --- | --- | --- | --- |
| Пользователь отклонил запрос или не ответил вовремя | Отказ | Отказ | Вход |
| Ошибка на стороне сервера или в протоколе, неверный API Key | Отказ | Вход | Вход |
| Сервер недоступен | По `OfflineMode` | Вход | Вход |
| Второй фактор не настроен | По `EnrollPolicy` | По `EnrollPolicy` | Вход |
| Пользователь неактивен, не найден в Simple2FA, нет доступа к ресурсу или лицензии | Отказ | Отказ | Отказ |

Каждый пропуск записывается в журнал приложений. `permissive` подходит для внедрения, когда сбой инфраструктуры Simple2FA не должен останавливать работу; `monitor` — для пилота, когда решения второго фактора нужно только наблюдать.

Обратите внимание на последнюю строку: даже в режиме `monitor` пользователь, которого нет в Simple2FA, войти не сможет. Чтобы такие пользователи входили по одному паролю, включите в глобальных настройках панели пропуск пользователей, отсутствующих в системе.

### Аварийный вход

`EmergencyLogins` — список учётных записей, для которых второй фактор не запрашивается и сервер Simple2FA не вызывается вовсе. Пароль Windows по-прежнему обязателен. Вход такой записи попадает в журнал приложений с пометкой `Emergency login bypass`.

```powershell
EmergencyLogins = 'CORP\admin-break-glass, localadmin'
```

Запись сравнивается по имени учётной записи: `localadmin` в списке подойдёт и для `.\localadmin`, и для `CORP\localadmin`. Чтобы ограничить запись доменом, укажите её полностью — `CORP\localadmin`. На доменной машине локальную учётную запись на плитке «Другой пользователь» вводят с указанием домена — `.\localadmin`, иначе имя будет дополнено доменом рабочей станции.

Заведите такую запись до включения `HideOtherProviders`: она остаётся единственным способом войти на машину, если сервер Simple2FA недоступен при `OfflineMode = 'closed'` или у администратора нет настроенного второго фактора. Держите список минимальным — это обход второго фактора, и он действует на всех машинах с этой конфигурацией.

## Установка на одну машину

Запустите установку с автоматическим повышением прав (запрос UAC появится сам):

```powershell
powershell -ExecutionPolicy Bypass -File .\installer\run_install.ps1
```

Параметры берутся из файла настроек. В командной строке `run_install.ps1` можно переопределить `BackendBaseUrl`, `ApiKey`, `SettingsFile`, `SourceDll`, `OfflineMode`, `EnforcementMode`, `EnrollPolicy`, `UiLanguage`, `HideOtherProviders` и `EmergencyLogins`:

```powershell
powershell -ExecutionPolicy Bypass -File .\installer\run_install.ps1 `
  -BackendBaseUrl https://2fa.corp.local -ApiKey "<Resource.api_key>"
```

Остальные параметры задаются в файле настроек либо при прямом запуске `install.ps1` из окна администратора.

Журнал последней установки сохраняется в `installer\install-last.log`.

После установки с `HideOtherProviders` требуется перезагрузка.

Установщик идемпотентен: он сравнивает установленную библиотеку и все параметры конфигурации с файлом настроек и завершается без изменений, если всё уже применено. Изменённый параметр применяется при следующем запуске — ключ `-Force` для этого не нужен. Он пригодится, только чтобы переустановить провайдер при совпадающих настройках, например при повреждённой регистрации:

```powershell
powershell -ExecutionPolicy Bypass -File .\installer\run_install.ps1 -Force
```

!!! warning "Сначала проверьте на тестовой машине"
    Перед развёртыванием на парк машин проверьте установку на снимке виртуальной машины: некорректно настроенный провайдер входа может заблокировать доступ к системе. Подключение по RDP с включённой проверкой подлинности на уровне сети (NLA) остаётся рабочим: пароль в нём проверяется до создания сеанса, и экран входа рабочей станции в этом не участвует.

## Развёртывание через групповые политики

Провайдер устанавливается на парк машин startup-скриптом групповой политики:

1. Скопируйте папку `installer` из пакета установки в каталог политики в SysVol.
2. Заполните `install.settings.psd1`.
3. В редакторе GPO откройте **Computer Configuration → Policies → Windows Settings → Scripts (Startup/Shutdown) → Startup → PowerShell Scripts → Add** и укажите `install.ps1`. Параметры не требуются — они берутся из файла настроек.
4. Примените политику и перезагрузите машины.

Благодаря идемпотентности установщика скрипт можно оставить выполняться при каждой загрузке: изменения в `install.settings.psd1` и новая версия библиотеки применяются на машинах при следующей перезагрузке сами.

В составе пакета также поставляются шаблоны ADMX/ADML для управления параметрами через редактор групповых политик — они покрывают все параметры конфигурации и записывают их в тот же ключ реестра, что и установщик.

!!! warning "Файл настроек и шаблоны ADMX не совмещаются"
    Startup-скрипт при каждой загрузке сверяет значения в реестре с файлом настроек и перезаписывает их при расхождении. Если параметры заданы через ADMX и отличаются от `install.settings.psd1`, они будут возвращаться к значениям файла после каждой перезагрузки. Выберите один источник: либо файл настроек, либо ADMX с одинаковыми значениями в обоих местах. Скрытие остальных способов входа шаблоном ADMX не включается: `HideOtherProviders` в нём — только признак, сами ключи политики записывает установщик.

## Параметры в реестре

Установщик записывает конфигурацию в `HKLM\SOFTWARE\Orbsoft\Simple2FA\Logon`. Имена значений совпадают с параметрами файла настроек: строковые — `BackendBaseUrl`, `ApiKey`, `OfflineMode`, `EnforcementMode`, `EnrollPolicy`, `UiLanguage`, `EmergencyLogins`; числовые (`DWORD`) — `HttpTimeoutMs`, `RequireOnUnlock`, `RequireOnRdp`, `UacMode`, `VerifyPasswordFirst`, `HideOtherProviders`. Провайдер читает их при каждом показе экрана входа, перезагрузка после правки не нужна.

При `HideOtherProviders` установщик дополнительно записывает политику входа: `ExcludedCredentialProviders` с идентификаторами парольного провайдера, PIN, Windows Hello и смарт-карт, `DefaultCredentialProvider` с идентификатором Simple2FA и запрет входа по PIN и биометрии. Эти ключи вступают в силу после перезагрузки. Если они управляются доменной политикой и недоступны для записи, установщик сообщит об этом, а плитки других способов входа останутся видимыми.

## Проверка работы

- Заблокируйте экран или выйдите из системы,
- Выберите свою учётную запись и введите пароль Windows (первый фактор),
- Получите запрос второго фактора,
- Подтвердите второй фактор,
- После подтверждения вход в Windows будет выполнен.

Результат попытки входа доступен в панели администратора, в разделе [«Попытки авторизации»](../../admin/auth-attempts.md). Вместе с логином на сервер передаются имя рабочей станции и её IP-адреса. Попытки, отклонённые на самой рабочей станции — неверный пароль Windows, недоступность сервера, аварийный вход, — до Simple2FA не доходят и в этом разделе не отображаются; их видно в журнале приложений Windows, источник `Simple2FA`.

Для диагностики на рабочей станции используйте скрипт из состава пакета:

```powershell
powershell -ExecutionPolicy Bypass -File .\installer\diagnose.ps1
```

Скрипт выводит наличие и версию библиотеки, состояние COM-регистрации и регистрации провайдера входа, текущую конфигурацию (API Key маскируется), список аварийных учётных записей, ключи политики скрытия способов входа и последние события журнала приложений от источника `Simple2FA`.

## Безопасность

- Пароль Windows проверяется локально и на сервер Simple2FA не передаётся.
- При `VerifyPasswordFirst = $true` неверный пароль отклоняется до запроса второго фактора — запросы на подтверждение не приходят на чужие попытки входа.
- Секреты в журналы не записываются.
- Режим `OfflineMode = 'closed'` запрещает вход при недоступном сервере — для сценариев, где доступность второго фактора критична.
- `HideOtherProviders = $true` закрывает обход второго фактора через PIN, Windows Hello и биометрию.
- `EmergencyLogins` — намеренный обход второго фактора. Каждое его использование записывается в журнал приложений; список стоит проверять при аудите вместе с журналом.

!!! warning "Неполная конфигурация отключает второй фактор"
    Если в реестре рабочей станции отсутствует `BackendBaseUrl` или `ApiKey`, провайдер пропускает вход по одному паролю и записывает предупреждение в журнал приложений. Так сделано, чтобы повреждённая конфигурация не заблокировала доступ к машине, но это означает, что `OfflineMode = 'closed'` не защищает от удаления параметров из реестра. Ограничьте права на изменение ключа `HKLM\SOFTWARE\Orbsoft\Simple2FA\Logon` и контролируйте состояние установки скриптом `diagnose.ps1`.

## Ограничения

- На плитке «Другой пользователь» имя без домена дополняется доменом рабочей станции. Для локальной учётной записи на доменной машине укажите `.\имя` или `ИМЯ_КОМПЬЮТЕРА\имя`.
- Если выбран способ с одноразовым кодом, вход выполняется в два шага: после пароля на плитке появляется поле для кода, затем нужно нажать «Вход» ещё раз. Остальные способы подтверждаются на устройстве после ввода пароля.
- Смена пароля на экране входа выполняется без второго фактора.

## Удаление

```powershell
powershell -ExecutionPolicy Bypass -File .\installer\uninstall.ps1
```

Скрипт снимает регистрацию провайдера, откатывает политику скрытия способов входа по фактическому состоянию ключей, удаляет библиотеку вместе с каталогом установки, источник журнала приложений и ключ конфигурации `HKLM\SOFTWARE\Orbsoft\Simple2FA`. Чтобы сохранить конфигурацию в реестре, запустите скрипт с ключом `-KeepConfig`. После удаления рекомендуется перезагрузка.

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

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