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

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

• Microsoft Defender XDR

Важно!

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

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

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

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

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

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

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

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

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

1. Войдите в Azure.

2. Перейдите в раздел Microsoft Entra ID>Регистрация приложений>Новая регистрация.

   

3. В форме выберите имя приложения, а затем нажмите кнопку Зарегистрировать.

4. На странице приложения выберите Разрешения> APIДобавить разрешения>API, которые использует> моя организация, введите Microsoft Threat Protection и выберите Microsoft Threat Protection. Теперь приложение может получить доступ к Microsoft Defender XDR.

   Совет

   Microsoft Threat Protection — это прежнее имя Microsoft Defender XDR и не будет отображаться в исходном списке. Чтобы оно появилось, необходимо написать его имя в текстовом поле.

   

5. Выберите Разрешения приложения. Выберите соответствующие разрешения для своего сценария (например, Incident.Read.All), а затем выберите Добавить разрешения.

   

   Примечание.

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

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

6. Выберите Предоставить согласие администратора. Каждый раз при добавлении разрешения необходимо выбрать Предоставить согласие администратора , чтобы оно войти в силу.

   

7. Чтобы добавить секрет в приложение, выберите Сертификаты & секреты, добавьте описание в секрет, а затем нажмите кнопку Добавить.

   Совет

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

   

8. Запишите идентификатор приложения и идентификатор клиента в безопасном месте. Они перечислены в разделе Обзор на странице приложения.

   

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

1. Создайте консольное приложение.

2. Установите NuGet Microsoft.Identity.Client.

3. Добавьте следующую строку:

   using Microsoft.Identity.Client;
   

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

1. Откройте командную строку и задайте для CLIENT_ID идентификатор приложения Azure.

2. Задайте для CLIENT_SECRET секрет приложения Azure.

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

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

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

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

2. Убедитесь, что утверждение ролей в декодированном маркере содержит необходимые разрешения.

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

   

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

1. Выберите API, который вы хотите использовать (инциденты или расширенная охота). Дополнительные сведения см. в статье Поддерживаемые API Microsoft Defender XDR.

2. В http-запросе, который вы хотите отправить, задайте для заголовка авторизации значение "Bearer" <token>, bearer — это схема авторизации, а маркер — ваш проверенный маркер.

3. Срок действия маркера истекает в течение одного часа. За это время можно отправить несколько запросов с одним и тем же маркером.

В следующем примере показано, как отправить запрос на получение списка инцидентов с помощью 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();

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

• Общие сведения об API Microsoft Defender XDR
• Доступ к API Microsoft Defender XDR
• Создание приложения "Hello мира"
• Создание приложения для доступа к MICROSOFT DEFENDER XDR API от имени пользователя
• Создание приложения с мультитенантным доступом партнеров к API Microsoft Defender XDR
• Сведения об ограничениях API и лицензировании
• Общие сведения о кодах ошибок
• Управление секретами в серверных приложениях с помощью Azure Key Vault
• Авторизация OAuth 2.0 для входа пользователей и доступа к API

Совет

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