Создание приложения с партнерским доступом к 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 и проверить маркер.
Войдите в 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.
Совет
В следующих примерах используйте идентификатор клиента пользователя, чтобы проверить работу скрипта.
# 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
Примечание
Следующий код был протестирован с помощью Nuget Microsoft.Identity.Client 3.19.8.
Важно!
Пакет NuGet Microsoft.IdentityModel.Clients.ActiveDirectory и библиотека аутентификация Azure AD (ADAL) устарели. С 30 июня 2020 г. новые функции не добавлены. Мы настоятельно рекомендуем выполнить обновление. Дополнительные сведения см. в руководстве по миграции .
Создайте консольное приложение.
Установите 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;
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 предварительно установлен на 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, который вы хотите использовать (инциденты или расширенная охота). Дополнительные сведения см. в статье Поддерживаемые 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();
- Общие сведения об API Microsoft Defender XDR
- Доступ к API Microsoft Defender XDR
- Создание приложения "Hello мира"
- Создание приложения для доступа к Microsoft Defender XDR без пользователя
- Создание приложения для доступа к MICROSOFT DEFENDER XDR API от имени пользователя
- Сведения об ограничениях API и лицензировании
- Общие сведения о кодах ошибок
- Управление секретами в серверных приложениях с помощью Azure Key Vault
- Авторизация OAuth 2.0 для входа пользователей и доступа к API
Совет
Хотите узнать больше? Общайтесь с членами сообщества Microsoft Security в нашем техническом сообществе: Microsoft Defender XDR Tech Community.