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

Статья
04/29/2024

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

Microsoft Defender XDR

Важно!

Некоторые сведения относятся к предварительным выпускам продуктов, которые могут быть существенно изменены до коммерческого выпуска. Корпорация Майкрософт не дает никаких гарантий, явных или подразумеваемых, относительно предоставленных здесь сведений.

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

Если вам нужен программный доступ к Microsoft Defender XDR от имени одного или нескольких пользователей, см. статью Create приложению для доступа к MICROSOFT DEFENDER XDR API от имени пользователя и Create приложение с партнерским доступом к Microsoft Defender XDR API. Если вы не знаете, какой тип доступа вам нужен, см. статью Начало работы.

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

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

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

В этой статье объясняется, как:

Create приложения Microsoft Entra
Получение маркера доступа для Microsoft Defender XDR
Проверьте маркер.

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

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

Совет

Microsoft Threat Protection — это прежнее имя Microsoft Defender XDR и не будет отображаться в исходном списке. Чтобы оно появилось, необходимо написать его имя в текстовом поле.
Выберите Разрешения приложения. Выберите соответствующие разрешения для своего сценария (например, Incident.Read.All), а затем выберите Добавить разрешения.

Примечание.

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

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

Совет

После нажатия кнопки Добавить выберите скопировать созданное значение секрета. Вы не сможете получить значение секрета после выхода.
Запишите идентификатор приложения и идентификатор клиента в безопасном месте. Они перечислены в разделе Обзор на странице приложения.
Только для партнеров Microsoft Defender XDR. Следуйте приведенным ниже инструкциям для доступа партнеров через API-интерфейсы Microsoft Defender XDR, настройте приложение как мультитенантное, чтобы оно было доступно во всех клиентах после получения согласия администратора. Партнерский доступ требуется для сторонних приложений, например, если вы создаете приложение, которое предназначено для запуска в нескольких клиентах. Он не требуется , если вы создаете службу, которую хотите запустить только в клиенте, например приложение для собственного использования, которое будет взаимодействовать только с вашими данными. Чтобы установить мультитенантное приложение, выполните приведенные далее действия.
- Перейдите в раздел Проверка подлинности и добавьте https://portal.azure.com в качестве URI перенаправления.
- В нижней части страницы в разделе Поддерживаемые типы учетных записей выберите согласие приложения "Учетные записи в любом каталоге организации " для мультитенантного приложения.
Так как приложение взаимодействует с Microsoft Defender XDR от имени пользователей, оно должно быть утверждено для каждого клиента, в котором вы планируете его использовать.

Глобальный администратор 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.

Важно!

Хотя в примерах в этом разделе рекомендуется вставлять значения секретов для тестирования, никогда не следует жестко кодировать секреты в приложение, работающее в рабочей среде. Третья сторона может использовать ваш секрет для доступа к ресурсам. Вы можете защитить секреты приложения с помощью azure Key Vault. Практический пример защиты приложения см. в статье Управление секретами в серверных приложениях с помощью Azure Key Vault.

Получение маркера доступа с помощью PowerShell

# This code gets the application context token and saves it to a file named "Latest-token.txt" under the current directory.

$tenantId = '' # Paste your directory (tenant) ID here
$clientId = '' # Paste your application (client) ID here
$appSecret = '' # Paste your own app secret here to test, then store it in a safe place, such as the Azure Key Vault!

$resourceAppIdUri = 'https://api.security.microsoft.com'
$oAuthUri = "https://login.windows.net/$tenantId/oauth2/token"

$authBody = [Ordered] @{
    resource = $resourceAppIdUri
    client_id = $clientId
    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 3.19.8.

Важно!

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

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

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

csharp
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

import json
import urllib.request
import urllib.parse

tenantId = '' # Paste your directory (tenant) ID here
clientId = '' # Paste your application (client) ID here
appSecret = '' # Paste your own app secret here to test, then store it in a safe place, such as the Azure Key Vault!

url = "https://login.windows.net/%s/oauth2/token" % (tenantId)

resourceAppIdUri = 'https://api.security.microsoft.com'

body = {
    'resource' : resourceAppIdUri,
    'client_id' : clientId,
    'client_secret' : appSecret,
    'grant_type' : 'client_credentials'
}

data = urllib.parse.urlencode(body).encode("utf-8")

req = urllib.request.Request(url, data)
response = urllib.request.urlopen(req)
jsonResponse = json.loads(response.read())
aadToken = jsonResponse["access_token"]

Получение маркера доступа с помощью curl

Примечание.

Curl предварительно установлен на Windows 10 версии 1803 и более поздних. Для других версий Windows скачайте и установите средство непосредственно с официального веб-сайта curl.

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

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

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://api.security.microsoft.com/.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"}

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

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

На следующем рисунке показан декодированные маркеры, полученные из приложения с Incidents.Read.Allразрешениями , Incidents.ReadWrite.Allи AdvancedHunting.Read.All :

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

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

В следующем примере показано, как отправить запрос на получение списка инцидентов с помощью C#.

    var httpClient = new HttpClient();
    var request = new HttpRequestMessage(HttpMethod.Get, "https://api.security.microsoft.com/api/incidents");

    request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);

    var response = httpClient.SendAsync(request).GetAwaiter().GetResult();

Совет

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

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

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

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

Получение маркера доступа с помощью PowerShell

Получение маркера доступа с помощью C#

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

Получение маркера доступа с помощью curl

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

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

Обратная связь

Обратная связь

Дополнительные ресурсы

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

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

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

Получение маркера доступа с помощью PowerShell

Получение маркера доступа с помощью C#

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

Получение маркера доступа с помощью curl

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

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

Связанные статьи

Обратная связь

Обратная связь

Дополнительные ресурсы