Партнерский доступ через API Microsoft Defender для конечной точки

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

• Microsoft Defender для конечной точки (план 1)
• Microsoft Defender для конечной точки (план 2)
• Microsoft Defender для бизнеса

Важно!

Расширенные возможности охоты не включены в Defender для бизнеса.

Хотите попробовать Microsoft Defender для конечной точки? Зарегистрироваться для бесплатной пробной версии.

Примечание.

Если вы являетесь клиентом для государственных организаций США, используйте URI, перечисленные в Microsoft Defender для конечной точки для клиентов государственных организаций США.

Совет

Для повышения производительности можно использовать сервер ближе к географическому расположению:

• us.api.security.microsoft.com
• eu.api.security.microsoft.com
• uk.api.security.microsoft.com
• au.api.security.microsoft.com
• swa.api.security.microsoft.com
• ina.api.security.microsoft.com

На этой странице описывается создание приложения Microsoft Entra для получения программного доступа к Microsoft Defender для конечной точки от имени клиентов.

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

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

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

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

3. Получите маркер доступа с помощью этого приложения.

4. Используйте маркер для доступа к API Microsoft Defender для конечной точки.

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

Важно!

Microsoft рекомендует использовать роли с наименьшим количеством разрешений. Это помогает повысить безопасность вашей организации. Глобальный администратор — это роль с высокими привилегиями, которую следует ограничивать экстренными сценариями, когда вы не можете использовать существующую роль.

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

1. Войдите в клиент Azure.

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

   

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

   • Выберите имя приложения.

   • Поддерживаемые типы учетных записей — учетные записи в любом каталоге организации.

   • URI перенаправления— тип: Web, URI: https://portal.azure.com

     

4. Разрешите приложению доступ к Microsoft Defender для конечной точки и назначьте ему минимальный набор разрешений, необходимых для завершения интеграции.

   • На странице приложения выберите Разрешения> APIДобавить API разрешений>API, которые моя организация использует>, введите WindowsDefenderATP и выберите WindowsDefenderATP.

   • WindowsDefenderATP не отображается в исходном списке. Начните писать его имя в текстовом поле, чтобы увидеть его появление.

     

Запрос разрешений API

Чтобы определить, какое разрешение вам нужно, ознакомьтесь с разделом Разрешения в API, который требуется вызвать. Например:

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

В следующем примере используется разрешение Чтение всех оповещений :

1. Выберите Разрешения> приложенияAlert.Read.All> выберите Добавить разрешения.

   

2. Выберите Предоставить согласие.

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

   

3. Добавьте секрет в приложение.

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

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

   

4. Запишите идентификатор приложения:

   • На странице приложения перейдите в раздел Обзор и скопируйте следующие сведения:

     

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

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

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

   Ссылка на согласие имеет следующий вид:

   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 следует заменить идентификатором приложения.

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

   

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

6. Готово! Вы успешно зарегистрировали приложение! Сведения о получении и проверке маркеров см. в следующих примерах.

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

Чтобы получить маркер доступа от имени клиента, используйте идентификатор клиента для следующих приобретений маркеров.

Дополнительные сведения о маркере Microsoft Entra см. в руководстве по Microsoft Entra.

С помощью PowerShell

# That code gets the App Context Token and save it to a file named "Latest-token.txt" under the current directory
# Paste below your Tenant ID, App ID and App Secret (App key).

$tenantId = '' ### Paste your tenant ID here
$appId = '' ### Paste your Application ID here
$appSecret = '' ### Paste your Application key here

$resourceAppIdUri = 'https://api.securitycenter.microsoft.com'
$oAuthUri = "https://login.microsoftonline.com/$TenantId/oauth2/token"
$authBody = [Ordered] @{
    resource = "$resourceAppIdUri"
    client_id = "$appId"
    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.IdentityModel.Clients.ActiveDirectory и библиотека аутентификация Azure AD (ADAL) устарели. С 30 июня 2020 г. новые функции не добавлены. Сведения об обновлении см. в руководстве по миграции.

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

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

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

    using Microsoft.Identity.Client;
   

   Этот код был протестирован с помощью NuGet Microsoft.Identity.Client.

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

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

Использование Curl

Примечание.

Следующая процедура предполагает, что Curl для Windows уже установлен на вашем компьютере

1. Откройте окно командной строки.

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

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

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

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

   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. Скопируйте или вставьте в JWT маркер, который вы получили на предыдущем шаге, чтобы декодировать его.

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

   На следующем снимке экрана показан декодированные маркеры, полученные из приложения с несколькими разрешениями на Microsoft Defender для конечной точки:

   

   Утверждение tid — это идентификатор клиента, к которому принадлежит маркер.

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

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

2. Задайте заголовок Authorization в http-запросе, в который вы отправляете Bearer {token} (bearer — это схема авторизации). Срок действия маркера составляет один час (с одним и тем же маркером можно отправить несколько запросов).

   Ниже приведен пример отправки запроса на получение списка оповещений с помощью C#:

   var httpClient = new HttpClient();
   
   var request = new HttpRequestMessage(HttpMethod.Get, "https://api.securitycenter.microsoft.com/api/alerts");
   
   request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
   
   var response = httpClient.SendAsync(request).GetAwaiter().GetResult();
   
    // Do something useful with the response
   

См. также

• Поддерживаемые API Microsoft Defender для конечной точки
• Доступ к Microsoft Defender для конечной точки от имени пользователя

Совет

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