使用应用程序上下文访问 Microsoft Defender for Cloud Apps

项目
01/23/2024

本页介绍如何创建应用程序，以在没有用户的情况下以编程方式访问 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 应用程序。
使用此应用程序，获取访问令牌。
使用令牌访问 Defender for Cloud Apps API。

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

创建应用

使用具有“全局管理员”角色的使用者登录 Azure。
导航到 "Microsoft Entra ID" >“应用注册”>“新建注册”。
在注册表单中，选择应用程序的名称，然后选择“注册”。
若要使应用能够访问 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。在应用程序页面上，转到“概述”，复制“应用程序(客户端) ID”和“目录(租户) ID”。
仅适用于 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
```
其中，00000000-0000-0000-0000-000000000000 替换为应用程序 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 教程。

使用 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 进行测试。

创建一个新的控制台应用程序。
安装 NuGet Microsoft.Identity.Client。
添加以下内容：
```
using Microsoft.Identity.Client;
```

在应用中复制并粘贴以下代码（不要忘记更新三个变量：tenantId, appId, appSecret）：

string tenantId = "00000000-0000-0000-0000-000000000000"; // Paste your own tenant ID here
string appId = "11111111-1111-1111-1111-111111111111"; // 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

请参阅适用于 Python 的 Microsoft 身份验证库 (MSAL)。

使用 Curl

注意

以下过程假设计算机上已安装 Curl for Windows。

打开命令提示符，并将 CLIENT_ID 设置为 Azure 应用程序 ID。
将 CLIENT_SECRET 设置为 Azure 应用程序机密。
将 TENANT_ID 设置为想要使用应用访问 Defender for Cloud Apps 的客户 Azure 租户 ID。
运行以下命令：

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"}

验证令牌

确保获得正确的令牌：

将你在上一步骤中获取的令牌复制并粘贴到 JWT，以便对其进行解码。
验证是否获得具有所需权限的“角色”声明
在下图中，可以看到从具有所有 Microsoft Defender for Cloud Apps 角色权限的应用获取的解码令牌：

Image of token validation.

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

选择想要使用的 API。有关详细信息，请参阅 Defender for Cloud Apps APIs。
在发送到 "Bearer {token}" 的 HTTP 请求中设置授权标头（持有者是授权方案）。
令牌的过期时间是一个小时。可以使用同一令牌发送多个请求。

以下是使用 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

另请参阅

管理 API 令牌

Share via