Использование API 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 мультитенантными и личными учетными записями Майкрософт. Если вы зарегистрировали приложение как Microsoft Entra мультитенантных и личных учетных записей Майкрософт, изменить это в пользовательском интерфейсе невозможно. Вместо этого необходимо использовать редактор манифеста приложения для изменения типов поддерживаемых учетных записей.

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

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

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

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

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

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

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

     Примечание.

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

     

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

     

   Важно!

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

   Например, вы можете:

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

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

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

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

     Примечание.

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

     

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

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

   

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

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

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

В этом примере используется Microsoft Authentication Library (MSAL) для интерактивного получения токена. Перед тем как запускать:

• Добавьте в проект пакет NuGet Microsoft.Identity.Client.
• При регистрации приложения настройте мобильную и десктопную платформу с http://localhost URI перенаправления, чтобы интерактивный поток мог вернуть токен.
• Скопируйте/вставьте следующий класс в своё приложение, затем вызовите AcquireUserTokenAsync с вашим идентификатором приложения и идентификатором арендатора. Пользователю предлагается войти в систему интерактивно; Их пароль никогда не обрабатывается вашим приложением.

    namespace WindowsDefenderATP
    {
        using System.Linq;
        using System.Threading.Tasks;
        using Microsoft.Identity.Client;

        public static class WindowsDefenderATPUtils
        {
            private const string Authority = "https://login.microsoftonline.com";

            // Microsoft Defender for Endpoint APIs expect tokens issued for this resource.
            private static readonly string[] Scopes = { "https://api.securitycenter.microsoft.com/.default" };

            public static async Task<string> AcquireUserTokenAsync(string appId, string tenantId)
            {
                // Public client application for a native (desktop) app.
                // No client secret or user password is stored or handled by the app.
                var app = PublicClientApplicationBuilder
                    .Create(appId)
                    .WithAuthority($"{Authority}/{tenantId}")
                    .WithDefaultRedirectUri() // http://localhost - register as a public client redirect URI
                    .Build();

                var account = (await app.GetAccountsAsync().ConfigureAwait(false)).FirstOrDefault();

                try
                {
                    // Reuse a cached token when one is available.
                    var silentResult = await app
                        .AcquireTokenSilent(Scopes, account)
                        .ExecuteAsync()
                        .ConfigureAwait(false);

                    return silentResult.AccessToken;
                }
                catch (MsalUiRequiredException)
                {
                    // First run or expired session: prompt the user to sign in.
                    // Uses the authorization code flow with PKCE and supports
                    // multifactor authentication and Conditional Access.
                    var interactiveResult = await app
                        .AcquireTokenInteractive(Scopes)
                        .ExecuteAsync()
                        .ConfigureAwait(false);

                    return interactiveResult.AccessToken;
                }
            }
        }
    }

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

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

• Скопируйте или вставьте в 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.security.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 для конечной точки с помощью контекста приложения