Прочитать на английском

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


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

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

  • Microsoft Defender XDR

Важно!

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

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

Если вам нужен программный доступ к Microsoft Defender XDR от имени одного пользователя, см. статью Создание приложения для доступа к MICROSOFT DEFENDER XDR 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, необходимые ему ресурсы.
  • Получение маркера доступа для Microsoft Defender XDR
  • Проверка маркера

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

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

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

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

Создание мультитенантного приложения

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

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

    Раздел регистрации приложения на портале Microsoft Defender

  3. В форме регистрации:

    • Выберите имя приложения.
    • В разделе Поддерживаемые типы учетных записей выберите Учетные записи в любом каталоге организации (любой каталог Microsoft Entra) — Мультитенантный.
    • Заполните раздел URI перенаправления . Выберите тип Web и присвойте URI перенаправления как https://portal.azure.com.

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

    Разделы регистрации приложения на портале Microsoft Defender

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

    Совет

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

    Раздел

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

    Область разрешений приложения на портале Microsoft Defender

    Примечание

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

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

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

    Раздел для предоставления согласия администратора на портале Microsoft Defender

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

    Совет

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

    Раздел

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

    Панель

  9. Добавьте приложение в клиент пользователя.

    Так как приложение взаимодействует с 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 Defender

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

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

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

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

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

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

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

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

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

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

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

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

Область декодированного маркера на портале Microsoft Defender

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

Совет

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