Доступ к API приложений Microsoft Defender для облака с помощью контекста пользователя
На этой странице описывается, как создать приложение, чтобы получить программный доступ к Defender для облака Приложениям от имени пользователя.
Если вам нужен программный доступ Microsoft Defender для облака приложения без пользователя, обратитесь к разделу Access Microsoft Defender для облака Apps с контекстом приложения.
Если вы не уверены, какой доступ вам нужен, ознакомьтесь со страницей "Введение".
Microsoft Defender для облака Приложения предоставляют большую часть своих данных и действий с помощью набора программных API. Эти API позволяют автоматизировать рабочие потоки и инновации на основе возможностей приложений Microsoft Defender для облака. Для доступа к API требуется проверка подлинности OAuth2.0. Дополнительные сведения см. в статье OAuth 2.0.
Как правило, вам потребуется выполнить следующие действия, чтобы использовать API:
- Создание приложения Microsoft Entra
- Получение маркера доступа с помощью этого приложения
- Использование маркера для доступа к API приложений Defender для облака
На этой странице объясняется, как создать приложение Microsoft Entra, получить маркер доступа для Microsoft Defender для облака Apps и проверить маркер.
Примечание.
При доступе к API приложений Microsoft Defender для облака от имени пользователя вам потребуется правильное разрешение приложения и разрешение пользователя. Если вы не знакомы с разрешениями пользователей на Microsoft Defender для облака Apps, см. статью "Управление доступом администратора".
Совет
Если у вас есть разрешение на выполнение действия на портале, у вас есть разрешение на выполнение действия в API.
Создать приложение
Войдите в Azure с учетной записью пользователя с ролью Глобального Администратор istrator.
Перейдите к идентификатору Microsoft Entra ID> Регистрация приложений> New.
Когда появится страница Регистрация приложения, введите регистрационную информацию приложения:
Имя — введите информативное имя приложения, которое будет отображаться пользователям приложения.
Поддерживаемые типы учетных записей — выберите учетные записи, которые должно поддерживать приложение.
Поддерживаемые типы счетов Описание Accounts in this organizational directory only (Учетные записи только в этом каталоге организации) Этот вариант подходит для создания бизнес-приложений. Он будет недоступен, если приложение не регистрируется в каталоге.
Этот параметр сопоставляется только с одним клиентом Microsoft Entra.
Этот параметр используется по умолчанию, если только приложение не регистрируется за пределами каталога. В случаях, когда приложение зарегистрировано вне каталога, по умолчанию используется мультитенантная и личная учетная запись Майкрософт Microsoft Entra.Учетные записи в любом каталоге организации Выберите этот параметр, если вы хотите выбрать в качестве целевой аудитории предприятия и учебные заведения.
Этот параметр сопоставляется с несколькими клиентами только для Microsoft Entra.
Если вы зарегистрировали приложение в качестве одного клиента только для Microsoft Entra, его можно обновить, чтобы microsoft Entra multi-tenant и вернуться в один клиент через панель проверки подлинности .Accounts in any organizational directory and personal Microsoft accounts (Учетные записи в любом каталоге организации и личные учетные записи Майкрософт) Этот параметр предназначен для самого широкого набора клиентов.
Этот параметр сопоставляется с мультитенантными и личными учетными записями Майкрософт в Microsoft Entra.
Если вы зарегистрировали приложение в качестве мультитенантных и личных учетных записей Майкрософт Microsoft Entra, вы не можете изменить это в пользовательском интерфейсе. Вместо этого необходимо изменить поддерживаемые типы учетных записей с помощью редактора манифестов приложений.URI перенаправления (необязательно) — выберите тип приложения, которое вы создаете — Web (Веб) или Public client (mobile & desktop) (Общедоступный клиент (для мобильных и классических приложений)), а затем введите универсальный код ресурса (URI) перенаправления (или URL-адрес ответа) приложения.
- Для веб-приложений укажите основной URL-адрес приложения. Например, выполняемое на локальном компьютере веб-приложение может иметь адрес
http://localhost:31544
. Пользователи будут использовать этот URL-адрес для входа в приложение веб-клиента. - Для общедоступных клиентских приложений укажите универсальный код ресурса (URI), используемый идентификатором Microsoft Entra для возврата ответов маркеров. Укажите значение, специфичное для вашего приложения, например
myapp://auth
.
Конкретные примеры для веб-приложений или собственных приложений см. в наших кратких руководствах.
По завершении щелкните Зарегистрировать.
- Для веб-приложений укажите основной URL-адрес приложения. Например, выполняемое на локальном компьютере веб-приложение может иметь адрес
Разрешите приложению доступ к приложениям Microsoft Defender для облака и назначьте ему разрешение "Чтение оповещений":
На странице приложения выберите API Permissions>Add permissionis>my organization использует> тип Microsoft Cloud App Security, а затем выберите Microsoft Cloud App Security.
Примечание. Microsoft Cloud App Security не отображается в исходном списке. Начните писать его имя в текстовом поле, чтобы увидеть его. Не забудьте ввести это имя, даже если продукт теперь называется Defender для облака Apps.
Выбор делегированных>разрешений Investigation.Read> выберите "Добавить разрешения"
Важное примечание. Выберите соответствующие разрешения. Investigation.Read является только примером. Сведения о других область разрешения см. в разделе "Поддерживаемые область"
- Чтобы определить нужное разрешение, просмотрите раздел "Разрешения " в API, который вы хотите вызвать.
Нажмите Предоставить согласие администратора.
Примечание. При каждом добавлении разрешения необходимо выбрать предоставление согласия администратора для принятия нового разрешения.
Запишите идентификатор приложения и идентификатор клиента:
На странице приложения перейдите к обзору и скопируйте следующие сведения:
Поддерживаемые область разрешений
Имя разрешения | Description | Поддерживаемые действия |
---|---|---|
Investigation.read | Выполните все поддерживаемые действия по действиям и оповещениям, кроме закрытия оповещений. Просмотр диапазонов IP-адресов, но не добавление, обновление или удаление. Выполните все действия сущностей. |
Список действий, получение, обратная связь Список оповещений, получение, пометка как чтение или непрочитанное Список сущностей, получение, дерево получения Список подсетей |
Исследование.manage | Выполняйте все действия исследования.read в дополнение к управлению оповещениями и диапазонами IP-адресов. | Список действий, получение, обратная связь Список оповещений, получение, отметка как чтение или непрочитанное, закрытие Список сущностей, получение, дерево получения Список подсетей, создание, обновление и удаление |
Discovery.read | Выполните все поддерживаемые действия по действиям и оповещениям, кроме закрытия оповещений. Вывод списка отчетов и категорий обнаружения. |
Список оповещений, получение, пометка как чтение или непрочитанное Отчеты списка обнаружения, категории отчетов списка |
Discovery.manage | Разрешения discovery.read Закрытие оповещений, отправка файлов обнаружения и создание скриптов блоков |
Список оповещений, получение, отметка как чтение или непрочитанное, закрытие Отчеты списка обнаружения, категории отчетов списка Отправка файла обнаружения, создание скрипта блокировки |
Параметры.read | Список диапазонов IP-адресов. | Список подсетей |
Параметры.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 для облака
Выберите API, который вы хотите использовать. Дополнительные сведения см. в Defender для облака API приложений.
Задайте заголовок авторизации в 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