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

Совет

Хотите узнать больше? Engage с сообществом Microsoft Security в нашем техническом сообществе: Microsoft Defender для конечной точки Техническое сообщество.