使用用户上下文访问 Microsoft Defender for Cloud Apps API

项目
01/23/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 应用程序
使用此应用程序，获取访问令牌
使用令牌访问 Defender for Cloud Apps API

本页介绍如何创建 Microsoft Entra 应用程序、获取 Microsoft Defender for Cloud Apps 的访问令牌以及验证令牌。

注意

代表用户访问 Microsoft Defender for Cloud Apps API 时，需要正确的应用程序权限和用户权限。如果不熟悉 Microsoft Defender for Cloud Apps 上的用户权限，请参阅管理管理员访问权限。

提示

如果有权在门户中执行操作，则也有权在 API 中执行操作。

创建应用

使用具有“全局管理员”角色的使用者帐户，登录 Azure。
导航到 "Microsoft Entra ID" >“应用注册”>“新建注册”。

“注册应用程序”页出现后，请输入应用程序的注册信息：

名称：输入一个会显示给应用用户的有意义的应用程序名称。

支持的帐户类型 - 选择希望应用程序支持的帐户。

支持的科目类型	说明
仅此组织目录中的帐户	若要生成业务线 (LOB) 应用程序，请选择此选项。如果不在目录中注册应用程序，则此选项不可用。此选项映射到仅限 Microsoft Entra 的单租户。这是默认选项，除非你是在目录外部注册应用。如果在目录外部注册应用，则默认设置为 Microsoft Entra 多租户和个人 Microsoft 帐户。
任何组织目录中的帐户	若要面向所有企业和教育客户，请选择此选项。此选项映射到仅限 Microsoft Entra 的多租户。如果已将应用注册为仅限 Microsoft Entra 的单租户，则可通过“身份验证”窗格将其更新为 Microsoft Entra 多租户，以及从多租户更新为单租户。
任何组织目录中的帐户和个人 Microsoft 帐户	选择此选项可定位最广泛一组的客户。此选项将映射到 Microsoft Entra 多租户和个人 Microsoft 帐户。如果已将应用注册为 Microsoft Entra 多租户和个人 Microsoft 帐户，则不能在 UI 中进行更改。而是必须使用应用程序清单编辑器来更改支持的帐户类型。

重定向 URI (可选) - 选择要生成的应用的类型：“Web”或“公共客户端(移动和桌面)”，然后输入应用程序的重定向 URI (或回复 URL)。
- 对于 Web 应用程序，请提供应用的基 URL。例如， http://localhost:31544 可以是本地计算机上运行的 Web 应用的 URL。用户将使用此 URL 登录到 Web 客户端应用程序。
- 对于公共客户端应用程序，请提供 Microsoft Entra ID 返回令牌响应时所用的 URI。输入特定于应用程序的值，例如 myapp://auth。
若要查看 Web 应用程序或本机应用程序的具体示例，请参阅快速入门。

完成后，选择“注册”。

允许应用程序访问 Microsoft Defender for Cloud Apps，并为其分配“读取警报”权限：
- 在应用程序页面上，选择“API 权限”>“添加权限”>“我的组织使用的 API”>，键入 "Microsoft Cloud App Security"，然后选择 "Microsoft Cloud App Security"。
- 注意："Microsoft Cloud App Security" 不会显示在原始列表中。开始在文本框中写入其名称，直到看到其显示。请确保键入此名称，即使产品现在称为 Defender for Cloud Apps。
- 选择“委派权限”>"Investigation.Read">选择“添加权限”
- 重要说明：选择相关权限。 "Investigation.Read" 只是一个示例。有关其他权限范围，请参阅支持的权限范围
  - 若要确定所需的权限，请查看要调用的 API 中的“权限”部分。
- 选择“授予管理员许可”
  
  注意：每次添加权限时，都必须选择“授予管理员同意”，才能使新权限生效。
记下应用程序 ID 和租户 ID：
- 在应用程序页面上，转到“概述”并复制以下信息：

支持的权限范围

权限名称	说明	支持的操作
Investigation.read	针对除关闭警报之外的活动和警报，执行所有受支持的操作。查看 IP 范围，但不添加、更新或删除。执行所有实体操作。	活动列表、提取、反馈警报列表、提取、标记为读取/未读实体列表、提取、提取树子网列表
Investigation.manage	除了管理警报和 IP 范围之外，还要执行所有 investigation.read 操作。	活动列表、提取、反馈警报列表、提取、标记为读取/未读、关闭实体列表、提取、提取树子网列表、创建/更新/删除
Discovery.read	针对除关闭警报之外的活动和警报，执行所有受支持的操作。列出发现报告和类别。	警报列表、提取、标记为读取/未读发现列表报表、列出报表类别
Discovery.manage	Discovery.read 权限关闭警报、上传发现文件并生成阻止脚本	警报列表、提取、标记为读取/未读、关闭发现列表报表、列出报表类别发现文件上传、生成阻止脚本
Settings.read	列出 IP 范围。	子网列表
Settings.manage	列出和管理 IP 范围。	子网列表、创建/更新/删除

获取访问令牌

有关 Microsoft Entra 令牌的详细信息，请参阅 Microsoft Entra 教程。

使用 C#

在应用程序中复制/粘贴以下类。

搭配使用 AcquireUserTokenAsync 方法与应用程序 ID、租户 ID、用户名和密码，以获取令牌。

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" 声明
在下面的屏幕截图中，可以看到在本教程中从应用获取的解码令牌：

使用令牌访问 Microsoft Defender for Cloud Apps API

选择想要使用的 API。有关详细信息，请参阅 Defender for Cloud Apps API。
在发送到 "Bearer {token}" 的 HTTP 请求中设置授权标头（持有者是授权方案）
令牌的过期时间为 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

Share via