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

Статья
04/26/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

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

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

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

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

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

Create мультитенантное приложение

Войдите в клиент Azure с помощью пользователя с ролью глобального администратора .
Перейдите в раздел Microsoft Entra ID>Регистрация приложений>Новая регистрация.
В форме регистрации:
- Выберите имя приложения.
- Поддерживаемые типы учетных записей — учетные записи в любом каталоге организации.
- URI перенаправления— тип: Web, URI: https://portal.azure.com
Разрешите приложению доступ к Microsoft Defender для конечной точки и назначьте ему минимальный набор разрешений, необходимых для завершения интеграции.
- На странице приложения выберите Разрешения> APIДобавить API разрешений>API, которые моя организация использует>, введите WindowsDefenderATP и выберите WindowsDefenderATP.
- Обратите внимание, что WindowsDefenderATP не отображается в исходном списке. Начните писать его имя в текстовом поле, чтобы увидеть его появление.

Запрос разрешений API

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

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

В следующем примере используется разрешение "Чтение всех оповещений".

Выберите Разрешения> приложенияAlert.Read.All> выберите Добавить разрешения.
Выберите Предоставить согласие.
- Примечание. При каждом добавлении разрешения необходимо выбрать параметр Предоставить согласие , чтобы новое разрешение войти в силу.
Добавьте секрет в приложение.
- Выберите Сертификаты & секреты, добавьте описание в секрет и нажмите кнопку Добавить.
Важно! После нажатия кнопки Добавить обязательно скопируйте созданное значение секрета. Вы не сможете получить его после отъезда!
Запишите идентификатор приложения:
- На странице приложения перейдите в раздел Обзор и скопируйте следующие сведения:
Добавьте приложение в клиент клиента.

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

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

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

Щелкнув ссылку согласия, войдите в систему с помощью глобального администратора клиента клиента и согласившись с приложением.

Кроме того, необходимо запросить у клиента идентификатор клиента и сохранить его для использования в будущем при получении маркера.
Готово! Вы успешно зарегистрировали приложение! Сведения о получении и проверке маркеров см. в следующих примерах.

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

Примечание: Чтобы получить маркер доступа от имени клиента, используйте идентификатор клиента для следующих приобретений маркеров.

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

С помощью PowerShell

# That code gets the App Context Token and save it to a file named "Latest-token.txt" under the current directory
# Paste below your Tenant ID, App ID and App Secret (App key).

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

$resourceAppIdUri = 'https://api.securitycenter.microsoft.com'
$oAuthUri = "https://login.microsoftonline.com/$TenantId/oauth2/token"
$authBody = [Ordered] @{
    resource = "$resourceAppIdUri"
    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
Out-File -FilePath "./Latest-token.txt" -InputObject $token
return $token

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

Приведенный ниже код был протестирован с помощью Nuget Microsoft.Identity.Client

Важно!

Пакет 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 клиента, который хочет использовать приложение для доступа к Microsoft 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 маркер, который вы получили на предыдущем шаге, чтобы декодировать его.
Убедитесь, что вы получили утверждение "roles" с нужными разрешениями.

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

Утверждение tid — это идентификатор клиента, к которому принадлежит маркер.

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

См. также