Создавайте подключаемые модули, используя модель оценки рисков AD FS 2019

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

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

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

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

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

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

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

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

Примечание.

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

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

Примечание.

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

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

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

• Установлен и настроен AD FS 2019
• .NET Framework 4.7 и выше
• Visual Studio

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

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

1. Скачайте пример подключаемого модуля, используйте Git Bash и введите следующее:

git clone https://github.com/Microsoft/adfs-sample-RiskAssessmentModel-RiskyIPBlock

2. Создайте файл.csv в любом расположении на сервере AD FS (в моем случае я создал файл authconfigdb.csv в C:\extensions) и добавьте IP-адреса, которые нужно заблокировать в этот файл.

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

Примечание.

Если у вас есть ферма AD FS, вы можете создать файл на любом или всех серверах AD FS. Любой из файлов можно использовать для импорта рискованных IP-адресов в AD FS. Подробно рассмотрим процесс импорта в разделе "Регистрация библиотеки подключаемых модулей" в разделе AD FS ниже.

3. Откройте проект ThreatDetectionModule.sln с помощью Visual Studio.

4. Удалите Microsoft.IdentityServer.dll из обозревателя решений, как показано ниже:
   

5. Добавьте ссылку на Microsoft.IdentityServer.dll AD FS, как показано ниже:

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

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

Примечание.

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

с. Нажмите "ОК", убедившись, что в окне Диспетчера ссылокMicrosoft.IdentityServer.dll установлен флажок.

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

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

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

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

д. Сохраните проект, как показано ниже:

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

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

Подключаемый модуль (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 следующим образом:

1. Скопируйте dll-файл из папки \bin\Debug в другое расположение (в моем случае скопируйте его в C:\extensions).

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

3. Выполните команду SN с параметром -T и расположением файла (в моем случае SN -T "C:\extensions\ThreatDetectionModule.dll").

Команда предоставит маркер открытого ключа (для меня маркер открытого ключа — 714697626ef96b35)

4. Добавьте библиотеку 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.

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

Примечание.

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

5. Откройте 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.

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

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

Примечание.

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

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

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

UnRegister-AdfsThreatDetectionModule -Name "IPBlockPlugin"

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

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

2. Сохраните и закройте файл.

3. Импортируйте обновленный файл в 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")

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

Введите инстанцию сервера федерации и нажмите кнопку «Проверка подлинности».

5. Проверка подлинности заблокирована, как показано ниже.
   

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

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

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

Файл содержит основной класс 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	Пустота	Вызывается AD FS при загрузке подключаемого модуля в конвейер
OnAuthenticationPipelineUnload	Пустота	Вызывается AD FS при выгрузке подключаемого модуля из конвейера
OnConfigurationUpdate	Пустота	Вызывается AD FS при обновлении конфигурации
Свойство	Тип	Определение
Имя поставщика	Струна	Возвращает имя поставщика, владеющего подключаемым модулем
ИдентификаторМодуля	Струна	Возвращает идентификатор подключаемого модуля

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

Интерфейс IRequestReceivedThreatDetectionModule

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

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

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

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

Метод возвращает ThrottleStatus (0, если NotEvaluated, 1 для блокировки и 2 для разрешения) в 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, который позволяет использовать данные, передаваемые в RequestContext requestContext, SecurityContext securityContext, ProtocolContext protocolContext и IList<Claim> additionalClams в качестве входных параметров для записи логики оценки рисков предварительной проверки подлинности.

Примечание.

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

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

Метод возвращает ThrottleStatus (0, если NotEvaluated, 1 для блокировки, и 2 для разрешения) в 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, который позволяет использовать данные, передаваемые в запросе RequestContext requestContext, SecurityContext securityContext, ProtocolContext protocolContext и дополнительные параметры IList<Claim> additionalClaims для написания логики оценки рисков после проверки подлинности.

Примечание.

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

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

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

Примечание.

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

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

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

Где записываются журналы?
A: Журналы ошибок можно записывать в журнал событий "AD FS/Admin" с помощью метода WriteAdminLogErrorMessage, журналы аудита — в журнал безопасности "AD FS Auditing" с помощью метода WriteAuditMessage, а журналы отладки — в журнал отладки "AD FS Tracing" с помощью метода WriteDebugMessage.

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

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

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

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