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

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

  • Статья

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

  • 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. Дополнительные сведения о ролях и разрешениях см. в статье Управление доступом к Microsoft Defender XDR с помощью Microsoft Entra глобальных ролей.

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

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

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

    Параметр Новая регистрация в области Управление в портал Azure

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

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

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

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

    Совет

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

    Панель 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 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();

Совет

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