Доступ к API приложений Microsoft Defender для облака с помощью контекста пользователя

Статья
10/20/2023

На этой странице описывается, как создать приложение, чтобы получить программный доступ к 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.

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

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

Когда появится страница Регистрация приложения, введите регистрационную информацию приложения:

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

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

Поддерживаемые типы счетов	Описание
Accounts in this organizational directory only (Учетные записи только в этом каталоге организации)	Этот вариант подходит для создания бизнес-приложений. Он будет недоступен, если приложение не регистрируется в каталоге. Этот параметр сопоставляется только с одним клиентом Microsoft Entra. Этот параметр используется по умолчанию, если только приложение не регистрируется за пределами каталога. В случаях, когда приложение зарегистрировано за пределами каталога, по умолчанию используется мультитенантная и личная учетная запись Майкрософт.
Учетные записи в любом каталоге организации	Выберите этот параметр, если вы хотите выбрать в качестве целевой аудитории предприятия и учебные заведения. Этот параметр сопоставляется с мультитенантом только для Microsoft Entra. Если вы зарегистрировали приложение в качестве одного клиента только для Microsoft Entra, его можно обновить, чтобы он был мультитенантным и обратно в один клиент через панель проверки подлинности .
Accounts in any organizational directory and personal Microsoft accounts (Учетные записи в любом каталоге организации и личные учетные записи Майкрософт)	Этот параметр предназначен для самого широкого набора клиентов. Этот параметр сопоставляется с мультитенантными и личными учетными записями Майкрософт в Microsoft Entra. Если вы зарегистрировали приложение в качестве мультитенантных и личных учетных записей Майкрософт, это невозможно изменить в пользовательском интерфейсе. Вместо этого необходимо изменить поддерживаемые типы учетных записей с помощью редактора манифестов приложений.

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

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

Разрешите приложению доступ к приложениям 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 Закрытие оповещений, отправка файлов обнаружения и создание скриптов блоков	Список оповещений, получение, отметка как чтение или непрочитанное, закрытие Отчеты списка обнаружения, категории отчетов списка Отправка файла обнаружения, создание скрипта блокировки
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 для облака

Выберите 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

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