Доступ к API Microsoft Defender for Cloud Apps с помощью контекста пользователя

Статья
11/28/2024

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

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

Если вы не знаете, какой доступ вам нужен, прочитайте страницу Введение.

Microsoft Defender for Cloud Apps предоставляет большую часть своих данных и действий с помощью набора программных API. Эти API позволяют автоматизировать рабочие потоки и внедрять инновации на основе Microsoft 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 и проверить маркер.

Примечание.

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

Совет

Если у вас есть разрешение на выполнение действия на портале, у вас есть разрешение на выполнение действия в API.

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

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

После появления страницы Регистрация приложения введите сведения о регистрации приложения:

Имя — введите понятное имя приложения, которое отображается для пользователей приложения.

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

Поддерживаемые типы учетных записей	Описание
Учетные записи только в этом каталоге организации	Этот вариант подходит для создания бизнес-приложений. Этот параметр недоступен, если вы не регистрируете приложение в каталоге. Этот параметр сопоставляется с Microsoft Entra только с одним клиентом. Этот параметр используется по умолчанию, если только приложение не регистрируется за пределами каталога. В случаях, когда приложение зарегистрировано вне каталога, по умолчанию используется Microsoft Entra мультитенантных и личных учетных записей Майкрософт.
Учетные записи в любом каталоге организации	Выберите этот параметр, если вы хотите выбрать в качестве целевой аудитории предприятия и учебные заведения. Этот параметр сопоставляется с мультитенантом только для Microsoft Entra. Если вы зарегистрировали приложение как Microsoft Entra только один клиент, его можно обновить, чтобы оно было Microsoft Entra мультитенантным и обратно в один клиент с помощью области Проверка подлинности.
Учетные записи в любом каталоге организации и личные учетные записи Майкрософт	Выберите этот параметр для широкого круга пользователей. Этот параметр сопоставляется с Microsoft Entra мультитенантными и личными учетными записями Майкрософт. Если вы зарегистрировали приложение как Microsoft Entra мультитенантных и личных учетных записей Майкрософт, изменить это в пользовательском интерфейсе невозможно. Вместо этого необходимо использовать редактор манифеста приложения для изменения типов поддерживаемых учетных записей.

URI перенаправления (необязательно) — выберите тип создаваемого приложения, **Веб или Общедоступный клиент (мобильный & настольный компьютер), а затем введите URI перенаправления (или URL-адрес ответа) для приложения.
- Для веб-приложений укажите основной URL-адрес приложения. Например, http://localhost:31544 может быть URL-адресом веб-приложения, выполняемого на локальном компьютере. Пользователи будут использовать этот URL-адрес для входа в приложение веб-клиента.
- Для общедоступных клиентских приложений укажите универсальный код ресурса (URI), используемый Microsoft Entra ID для возврата ответов маркера. Укажите значение, специфичное для вашего приложения, например myapp://auth.
Конкретные примеры для веб-приложений или собственных приложений см. в наших кратких руководствах.

По завершении щелкните Зарегистрировать.

Разрешите приложению доступ к Microsoft Defender for Cloud Apps и назначьте ему разрешение "Чтение оповещений":
- На странице приложения выберите Разрешения> APIДобавить API разрешений>API, которые использует моя организация,> введите Microsoft Cloud App Security, а затем выберите Microsoft Cloud App Security.
- Примечание. Microsoft Cloud App Security не отображается в исходном списке. Начните писать его имя в текстовом поле, чтобы увидеть его появление. Обязательно введите это имя, хотя продукт теперь называется Defender for Cloud Apps.
- Выберите Исследование делегированных>разрешений.На чтение> выберите Добавить разрешения
- Важное примечание. Выберите соответствующие разрешения. Investigation.Read — это только пример. Другие области разрешений см. в разделе Поддерживаемые области разрешений.
  - Чтобы определить, какое разрешение вам нужно, просмотрите раздел Разрешения в API, который требуется вызвать.
- Выберите Предоставить согласие администратора.
  
  Примечание. При каждом добавлении разрешения необходимо выбрать Предоставить согласие администратора , чтобы новое разрешение войлось в силу.
Запишите идентификатор приложения и идентификатор клиента:
- На странице приложения перейдите в раздел Обзор и скопируйте следующие сведения:

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

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

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

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

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

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

Примечание.

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

namespace MDA
{
    using System.Net.Http;
    using System.Text;
    using System.Threading.Tasks;
    using Newtonsoft.Json.Linq;

    public static class MDAUtils
    {
        private const string Authority = "https://login.microsoftonline.com";

        private const string MDAId = "05a65629-4c1b-48c1-a78b-804c4abdd4af";
        private const string Scope = "Investigation.read";

        public static async Task<string> AcquireUserTokenAsync(string username, string password, string appId, string tenantId)
        {
            using (var httpClient = new HttpClient())
            {
                var urlEncodedBody = $"scope={MDAId}/{Scope}&client_id={appId}&grant_type=password&username={username}&password={password}";

                var stringContent = new StringContent(urlEncodedBody, Encoding.UTF8, "application/x-www-form-urlencoded");

                using (var response = await httpClient.PostAsync($"{Authority}/{tenantId}/oauth2/token", stringContent).ConfigureAwait(false))
                {
                    response.EnsureSuccessStatusCode();

                    var json = await response.Content.ReadAsStringAsync().ConfigureAwait(false);

                    var jObject = JObject.Parse(json);

                    return jObject["access_token"].Value<string>();
                }
            }
        }
    }
}

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

Убедитесь, что вы получили правильный маркер:

Скопируйте или вставьте в JWT маркер, полученный на предыдущем шаге, чтобы декодировать его
Убедитесь, что вы получили утверждение scp с нужными разрешениями приложения.
На снимке экрана ниже вы можете увидеть декодированные маркеры, полученные из приложения в этом руководстве:

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

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

Пример отправки запроса на получение списка оповещений с помощью 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

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