Создание приложения для доступа к MICROSOFT DEFENDER XDR API от имени пользователя

Создайте приложение, чтобы получить программный доступ к Microsoft Defender от имени одного пользователя.

Если вам нужен программный доступ к Microsoft Defender без определенного пользователя (например, если вы пишете фоновое приложение или управляющая программа), см. статью "Создание приложения для доступа к Microsoft Defender без пользователя". Если вам нужно предоставить доступ для нескольких клиентов, например, если вы обслуживаете большую организацию или группу клиентов, см. статью "Создание приложения с партнерским доступом к Microsoft Defender API". Если вы не знаете, какой тип доступа вам нужен, см. статью Начало работы.

Microsoft Defender предоставляет большую часть своих данных и действий с помощью набора программных API. Эти API помогают автоматизировать рабочие процессы и использовать возможности Microsoft Defender. Для доступа к API требуется проверка подлинности OAuth2.0. Дополнительные сведения см. в разделе Поток кода авторизации OAuth 2.0.

Как правило, для использования этих API необходимо выполнить следующие действия:

• Создайте приложение Microsoft Entra.
• Получите маркер доступа с помощью этого приложения.
• Используйте маркер для доступа к API Microsoft Defender.

В этой статье объясняется, как:

• Создание приложения Microsoft Entra
• Получение маркера доступа для Microsoft Defender
• Проверка маркера

Создать приложение

1. Войдите в Azure.

2. Перейдите в раздел Microsoft Entra ID>Регистрация приложений>Новая регистрация.

   

3. В форме выберите имя приложения и введите следующие сведения для URI перенаправления, а затем выберите Зарегистрировать.

   

   • Тип приложения: Общедоступный клиент
   • URI перенаправления:https://portal.azure.com

4. На странице приложения выберите Разрешения> APIДобавить разрешения>API, которые использует> моя организация, введите Microsoft Threat Protection и выберите Microsoft Threat Protection. Теперь приложение может получить доступ к Microsoft Defender XDR.

   Совет

   Microsoft Threat Protection — это прежнее имя Microsoft Defender XDR и не будет отображаться в исходном списке. Чтобы оно появилось, необходимо написать его имя в текстовом поле.

   

   • Выберите Делегированные разрешения. Выберите соответствующие разрешения для вашего сценария (например , Incident.Read), а затем выберите Добавить разрешения.

     

   Примечание.

   Необходимо выбрать соответствующие разрешения для вашего сценария. Чтение всех инцидентов — это просто пример. Чтобы определить, какое разрешение вам нужно, ознакомьтесь с разделом Разрешения в API, который требуется вызвать.

   Например, чтобы выполнить расширенные запросы, выберите разрешение "Выполнение расширенных запросов". Чтобы изолировать устройство, выберите разрешение "Изолировать компьютер".

5. Выберите Предоставить согласие администратора. Каждый раз при добавлении разрешения необходимо выбрать Предоставить согласие администратора , чтобы оно войти в силу.

   

6. Запишите идентификатор приложения и идентификатор клиента в безопасном месте. Они перечислены в разделе Обзор на странице приложения.

   

Получение токена доступа

Дополнительные сведения о маркерах Microsoft Entra см. в руководстве по Microsoft Entra.

Получение маркера доступа от имени пользователя с помощью PowerShell

Используйте библиотеку MSAL.PS для получения маркеров доступа с делегированными разрешениями. Выполните следующие команды, чтобы получить маркер доступа от имени пользователя:

Install-Module -Name MSAL.PS # Install the MSAL.PS module from PowerShell Gallery

$TenantId = " " # Paste your directory (tenant) ID here.
$AppClientId="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" # Paste your application (client) ID here.

$MsalParams = @{
   ClientId = $AppClientId
   TenantId = $TenantId
   Scopes   = 'https://graph.microsoft.com/User.Read.All','https://graph.microsoft.com/Files.ReadWrite','https://api.securitycenter.windows.com/AdvancedQuery.Read'
}

$MsalResponse = Get-MsalToken @MsalParams
$AccessToken  = $MsalResponse.AccessToken
 
$AccessToken # Display the token in PS console

Проверка маркера

1. Скопируйте и вставьте маркер в JWT , чтобы декодировать его.
2. Убедитесь, что утверждение ролей в декодированном маркере содержит необходимые разрешения.

На следующем рисунке показан декодированные маркеры, полученные из приложения с Incidents.Read.Allразрешениями , Incidents.ReadWrite.Allи AdvancedHunting.Read.All :

Использование маркера для доступа к API Microsoft Defender

1. Выберите API, который вы хотите использовать (инциденты или расширенная охота). Дополнительные сведения см. в разделе "Поддерживаемые Microsoft Defender API".
2. В http-запросе, который вы хотите отправить, задайте для заголовка авторизации значение "Bearer" <token>, bearer — это схема авторизации, а маркер — это проверенный маркер.
3. Срок действия маркера истекает в течение одного часа. За это время можно отправить несколько запросов с одним и тем же маркером.

В следующем примере показано, как отправить запрос на получение списка инцидентов с помощью C#.

    var httpClient = new HttpClient();
    var request = new HttpRequestMessage(HttpMethod.Get, "https://api.security.microsoft.com/api/incidents");

    request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);

    var response = httpClient.SendAsync(request).GetAwaiter().GetResult();

Статьи по теме

• Обзор API Microsoft Defender
• Доступ к API Microsoft Defender
• Создание приложения Hello world
• Создание приложения для доступа к Microsoft Defender XDR без пользователя
• Создание приложения с мультитенантным доступом партнеров к API Microsoft Defender XDR
• Сведения об ограничениях API и лицензировании
• Общие сведения о кодах ошибок
• Авторизация OAuth 2.0 для входа пользователей и доступа к API