Create приложения с партнерским доступом к API Microsoft Defender XDR

Статья
04/27/2024

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

Microsoft Defender XDR

Важно!

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

На этой странице описано, как создать приложение Microsoft Entra, которое имеет программный доступ к Microsoft Defender XDR от имени пользователей в нескольких клиентах. Мультитенантные приложения полезны для обслуживания больших групп пользователей.

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

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, необходимые ему ресурсы.
Получение маркера доступа для Microsoft Defender XDR
Проверка маркера

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

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

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

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

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

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

Совет

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

Примечание.

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

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

Совет

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

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

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

Ссылка на согласие имеет следующий вид:
```
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!

$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):

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

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

Скопируйте и вставьте маркер на веб-сайт проверяющего веб-маркера 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 приложения с партнерским доступом к API Microsoft Defender XDR

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

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

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

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

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

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

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

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

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

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

Поделиться через

Create приложения с партнерским доступом к API Microsoft Defender XDR

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

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

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

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

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

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

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

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

Статьи по теме

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

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