Создание приложения для доступа к Microsoft Defender для конечной точки без пользователя

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

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

Важно!

Расширенные возможности охоты не включены в Defender для бизнеса.

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

Примечание.

Если вы являетесь клиентом для государственных организаций США, используйте URI, перечисленные в Microsoft Defender для конечной точки для клиентов государственных организаций США.

Совет

Для повышения производительности можно использовать сервер ближе к географическому расположению:

• us.api.security.microsoft.com
• eu.api.security.microsoft.com
• uk.api.security.microsoft.com
• au.api.security.microsoft.com
• swa.api.security.microsoft.com
• ina.api.security.microsoft.com

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

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

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

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

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

Важно!

Microsoft рекомендует использовать роли с наименьшим количеством разрешений. Это помогает повысить безопасность вашей организации. Глобальный администратор — это роль с высокими привилегиями, которую следует ограничивать экстренными сценариями, когда вы не можете использовать существующую роль.

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

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

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

   

3. В форме регистрации выберите имя приложения и нажмите кнопку Зарегистрировать.

4. Чтобы разрешить приложению доступ к Defender для конечной точки и назначить ему разрешение "Чтение всех оповещений", на странице приложения выберите Разрешения> APIДобавить разрешения>API, которые использует> моя организация, введите WindowsDefenderATP, а затем выберите WindowsDefenderATP.

   Примечание.

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

   

   Выберите Разрешения> приложенияAlert.Read.All, а затем — Добавить разрешения.

   

5. Выберите соответствующие разрешения. Read All Alerts является только примером. Ниже приводятся примеры:

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

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

   Примечание.

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

   

7. Чтобы добавить секрет в приложение, выберите Сертификаты & секреты, добавьте описание в секрет, а затем нажмите кнопку Добавить.

   Примечание.

   После нажатия кнопки Добавить выберите скопировать созданное значение секрета. Вы не сможете получить это значение после ухода.

   

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

   

9. Только для Партнеров в Microsoft Defender для конечных точек. Задайте для приложения мультитенантное (доступно во всех клиентах после согласия). Это необходимо для сторонних приложений (например, если вы создаете приложение, которое предназначено для запуска в клиенте нескольких клиентов). Это не обязательно, если вы создаете службу, которую хотите запустить только в клиенте (например, если вы создаете приложение для собственного использования, которое будет взаимодействовать только с вашими данными). Чтобы настроить мультитенантное приложение, выполните следующие действия.

   1. Перейдите в раздел Проверка подлинности и добавьте https://portal.azure.com в качестве URI перенаправления.

   2. В нижней части страницы в разделе Поддерживаемые типы учетных записей выберите согласие приложения "Учетные записи в любом каталоге организации " для мультитенантного приложения.

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

      Вам (или вашему клиенту, если вы пишете стороннее приложение) необходимо выбрать ссылку согласия и утвердить приложение. Согласие должно быть сделано с пользователем, который имеет права администратора в Active Directory.

      Ссылка на согласие формируется следующим образом:

      https://login.microsoftonline.com/common/oauth2/authorize?prompt=consent&client_id=00000000-0000-0000-0000-000000000000&response_type=code&sso_reload=true
      

      Где 00000000-0000-0000-0000-000000000000 заменяется идентификатором приложения.

Готово! Вы успешно зарегистрировали приложение! Ниже приведены примеры получения и проверки маркеров.

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

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

Воспользуйтесь PowerShell

# This script acquires the App Context Token and stores it in the variable $token for later use in the script.
# Paste your Tenant ID, App ID, and App Secret (App key) into the indicated quotes below.

$tenantId = '' ### Paste your tenant ID here
$appId = '' ### Paste your Application ID here
$appSecret = '' ### Paste your Application key here

$sourceAppIdUri = 'https://api.securitycenter.microsoft.com/.default'
$oAuthUri = "https://login.microsoftonline.com/$TenantId/oauth2/v2.0/token"
$authBody = [Ordered] @{
    scope = "$sourceAppIdUri"
    client_id = "$appId"
    client_secret = "$appSecret"
    grant_type = 'client_credentials'
}
$authResponse = Invoke-RestMethod -Method Post -Uri $oAuthUri -Body $authBody -ErrorAction Stop
$token = $authResponse.access_token
$token

Используйте C#:

Следующий код был протестирован с помощью NuGet Microsoft.Identity.Client 3.19.8.

Важно!

Пакет NuGet Microsoft.IdentityModel.Clients.ActiveDirectory и библиотека проверки подлинности Azure AD (ADAL) устарели. С 30 июня 2020 г. новые функции не добавлены. Мы настоятельно рекомендуем выполнить обновление. Дополнительные сведения см. в руководстве по миграции .

1. Создайте консольное приложение.

2. Установите NuGet Microsoft.Identity.Client.

3. Добавьте следующий код:

   using Microsoft.Identity.Client;
   

4. Скопируйте и вставьте следующий код в приложение (не забудьте обновить три переменные: tenantId, appId, appSecret):

   string tenantId = "00000000-0000-0000-0000-000000000000"; // Paste your own tenant ID here
   string appId = "11111111-1111-1111-1111-111111111111"; // Paste your own app ID here
   string appSecret = "22222222-2222-2222-2222-222222222222"; // Paste your own app secret here for a test, and then store it in a safe place! 
   const string authority = "https://login.microsoftonline.com";
   const string audience = "https://api.securitycenter.microsoft.com";
   
   IConfidentialClientApplication myApp = ConfidentialClientApplicationBuilder.Create(appId).WithClientSecret(appSecret).WithAuthority($"{authority}/{tenantId}").Build();
   
   List<string> scopes = new List<string>() { $"{audience}/.default" };
   
   AuthenticationResult authResult = myApp.AcquireTokenForClient(scopes).ExecuteAsync().GetAwaiter().GetResult();
   
   string token = authResult.AccessToken;
   

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

См . раздел Получение маркера с помощью Python.

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

Примечание.

В следующей процедуре предполагается, что Curl для Windows уже установлен на компьютере.

1. Откройте командную строку и задайте CLIENT_ID идентификатор приложения Azure.

2. Задайте CLIENT_SECRET секрет приложения Azure.

3. Задайте TENANT_ID идентификатор клиента Azure, который хочет использовать приложение для доступа к Defender для конечной точки.

4. Выполните следующую команду:

   curl -i -X POST -H "Content-Type:application/x-www-form-urlencoded" -d "grant_type=client_credentials" -d "client_id=%CLIENT_ID%" -d "scope=https://securitycenter.onmicrosoft.com/windowsatpservice/.default" -d "client_secret=%CLIENT_SECRET%" "https://login.microsoftonline.com/%TENANT_ID%/oauth2/v2.0/token" -k
   

   Вы получите ответ, похожий на следующий фрагмент кода:

   {"token_type":"Bearer","expires_in":3599,"ext_expires_in":0,"access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIn <truncated> aWReH7P0s0tjTBX8wGWqJUdDA"}
   

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

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

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

2. Убедитесь, что вы получили утверждение роли с требуемыми разрешениями.

   На следующем рисунке показан декодированные маркеры, полученные из приложения с разрешениями для всех ролей Microsoft Defender для конечной точки:

   

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

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

2. Задайте заголовок авторизации в запросе, в который http вы отправляете Bearer {token} (bearer — это схема авторизации).

3. Срок действия маркера составляет один час. Вы можете отправить несколько запросов с одним и тем же маркером.

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

Совет

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