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

Примечание.

Хотите испытать Microsoft Defender XDR? Узнайте больше о том, как оценивать и пилотно Microsoft Defender XDR.

Область применения:

• Microsoft Defender XDR

Важно!

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

На этой странице описывается создание приложения для получения программного доступа к Microsoft Defender XDR от имени одного пользователя.

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

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

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

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

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

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

Примечание.

При доступе к API Microsoft Defender XDR от имени пользователя вам потребуются правильные разрешения приложения и разрешения пользователя.

Совет

Если у вас есть разрешение на выполнение действия на портале, у вас есть разрешение на выполнение действия в API.

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

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 XDR

1. Выберите API, который вы хотите использовать (инциденты или расширенная охота). Дополнительные сведения см. в статье Поддерживаемые API Microsoft Defender XDR.
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 XDR
• Доступ к API Microsoft Defender XDR
• Создание приложения "Hello мира"
• Создание приложения для доступа к Microsoft Defender XDR без пользователя
• Создание приложения с мультитенантным доступом партнеров к API Microsoft Defender XDR
• Сведения об ограничениях API и лицензировании
• Общие сведения о кодах ошибок
• Авторизация OAuth 2.0 для входа пользователей и доступа к API

Совет

Хотите узнать больше? Engage с сообществом Microsoft Security в нашем техническом сообществе: Microsoft Defender XDR Техническое сообщество.