Использование API Microsoft Defender для конечной точки

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

• Microsoft Defender для конечной точки (план 1)
• Microsoft Defender для конечной точки (план 2)
• Microsoft Defender для бизнеса

Хотите попробовать Microsoft Defender для конечной точки? Зарегистрироваться для бесплатной пробной версии.

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

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

Если вы не знаете, какой доступ вам нужен, прочитайте страницу Введение.

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

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

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

На этой странице объясняется, как создать приложение Microsoft Entra, получить маркер доступа к Microsoft Defender для конечной точки и проверить маркер.

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

1. Войдите на портал Azure.

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

   

3. После появления страницы Регистрация приложения введите сведения о регистрации приложения:

   • Имя — введите понятное имя приложения, которое отображается для пользователей приложения.

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

     
     

     Поддерживаемые типы учетных записей	Описание
     Учетные записи только в этом каталоге организации	Этот вариант подходит для создания бизнес-приложений. Этот параметр недоступен, если вы не регистрируете приложение в каталоге. Этот параметр сопоставляется с одним клиентом Microsoft Entra. Этот параметр используется по умолчанию, если вы не регистрируете приложение за пределами каталога. В случаях, когда приложение зарегистрировано вне каталога, по умолчанию используется мультитенантная и личная учетная запись Майкрософт Microsoft Entra.
     Учетные записи в любом каталоге организации	Выберите этот параметр, если вы хотите выбрать в качестве целевой аудитории предприятия и учебные заведения. Этот параметр сопоставляется с мультитенантом только Microsoft Entra. Если вы зарегистрировали приложение как однотенантное приложение Microsoft Entra, вы можете обновить его до мультитенантного приложения Microsoft Entra и вернуться к одному клиенту с помощью колонки Проверка подлинности .
     Учетные записи в любом каталоге организации и личные учетные записи Майкрософт	Выберите этот параметр для широкого круга пользователей. Этот параметр сопоставляется с мультитенантными и личными учетными записями Майкрософт в Microsoft Entra. Если вы зарегистрировали приложение как мультитенантную и личную учетную запись Майкрософт, вы не сможете изменить это в пользовательском интерфейсе. Вместо этого необходимо использовать редактор манифеста приложения для изменения типов поддерживаемых учетных записей.

   • URI перенаправления (необязательно) — выберите тип приложения, которое вы создаете — Веб или Общедоступный клиент (мобильный и классический), а затем введите универсальный код ресурса (URI) перенаправления (или URL-адрес ответа) приложения.

     • Для веб-приложений укажите основной URL-адрес приложения. Например, http://localhost:31544 может быть URL-адресом веб-приложения, выполняемого на локальном компьютере. Пользователи будут использовать этот URL-адрес для входа в приложение веб-клиента.

     • Для общедоступных клиентских приложений укажите универсальный код ресурса (URI), используемый идентификатором Microsoft Entra для возврата ответов маркера. Укажите значение, специфичное для вашего приложения, например myapp://auth.

     Конкретные примеры для веб-приложений или собственных приложений см. в наших кратких руководствах.

     По завершении щелкните Зарегистрировать.

4. Разрешите приложению доступ к Microsoft Defender для конечной точки и назначьте ему разрешение "Чтение оповещений":

   • На странице приложения выберите Разрешения> APIДобавить API разрешений>API, которые моя организация использует>, введите WindowsDefenderATP и выберите WindowsDefenderATP.

     Примечание.

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

     

   • Выберите Пункт Оповещения о делегированных разрешениях.Чтение>> выберите Добавить разрешения.

     

   Важно!

   Выберите соответствующие разрешения. Примером является только чтение оповещений.

   Например:

   • Чтобы выполнить расширенные запросы, выберите Разрешение На выполнение расширенных запросов .

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

   • Чтобы определить, какое разрешение вам нужно, просмотрите раздел Разрешения в API, который требуется вызвать.

   • Выберите Предоставить согласие.

     Примечание.

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

     

5. Запишите идентификатор приложения и идентификатор клиента.

   На странице приложения перейдите в раздел Обзор и скопируйте следующие сведения:

   

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

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

Использование C#

• Скопируйте или вставьте приведенный ниже класс в приложение.

• Используйте метод AcquireUserTokenAsync с идентификатором приложения, идентификатором клиента, именем пользователя и паролем, чтобы получить маркер.

  namespace WindowsDefenderATP
  {
      using System.Net.Http;
      using System.Text;
      using System.Threading.Tasks;
      using Newtonsoft.Json.Linq;
  
      public static class WindowsDefenderATPUtils
      {
          private const string Authority = "https://login.microsoftonline.com";
  
          private const string WdatpResourceId = "https://api.securitycenter.microsoft.com";
  
          public static async Task<string> AcquireUserTokenAsync(string username, string password, string appId, string tenantId)
          {
              using (var httpClient = new HttpClient())
              {
                  var urlEncodedBody = $"resource={WdatpResourceId}&client_id={appId}&grant_type=password&username={username}&password={password}";
  
                  var stringContent = new StringContent(urlEncodedBody, Encoding.UTF8, "application/x-www-form-urlencoded");
  
                  using (var response = await httpClient.PostAsync($"{Authority}/{tenantId}/oauth2/token", stringContent).ConfigureAwait(false))
                  {
                      response.EnsureSuccessStatusCode();
  
                      var json = await response.Content.ReadAsStringAsync().ConfigureAwait(false);
  
                      var jObject = JObject.Parse(json);
  
                      return jObject["access_token"].Value<string>();
                  }
              }
          }
      }
  }
  

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

Убедитесь, что вы получили правильный маркер:

• Скопируйте или вставьте в JWT маркер, полученный на предыдущем шаге, чтобы декодировать его.

• Проверьте получение утверждения "scp" с требуемыми разрешениями приложения.

• На снимке экрана ниже вы можете увидеть декодированные маркеры, полученные из приложения в этом руководстве:

  

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

• Выберите API, который вы хотите использовать. Поддерживаемые API Microsoft Defender для конечной точки.

• Задайте заголовок Authorization в HTTP-запросе, отправляемом по адресу Bearer {token}( Bearer — это схема авторизации).

• Срок действия маркера составляет 1 час (можно отправить несколько запросов с одним и тем же маркером).

• Пример отправки запроса на получение списка оповещений с помощью C#:

  var httpClient = new HttpClient();
  
  var request = new HttpRequestMessage(HttpMethod.Get, "https://api.securitycenter.microsoft.com/api/alerts");
  
  request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
  
  var response = httpClient.SendAsync(request).GetAwaiter().GetResult();
  
  // Do something useful with the response
  

См. также

• API Microsoft Defender для конечной точки
• Доступ к Microsoft Defender для конечной точки с помощью контекста приложения