Создание подключаемых модулей с помощью модели оценки риска AD FS за 2019 г.

Статья
02/13/2024

Теперь вы можете создавать собственные подключаемые модули, чтобы блокировать или назначать оценку риска для запросов проверки подлинности на различных этапах— полученные запросы, предварительной проверки подлинности и после проверки подлинности. Это можно сделать с помощью новой модели оценки рисков, представленной с AD FS 2019.

Что такое модель оценки рисков?

Модель оценки рисков — это набор интерфейсов и классов, которые позволяют разработчикам читать заголовки запросов проверки подлинности и реализовывать собственную логику оценки рисков. Реализованный код (подключаемый модуль) затем выполняется в соответствии с процессом проверки подлинности AD FS. Например, используя интерфейсы и классы, включенные в модель, можно реализовать код для блокировки или разрешения запроса проверки подлинности на основе IP-адреса клиента, включенного в заголовок запроса. AD FS выполнит код для каждого запроса проверки подлинности и выполнит соответствующие действия в соответствии с реализованной логикой.

Модель позволяет подключать код на любом из трех этапов конвейера проверки подлинности AD FS, как показано ниже:

Diagram that shows the three stages of A D F S authentication.

Этап получения запроса— позволяет создавать подключаемые модули для разрешения или блокировки запроса, когда AD FS получает запрос проверки подлинности, т. е. перед вводом учетных данных пользователем. Контекст запроса (например, IP-адрес клиента, метод HTTP, DNS-сервер прокси-сервера и т. д.) можно использовать на этом этапе для оценки риска. Например, можно создать подключаемый модуль для чтения IP-адреса из контекста запроса и заблокировать запрос проверки подлинности, если IP-адрес находится в предварительно определенном списке рискованных IP-адресов.
Этап предварительной проверки подлинности— позволяет создавать подключаемые модули для разрешения или блокировки запросов в точке, в которой пользователь предоставляет учетные данные, но до оценки AD FS. На этом этапе в дополнение к контексту запроса также содержатся сведения о контексте безопасности (например, маркер пользователя, идентификатор пользователя и т. д.) и контекст протокола (например, протокол проверки подлинности, clientID, resourceID и т. д.) для использования в логике оценки рисков. Например, можно создать подключаемый модуль, чтобы предотвратить атаки с распыления паролем, считывая пароль пользователя из маркера пользователя и блокируя запрос проверки подлинности, если пароль находится в предварительно определенном списке рискованных паролей.
После проверки подлинности — позволяет создавать подключаемый модуль для оценки риска после того, как пользователь предоставил учетные данные и AD FS выполнил проверку подлинности. На этом этапе помимо контекста запроса, контекста безопасности и контекста протокола также содержатся сведения о результатах проверки подлинности (успешно или сбое). Подключаемый модуль может оценить оценку риска на основе доступных сведений и передать оценку риска для утверждения и правил политики для дальнейшей оценки.

Чтобы лучше понять, как создать подключаемый модуль оценки рисков и запустить его в соответствии с процессом AD FS, давайте создадим пример подключаемого модуля, который блокирует запросы, поступающие из определенных IP-адресов экстрасети , идентифицированных как рискованные, зарегистрируйте подключаемый модуль в AD FS и, наконец, протестируйте функциональные возможности.

Примечание.

Кроме того, можно создать подключаемый модуль с рискованным пользователем, пример подключаемого модуля, который использует уровень риска пользователей, определенный Защита идентификации Microsoft Entra для блокировки проверки подлинности или применения многофакторной проверки подлинности (MFA). Здесь доступны шаги по созданию подключаемого модуля пользователя с рискованным пользователем.

Создание примера подключаемого модуля

Примечание.

В этом пошаговом руководстве показано, как создать пример подключаемого модуля. Решение, которое мы создаем, не является решением enterprise-ready.

Предварительные требования

Ниже приведен список предварительных требований, необходимых для сборки этого подключаемого модуля:

Установлен и настроен AD FS 2019
платформа .NET Framework 4.7 и более поздних версий
Visual Studio

Сборка dll подключаемого модуля

Следующая процедура поможет вам создать пример библиотеки dll подключаемых модулей:

Скачайте пример подключаемого модуля, используйте Git Bash и введите следующее:
```
git clone https://github.com/Microsoft/adfs-sample-RiskAssessmentModel-RiskyIPBlock
```
Создайте файл .csv в любом расположении на сервере AD FS (в моем случае я создал файл authconfigdb.csv в C:\extensions) и добавьте IP-адреса, которые нужно заблокировать в этот файл.

Пример подключаемого модуля блокирует все запросы проверки подлинности, поступающие из IP-адресов экстрасети, перечисленных в этом файле.

Примечание.

Если у вас есть ферма AD FS, вы можете создать файл на любом или всех серверах AD FS. Любой из файлов можно использовать для импорта рискованных IP-адресов в AD FS. Мы подробно рассмотрим процесс импорта в разделе "Регистрация библиотеки dll подключаемых модулей" в разделе AD FS ниже.
Откройте проект ThreatDetectionModule.sln с помощью Visual Studio.
Microsoft.IdentityServer.dll Удалите из Обозреватель решений, как показано ниже:
Добавьте ссылку на Microsoft.IdentityServer.dll AD FS, как показано ниже:

a. Щелкните правой кнопкой мыши ссылки в решениях Обозреватель и выберите "Добавить ссылку...".

b. В окне диспетчера ссылок нажмите кнопку "Обзор". В диалоговом окне "Выбор файлов для ссылки... диалоговое окно" выберите Microsoft.IdentityServer.dll из папки установки AD FS (в моем случае C:\Windows\ADFS) и нажмите кнопку "Добавить".

Примечание.

В моем случае я создаю подключаемый модуль на самом сервере AD FS. Если среда разработки находится на другом сервере, скопируйте Microsoft.IdentityServer.dll ее из папки установки AD FS на сервере AD FS в поле разработки.

c. Нажмите кнопку "ОК" в окне диспетчера ссылок после выбора Microsoft.IdentityServer.dll поля проверка.
Все классы и ссылки теперь выполняют сборку. Тем не менее, так как выходные данные этого проекта являются библиотекой DLL, ее необходимо установить в глобальный кэш сборок или GAC сервера AD FS, а библиотека DLL должна быть подписана сначала. Это можно сделать следующим образом.

a. Щелкните правой кнопкой мыши имя проекта ThreatDetectionModule. В меню выберите пункт "Свойства".

b. На странице "Свойства" нажмите кнопку "Подписывание" слева, а затем проверка поле проверка помечено как подпись сборки. В файле< ключа строгого имени выберите меню "Создать...>".

c. В диалоговом окне "Создание ключа строгого имени" введите имя (можно выбрать любое имя) для ключа, un проверка поле проверка "Защита файла ключа с помощью пароля". Затем нажмите кнопку "ОК".

d. Сохраните проект, как показано ниже:
Создайте проект, нажав кнопку "Сборка", а затем перестроите решение, как показано ниже:

Проверьте окно вывода в нижней части экрана, чтобы узнать, произошла ли ошибка.

Подключаемый модуль (dll) теперь готов к использованию и находится в папке \bin\Debug папки проекта (в моем случае это C:\extensions\ThreatDetectionModule\bin\Debug\ThreatDetectionModule.dll).

Следующим шагом является регистрация библиотеки DLL в AD FS, поэтому она выполняется в соответствии с процессом проверки подлинности AD FS.

Регистрация библиотеки dll подключаемого модуля с помощью AD FS

Необходимо зарегистрировать библиотеку dll в AD FS с помощью Register-AdfsThreatDetectionModule команды PowerShell на сервере AD FS. Однако перед регистрацией необходимо получить маркер открытого ключа. Этот маркер открытого ключа был создан при создании ключа и подписан библиотеке dll с помощью этого ключа. Чтобы узнать, что такое токен открытого ключа для библиотеки DLL, можно использовать SN.exe следующим образом:

Скопируйте dll-файл из папки \bin\Debug в другое расположение (в моем случае скопируйте его в C:\extensions).
Запустите командную строку разработчика для Visual Studio и перейдите в каталог, содержащий sn.exe (в моем случае каталог C:\Program Files (x86)\Microsoft SDK\Windows\v10.0A\bin\NETFX 4.7.2 Tools.
Выполните команду SN с параметром -T и расположением файла (в моем случаеSN -T "C:\extensions\ThreatDetectionModule.dll").

Команда предоставит маркер открытого ключа (для меня маркер открытого ключа — 714697626ef96b35)
Добавьте библиотеку dll в глобальный кэш сборок сервера AD FS, мы рекомендуем создать соответствующий установщик для проекта и использовать установщик для добавления файла в GAC. Другим решением является использование Gacutil.exe (дополнительные сведения о Gacutil.exe доступных здесь) на компьютере разработки. Так как у меня есть visual studio на том же сервере, что и AD FS, я буду использовать Gacutil.exe следующим образом:

a. В командной строке разработчика для Visual Studio перейдите в каталог, содержащий Gacutil.exe (в моем случае каталог C :\Program Files (x86)\Microsoft SDK\Windows\v10.0A\bin\NETFX 4.7.2 Tools.

b. Выполните команду Gacutil (в моем случаеGacutil /IF C:\extensions\ThreatDetectionModule.dll):

Примечание.

Если у вас есть ферма AD FS, на каждом сервере AD FS в ферме необходимо выполнить указанные выше действия.

Откройте Windows PowerShell и выполните следующую команду, чтобы зарегистрировать библиотеку dll:

Register-AdfsThreatDetectionModule -Name "<Add a name>" -TypeName "<class name that implements interface>, <dll name>, Version=10.0.0.0, Culture=neutral, PublicKeyToken=< Add the Public Key Token from Step 2. above>" -ConfigurationFilePath "<path of the .csv file>"

В моем случае команда:

Register-AdfsThreatDetectionModule -Name "IPBlockPlugin" -TypeName "ThreatDetectionModule.UserRiskAnalyzer, ThreatDetectionModule, Version=10.0.0.0, Culture=neutral, PublicKeyToken=714697626ef96b35" -ConfigurationFilePath "C:\extensions\authconfigdb.csv"

Примечание.

Необходимо зарегистрировать библиотеку DLL только один раз, даже если у вас есть ферма AD FS.

Перезапустите службу AD FS после регистрации библиотеки DLL.

Это так, библиотека dll теперь зарегистрирована в AD FS и готова к использованию!

Примечание.

Если какие-либо изменения вносятся в подключаемый модуль и проект перестроен, необходимо снова зарегистрировать обновленную библиотеку DLL. Перед регистрацией необходимо отменить регистрацию текущей библиотеки DLL с помощью следующей команды:

UnRegister-AdfsThreatDetectionModule -Name "<name used while registering the dll in 5. above>"

В моем случае команда:

UnRegister-AdfsThreatDetectionModule -Name "IPBlockPlugin"

Тестирование подключаемого модуля

Откройте файл authconfig.csv, который мы создали ранее (в моем случае в расположении C:\extensions) и добавьте IP-адреса экстрасети, которые нужно заблокировать. Каждый IP-адрес должен находиться в отдельной строке, и в конце не должно быть пробелов.
Сохранить и закрыть файл.

Импортируйте обновленный файл в AD FS, выполнив следующую команду PowerShell:

Import-AdfsThreatDetectionModuleConfiguration -name "<name given while registering the dll>" -ConfigurationFilePath "<path of the .csv file>"

В моем случае команда:

Import-AdfsThreatDetectionModuleConfiguration -name "IPBlockPlugin" -ConfigurationFilePath "C:\extensions\authconfigdb.csv")

Инициируйте запрос проверки подлинности с сервера с тем же IP-адресом, который вы добавили в authconfig.csv.

Для этой демонстрации я буду использовать средство ad FS Help Claims X-Ray для запуска запроса. Если вы хотите использовать средство X-Ray, следуйте инструкциям.

Введите экземпляр сервера федерации и нажмите кнопку "Проверка подлинности ".
Проверка подлинности заблокирована, как показано ниже.

Теперь, когда мы знаем, как создать и зарегистрировать подключаемый модуль, давайте рассмотрим код подключаемого модуля, чтобы понять реализацию с помощью новых интерфейсов и классов, представленных с моделью.

Пошаговое руководство по коду подключаемого модуля

Откройте проект ThreatDetectionModule.sln с помощью Visual Studio и откройте основной файл UserRiskAnalyzer.cs из Обозреватель решений справа от экрана

model

Файл содержит основной класс UserRiskAnalyzer, реализующий абстрактный класс ThreatDetectionModule и интерфейс IRequestReceivedThreatDetectionModule , чтобы считывать IP-адрес из контекста запроса, сравнить полученный IP-адрес с IP-адресами, загруженными из AD FS DB, и блокировать запрос, если имеется соответствие IP-адресов. Давайте рассмотрим эти типы более подробно

Абстрактный класс ThreatDetectionModule

Этот абстрактный класс загружает подключаемый модуль в конвейер AD FS, что позволяет запускать подключаемый модуль в соответствии с процессом AD FS.

public abstract class ThreatDetectionModule
{
    protected ThreatDetectionModule();

    public abstract string VendorName { get; }
    public abstract string ModuleIdentifier { get; }

    public abstract void OnAuthenticationPipelineLoad(ThreatDetectionLogger logger, ThreatDetectionModuleConfiguration configData);
    public abstract void OnAuthenticationPipelineUnload(ThreatDetectionLogger logger);
    public abstract void OnConfigurationUpdate(ThreatDetectionLogger logger, ThreatDetectionModuleConfiguration configData);
}

Класс включает следующие методы и свойства:

Способ	Тип	Определение
OnAuthenticationPipelineLoad	Void	Вызывается AD FS при загрузке подключаемого модуля в конвейер
OnAuthenticationPipelineUnload	Void	Вызывается AD FS при выгрузке подключаемого модуля из конвейера
OnConfigurationUpdate	Void	Вызывается AD FS при обновлении конфигурации
Свойство	Тип	Определение
VendorName	Строка	Возвращает имя поставщика, хладеющего подключаемым модулем
ModuleIdentifier	Строка	Возвращает идентификатор подключаемого модуля

В нашем примере подключаемого модуля мы используем методы OnAuthenticationPipelineLoad и OnConfigurationUpdate для чтения предварительно определенных IP-адресов из AD FS DB. OnAuthenticationPipelineLoad вызывается при регистрации подключаемого модуля в AD FS, а onConfigurationUpdate вызывается при импорте .csv с помощью командлета Import-AdfsThreatDetectionModuleConfiguration .

Интерфейс IRequestReceivedThreatDetectionModule

Этот интерфейс позволяет реализовать оценку риска в точке, когда AD FS получает запрос проверки подлинности, но перед вводом учетных данных пользователем на этапе получения запроса проверки подлинности.

public interface IRequestReceivedThreatDetectionModule
{
    Task<ThrottleStatus> EvaluateRequest (
    ThreatDetectionLogger logger,
    RequestContext requestContext );
}

Интерфейс включает метод EvaluateRequest , который позволяет использовать контекст запроса проверки подлинности, переданного в параметре ввода requestContext, для записи логики оценки рисков. Параметр requestContext имеет тип RequestContext.

Другой переданный входной параметр — средство ведения журнала, которое является типом ThreatDetectionLogger. Этот параметр можно использовать для записи сообщений об ошибке, аудите и/или отладке в журналы AD FS.

Метод возвращает ThrottleStatus (0, если NotEvaluated, 1 to Block и 2 to Allow) в AD FS, который затем блокирует или разрешает запрос.

В нашем примере подключаемого модуля реализация метода EvaluateRequest анализирует clientIpAddress из параметра requestContext и сравнивает его со всеми IP-адресами, загруженными из базы данных AD FS. Если совпадение найдено, метод возвращает значение 2 для block, в противном случае возвращается значение 1 для allow. В зависимости от возвращаемого значения AD FS либо блокирует, либо разрешает запрос.

Примечание.

Пример подключаемого модуля, описанного выше, реализует только интерфейс IRequestReceivedThreatDetectionModule. Однако модель оценки рисков предоставляет два дополнительных интерфейса — IPreAuthenticationThreatDetectionModule (для реализации логики оценки рисков для этапа предварительной проверки подлинности) и IPostAuthenticationThreatDetectionModule (для реализации логики оценки рисков во время этапа после проверки подлинности). Ниже приведены сведения о двух интерфейсах.

Интерфейс IPreAuthenticationThreatDetectionModule

Этот интерфейс позволяет реализовать логику оценки рисков в точке, когда пользователь предоставляет учетные данные, но прежде чем AD FS оценивает их, т. е. этап предварительной проверки подлинности.

public interface IPreAuthenticationThreatDetectionModule
{
    Task<ThrottleStatus> EvaluatePreAuthentication (
    ThreatDetectionLogger logger,
    RequestContext requestContext,
    SecurityContext securityContext,
    ProtocolContext protocolContext,
    IList<Claim> additionalClams
  );
}

Интерфейс включает метод EvaluatePreAuthentication, который позволяет использовать данные, передаваемые в запросе RequestContextContext, SecurityContext securityContext, ProtocolContext protocolContext и IList<Claim> additionalClams input parameters для записи логики оценки рисков предварительной проверки подлинности.

Примечание.

Список свойств, передаваемых с каждым типом контекста, см. в определениях классов RequestContext, SecurityContext и ProtocolContext.

Метод возвращает ThrottleStatus (0, если NotEvaluated, 1 to Block и 2 to Allow) в AD FS, который затем блокирует или разрешает запрос.

Интерфейс IPostAuthenticationThreatDetectionModule

Этот интерфейс позволяет реализовать логику оценки рисков после того, как пользователь предоставил учетные данные и AD FS выполнил проверку подлинности, т. е. этап после проверки подлинности.

public interface IPostAuthenticationThreatDetectionModule
{
    Task<RiskScore> EvaluatePostAuthentication (
    ThreatDetectionLogger logger,
    RequestContext requestContext,
    SecurityContext securityContext,
    ProtocolContext protocolContext,
    AuthenticationResult authenticationResult,
    IList<Claim> additionalClams
  );
}

Интерфейс включает метод EvaluatePostAuthentication, который позволяет использовать данные, передаваемые в запросе RequestContextContext, SecurityContext securityContext, ProtocolContext protocolContext и IList<Claim> additionalClams input parameters для записи логики оценки рисков после проверки подлинности.

Примечание.

Полный список свойств, передаваемых с каждым типом контекста, см. в определениях классов RequestContext, SecurityContext и ProtocolContext.

Метод возвращает оценку риска, которую можно использовать в политике AD FS и правилах утверждений.

Примечание.

Для работы подключаемого модуля основной класс (в данном случае UserRiskAnalyzer) должен получить абстрактный класс ThreatDetectionModule и должен реализовать по крайней мере один из трех интерфейсов, описанных выше. После регистрации библиотеки DLL AD FS проверка, какие интерфейсы реализуются и вызывают их на соответствующем этапе в конвейере.

Вопросы и ответы

Зачем создавать эти подключаемые модули?
Ответ. Эти подключаемые модули не только предоставляют дополнительные возможности для защиты среды от атак, таких как атаки с распылением паролей, но и обеспечивают гибкость для создания собственной логики оценки рисков на основе ваших требований.

Где записываются журналы?
Ответ. Журналы ошибок можно записывать в журнал событий AD FS/Администратор с помощью метода записи Администратор LogErrorMessage, журналов аудита в журнал безопасности AD FS с помощью метода WriteAuditMessage и отладки журналов отладки в журнал отладки AD FS с помощью метода WriteDebugMessage.

Можно ли добавить эти подключаемые модули, чтобы увеличить задержку процесса проверки подлинности AD FS?
Ответ. Влияние задержки определяется временем выполнения логики оценки рисков, которую вы реализуете. Мы рекомендуем оценить влияние задержки перед развертыванием подключаемой среды в рабочей среде.

Почему AD FS не может предложить список рискованных IP-адресов, пользователей и т. д.?
Ответ. Хотя в настоящее время нет, мы работаем над созданием аналитики, чтобы предложить рискованные IP-адреса, пользователи и т. д. в подключаемой модели оценки рисков. Мы будем делиться датами запуска в ближайшее время.

Какие другие примеры подключаемых модулей доступны?
Ответ. Доступны следующие примеры подключаемых модулей:

Имя	Описание
Небезопасный подключаемый модуль пользователя	Пример подключаемого модуля, который блокирует проверку подлинности или применяет MFA на основе уровня риска пользователя, определенного Защита идентификации Microsoft Entra.

Создание подключаемых модулей с помощью модели оценки риска AD FS за 2019 г.

Что такое модель оценки рисков?

Создание примера подключаемого модуля

Предварительные требования

Сборка dll подключаемого модуля

Регистрация библиотеки dll подключаемого модуля с помощью AD FS

Тестирование подключаемого модуля

Пошаговое руководство по коду подключаемого модуля

Абстрактный класс ThreatDetectionModule

Интерфейс IRequestReceivedThreatDetectionModule

Интерфейс IPreAuthenticationThreatDetectionModule

Интерфейс IPostAuthenticationThreatDetectionModule

Вопросы и ответы

Дополнительные ресурсы