Поделиться через

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

  • Статья

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

  • Microsoft Defender XDR

Важно!

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

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

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

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

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

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

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

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

Примечание.

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

Совет

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

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

  1. Войдите в Azure как пользователь с ролью глобального администратора .

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

    Параметр

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

    Область регистрации приложений на портале Azure

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

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

    Совет

    Защита от угроз (Майкрософт ) — это прежнее имя XDR в Microsoft Defender и не будет отображаться в исходном списке. Чтобы оно появилось, необходимо написать его имя в текстовом поле.

    Панель API вашей организации на портале Microsoft Defender

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

      Область Делегированные разрешения на портале Microsoft Defender

    Примечание.

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

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

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

    Область предоставления согласия администратора на портале Microsoft Defender

  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 :

Раздел разрешений в области Декодированные маркеры на портале Microsoft Defender

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

  1. Выберите API, который вы хотите использовать (инциденты или расширенная охота). Дополнительные сведения см. в разделе Поддерживаемые API XDR в Microsoft Defender.
  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();

Совет

Хотите узнать больше? Обратитесь к сообществу Майкрософт по безопасности в техническом сообществе Microsoft Defender XDR Tech Community.