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

Статья
04/27/2024

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

Важно!

Расширенные возможности охоты не включены в 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

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

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

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

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

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

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

Войдите в Azure с помощью пользователя с ролью глобального администратора .
Перейдите в раздел Microsoft Entra ID>Регистрация приложений>Новая регистрация.
В форме регистрации выберите имя приложения и нажмите кнопку Зарегистрировать.
Чтобы разрешить приложению доступ к Defender для конечной точки и назначить ему разрешение "Чтение всех оповещений", на странице приложения выберите Разрешения> APIДобавить разрешения>API, которые использует> моя организация, введите WindowsDefenderATP, а затем выберите WindowsDefenderATP.

Примечание.

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

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

Необходимо выбрать соответствующие разрешения. "Чтение всех оповещений" — это только пример. Например:
- Чтобы выполнить расширенные запросы, выберите разрешение "Выполнение дополнительных запросов".
- Чтобы изолировать устройство, выберите разрешение "Изолировать компьютер".
- Чтобы определить, какое разрешение вам нужно, ознакомьтесь с разделом Разрешения в API, который требуется вызвать.
Выберите Предоставить согласие.

Примечание.

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

Примечание.

После нажатия кнопки Добавить выберите скопировать созданное значение секрета. Вы не сможете получить это значение после ухода.
Запишите идентификатор приложения и идентификатор клиента. На странице приложения перейдите в раздел Обзор и скопируйте следующее.
Только для партнеров Microsoft Defender для конечной точки. Задайте для приложения мультитенантное (доступно во всех клиентах после согласия). Это необходимо для сторонних приложений (например, если вы создаете приложение, которое предназначено для запуска в клиенте нескольких клиентов). Это не обязательно, если вы создаете службу, которую хотите запустить только в клиенте (например, если вы создаете приложение для собственного использования, которое будет взаимодействовать только с вашими данными). Чтобы настроить мультитенантное приложение, выполните приведенные далее действия.
- Перейдите в раздел Проверка подлинности и добавьте https://portal.azure.com в качестве URI перенаправления.
- В нижней части страницы в разделе Поддерживаемые типы учетных записей выберите согласие приложения "Учетные записи в любом каталоге организации " для мультитенантного приложения.
Приложение должно быть утверждено в каждом клиенте, где вы планируете его использовать. Это связано с тем, что приложение взаимодействует с 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
```
Где 000000000-0000-0000-0000-00000000000 заменяется идентификатором приложения.

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

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

Дополнительные сведения о маркерах 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 г. новые функции не добавлены. Мы настоятельно рекомендуем выполнить обновление. Дополнительные сведения см. в руководстве по миграции .

Create новое консольное приложение.
Установите NuGet Microsoft.Identity.Client.
Добавьте следующий код:
```
using Microsoft.Identity.Client;
```

Скопируйте и вставьте следующий код в приложение (не забудьте обновить три переменные: 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 уже установлен на компьютере.

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

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

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"}

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

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

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

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

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

Выберите API, который вы хотите использовать. Дополнительные сведения см. в разделе Поддерживаемые API Defender для конечных точек.
Задайте заголовок авторизации в HTTP-запросе, отправляемом в "Bearer {token}" (Bearer — это схема авторизации).
Срок действия маркера составляет один час. Вы можете отправить несколько запросов с одним и тем же маркером.

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

См. также