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

Доступ к Microsoft Defender for Cloud Apps с помощью контекста приложения

  • Статья

На этой странице описывается создание приложения для получения программного доступа к Defender for Cloud Apps без пользователя. Если вам нужен программный доступ к Defender for Cloud Apps от имени пользователя, см. статью Получение доступа с помощью контекста пользователя. Если вы не знаете, какой доступ вам нужен, см. страницу Управление маркерами API .

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

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

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

В этой статье объясняется, как создать приложение Microsoft Entra, получить маркер доступа для Microsoft Defender for Cloud Apps и проверить маркер.

Создание приложения для Defender for Cloud Apps

  1. В Центр администрирования Microsoft Entra зарегистрируйте новое приложение. Дополнительные сведения см. в разделе Краткое руководство. Регистрация приложения с помощью Центр администрирования Microsoft Entra.

  2. Чтобы разрешить приложению доступ к Defender for Cloud Apps и назначить ему разрешение "Чтение всех оповещений", на странице приложения выберите Разрешения> APIДобавить разрешения>API, которые используются> в вашей организации, введите Microsoft Cloud App Security, а затем выберите Microsoft Cloud App Security.

    Примечание.

    Microsoft Cloud App Security не отображается в исходном списке. Начните писать его имя в текстовом поле, чтобы увидеть его появление. Обязательно введите это имя, хотя продукт теперь называется Defender for Cloud Apps.

    Снимок экрана: добавление разрешения.

    • Выберите Application permissions>Investigation.Read(Изучение разрешений приложения.Чтение), а затем — Добавить разрешения.

      Снимок экрана: добавление разрешения приложения.

      Необходимо выбрать соответствующие разрешения. Investigation.Read — это только пример. Другие области разрешений см. в разделе Поддерживаемые области разрешений.

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

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

    Примечание.

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

    Снимок экрана: предоставление разрешений администратора.

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

    Примечание.

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

    Снимок экрана: создание ключа приложения.

  5. Запишите идентификатор приложения и идентификатор клиента. На странице приложения перейдите в раздел Обзор и скопируйте идентификатор приложения (клиента) и идентификатор каталога (клиента).

    Снимок экрана: созданный идентификатор приложения.

  6. Только для партнеров Microsoft Defender for Cloud Apps. Настройте мультитенантное приложение (доступно во всех клиентах после согласия). Это необходимо для сторонних приложений (например, если вы создаете приложение, которое предназначено для запуска в клиенте нескольких клиентов). Это не обязательно, если вы создаете службу, которую хотите запустить только в клиенте (например, если вы создаете приложение для собственного использования, которое будет взаимодействовать только с вашими данными). Чтобы настроить мультитенантное приложение, выполните приведенные далее действия.

    • Перейдите в раздел Проверка подлинности и добавьте https://portal.azure.com в качестве URI перенаправления.

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

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

    Вам (или вашему клиенту, если вы пишете стороннее приложение) необходимо выбрать ссылку согласия и утвердить приложение. Согласие должно быть сделано с пользователем, который имеет права администратора в Active Directory.

    Ссылка на согласие формируется следующим образом:

    https://login.microsoftonline.com/common/oauth2/authorize?prompt=consent&client_id=00000000-0000-0000-0000-000000000000&response_type=code&sso_reload=true

    Где 000000000-0000-0000-0000-00000000000 заменяется идентификатором приложения.

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

Поддерживаемые области разрешений

Имя разрешения Описание Поддерживаемые действия
Investigation.read Выполнение всех поддерживаемых действий с действиями и оповещениями, кроме оповещений о закрытии.
Просматривайте диапазоны IP-адресов, но не добавляйте, не обновляйте и не удаляйте.

Выполнение всех действий сущностей.		 Список действий, выборка, отзыв
Список оповещений, выборка, пометка как прочитанные или непрочитанные
Список сущностей, выборка, дерево выборки
Список подсетей
Investigation.manage Выполните все действия investigation.read в дополнение к управлению оповещениями и диапазонами IP-адресов. Список действий, выборка, отзыв
Список оповещений, выборка, пометка как чтение/непрочитанное, закрытие
Список сущностей, выборка, дерево выборки
Список подсетей, создание, обновление и удаление
Discovery.read Выполнение всех поддерживаемых действий с действиями и оповещениями, кроме оповещений о закрытии.
Вывод списка отчетов об обнаружении и категорий.		 Список оповещений, выборка, пометка как прочитанные или непрочитанные
Отчеты списка обнаружения, категории отчетов списка
Discovery.manage Разрешения Discovery.read
Закрытие оповещений, отправка файлов обнаружения и создание сценариев блоков		 Список оповещений, выборка, пометка как чтение/непрочитанное, закрытие
Отчеты списка обнаружения, категории отчетов списка
Отправка файла обнаружения, создание скрипта блока
Settings.read Список диапазонов IP-адресов. Список подсетей
Settings.manage Вывод списка диапазонов IP-адресов и управление ими. Список подсетей, создание, обновление и удаление

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

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

Воспользуйтесь PowerShell

# This script acquires the App Context Token and stores it in the variable $token for later use in the script.
# Paste your Tenant ID, App ID, and App Secret (App key) into the indicated quotes below.

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

$resourceAppIdUri = '05a65629-4c1b-48c1-a78b-804c4abdd4af'
$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

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

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

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

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

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

    using Microsoft.Identity.Client;

  4. Скопируйте и вставьте следующий код в приложение (не забудьте обновить три переменные: tenantId, appId, appSecret):

    string tenantId = "00000000-0000-0000-0000-000000000000"; // Paste your own tenant ID here
string appId = "00001111-aaaa-2222-bbbb-3333cccc4444"; // 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 = "05a65629-4c1b-48c1-a78b-804c4abdd4af";

IConfidentialClientApplication myApp = ConfidentialClientApplicationBuilder.Create(appId).WithClientSecret(appSecret).WithAuthority($"{authority}/{tenantId}").Build();

List scopes = new List() { $"{audience}/.default" };

AuthenticationResult authResult = myApp.AcquireTokenForClient(scopes).ExecuteAsync().GetAwaiter().GetResult();

string token = authResult.AccessToken;

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

См . статью Библиотека проверки подлинности Майкрософт (MSAL) для Python.

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

Примечание.

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

  1. Откройте командную строку и задайте для CLIENT_ID идентификатор приложения Azure.
  2. Задайте для CLIENT_SECRET секрет приложения Azure.
  3. Задайте TENANT_ID идентификатор клиента Azure, который хочет использовать приложение для доступа к Defender for Cloud Apps.
  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=05a65629-4c1b-48c1-a78b-804c4abdd4af/.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. Убедитесь, что вы получили утверждение "роли" с требуемыми разрешениями
  3. На следующем рисунке показан декодированные маркеры, полученные из приложения с разрешениями для всех Microsoft Defender for Cloud Apps ролей:

Снимок экрана: проверка маркера.

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

  1. Выберите API, который вы хотите использовать. Дополнительные сведения см. в разделе API Defender for Cloud Apps.
  2. Задайте заголовок авторизации в HTTP-запросе, отправляемом в "Bearer {token}" (Bearer — это схема авторизации).
  3. Срок действия маркера составляет один час. Вы можете отправить несколько запросов с одним и тем же маркером.

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

    var httpClient = new HttpClient();

    var request = new HttpRequestMessage(HttpMethod.Get, "https://portal.cloudappsecurity.com/cas/api/v1/alerts/");

    request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);

    var response = httpClient.SendAsync(request).GetAwaiter().GetResult();

    // Do something useful with the response

См. также