创建具有Microsoft Defender XDR API 的合作伙伴访问权限的应用

项目
11/19/2024

适用于：

Microsoft Defender XDR

重要

某些信息与预发布的产品有关，在商业发布之前可能有重大修改。 Microsoft 对此处所提供的信息不作任何明示或默示的保证。

本页介绍如何代表跨多个租户的用户创建对Microsoft Defender XDR具有编程访问权限的Microsoft Entra应用。多租户应用可用于为大型用户组提供服务。

如果需要代表单个用户以编程方式访问Microsoft Defender XDR，请参阅创建应用以代表用户访问Microsoft Defender XDR API。如果需要在没有用户显式定义的访问 (例如，如果要编写后台应用或守护程序) ，请参阅创建应用以在没有用户的情况下访问Microsoft Defender XDR。如果不确定需要哪种类型的访问权限，请参阅入门。

Microsoft Defender XDR通过一组编程 API 公开其大部分数据和操作。这些 API 可帮助你自动执行工作流并利用Microsoft Defender XDR的功能。此 API 访问需要 OAuth2.0 身份验证。有关详细信息，请参阅 OAuth 2.0 授权代码流。

通常，需要执行以下步骤才能使用这些 API：

创建Microsoft Entra应用程序。
使用此应用程序获取访问令牌。
使用令牌访问Microsoft Defender XDR API。

由于此应用是多租户的，因此还需要代表其用户从每个租户获得管理员同意。

本文介绍如何：

创建多租户Microsoft Entra应用程序
获取用户管理员的授权许可，允许应用程序访问其所需的资源Microsoft Defender XDR。
获取访问令牌以Microsoft Defender XDR
验证令牌

Microsoft Defender XDR通过一组编程 API 公开其大部分数据和操作。这些 API 将帮助你自动执行工作流，并根据Microsoft Defender XDR功能进行创新。 API 访问需要 OAuth2.0 身份验证。有关详细信息，请参阅 OAuth 2.0 授权代码流。

通常，需要执行以下步骤才能使用 API：

创建多租户Microsoft Entra应用程序。
获取授权 (用户管理员) 同意应用程序访问其所需的Microsoft Defender XDR资源。
使用此应用程序获取访问令牌。
使用令牌访问Microsoft Defender XDR API。

以下步骤指导如何创建多租户Microsoft Entra应用程序、获取访问令牌以Microsoft Defender XDR并验证令牌。

创建多租户应用

登录到 Azure。
导航到Microsoft Entra ID>应用注册>“新建注册”。
在注册表单中：
- 为应用程序选择一个名称。
- 从“支持的帐户类型”中，选择“任何组织目录中的帐户” (“任何Microsoft Entra目录) - 多租户”。
- 填写 “重定向 URI ”部分。选择类型 “Web ”，并将重定向 URI 指定为 https://portal.azure.com。
填写完表单后，选择“ 注册”。
在应用程序页上，选择“API 权限>”“添加组织使用>的权限> API”，键入“Microsoft威胁防护”，然后选择“Microsoft威胁防护”。你的应用现在可以访问Microsoft Defender XDR。

提示

Microsoft威胁防护是Microsoft Defender XDR的前名称，不会显示在原始列表中。你需要开始在文本框中写入其名称才能看到它出现。
选择“应用程序权限”。选择方案的相关权限 (例如 Incident.Read.All) ，然后选择“ 添加权限”。

注意

需要为方案选择相关权限。 读取所有事件 只是一个示例。若要确定所需的权限，请查看要调用的 API 中的 “权限” 部分。

例如，若要运行高级查询，请选择“运行高级查询”权限;若要隔离设备，请选择“隔离计算机”权限。
选择“ 授予管理员同意”。每次添加权限时，都必须选择“ 授予管理员同意 ”才能使其生效。
若要向应用程序添加机密，请选择“ 证书 & 机密”，向机密添加说明，然后选择“ 添加”。

提示

选择“ 添加”后，选择 “复制生成的机密值”。离开后将无法检索机密值。
在安全的地方记录应用程序 ID 和租户 ID。它们在应用程序页的 “概述 ”下列出。
将应用程序添加到用户的租户。

由于应用程序代表用户与Microsoft Defender XDR交互，因此需要针对你打算使用它的每个租户获得批准。

用户租户中的管理员需要查看同意链接并批准应用程序。

同意链接的格式如下：
```
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。

单击同意链接后，以用户租户的管理员身份登录，并授予对应用程序的同意。

你还需要要求用户提供其租户 ID。租户 ID 是用于获取访问令牌的标识符之一。

完成！ 已成功注册应用程序！
有关令牌获取和验证，请参阅以下示例。

获取访问令牌

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

重要

尽管本部分中的示例鼓励你粘贴机密值以进行测试，但 绝不能将机密硬编码 到生产中运行的应用程序中。第三方可以使用你的机密来访问资源。可以使用 Azure 密钥保管库帮助保护应用的机密安全。有关如何保护应用的实用示例，请参阅使用 Azure 密钥保管库管理服务器应用中的机密。

提示

在以下示例中，使用用户的租户 ID 测试脚本是否正常工作。

使用 PowerShell 获取访问令牌

# This code gets the application context token and saves it to a file named "Latest-token.txt" under the current directory.

$tenantId = '' # Paste your directory (tenant) ID here
$clientId = '' # Paste your application (client) ID here
$appSecret = '' # Paste your own app secret here to test, then store it in a safe place!

$resourceAppIdUri = 'https://api.security.microsoft.com'
$oAuthUri = "https://login.windows.net/$tenantId/oauth2/token"

$authBody = [Ordered] @{
    resource = $resourceAppIdUri
    client_id = $clientId
    client_secret = $appSecret
    grant_type = 'client_credentials'
}

$authResponse = Invoke-RestMethod -Method Post -Uri $oAuthUri -Body $authBody -ErrorAction Stop
$token = $authResponse.access_token

Out-File -FilePath "./Latest-token.txt" -InputObject $token

return $token

使用 C 获取访问令牌#

注意

以下代码已使用 Nuget Microsoft.Identity.Client 3.19.8 进行测试。

重要

Microsoft.IdentityModel.Clients.ActiveDirectory NuGet 包和Azure AD 身份验证库 (ADAL) 已弃用。自 2020 年 6 月 30 日以来，未添加任何新功能。强烈建议升级，请参阅迁移指南了解更多详细信息。

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

将以下代码复制并粘贴到应用中， (不要忘记更新三个变量： tenantId、 clientId、 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 = https://api.securitycenter.microsoft.com;

IConfidentialClientApplication myApp = ConfidentialClientApplicationBuilder.Create(appId).WithClientSecret(appSecret).WithAuthority($"{authority}/{tenantId}").Build();

List<string> scopes = new List<string>() { $"{audience}/.default" };

AuthenticationResult authResult = myApp.AcquireTokenForClient(scopes).ExecuteAsync().GetAwaiter().GetResult();

string token = authResult.AccessToken;

使用 Python 获取访问令牌

import json
import urllib.request
import urllib.parse

tenantId = '' # Paste your directory (tenant) ID here
clientId = '' # Paste your application (client) ID here
appSecret = '' # Paste your own app secret here to test, then store it in a safe place, such as the Azure Key Vault!

url = "https://login.windows.net/%s/oauth2/token" % (tenantId)

resourceAppIdUri = 'https://api.security.microsoft.com'

body = {
    'resource' : resourceAppIdUri,
    'client_id' : clientId,
    'client_secret' : appSecret,
    'grant_type' : 'client_credentials'
}

data = urllib.parse.urlencode(body).encode("utf-8")

req = urllib.request.Request(url, data)
response = urllib.request.urlopen(req)
jsonResponse = json.loads(response.read())
aadToken = jsonResponse["access_token"]

使用 curl 获取访问令牌

注意

Curl 预安装在 Windows 10 版本 1803 及更高版本上。对于其他版本的 Windows，请直接从官方 curl 网站下载并安装该工具。

打开命令提示符，并将CLIENT_ID设置为 Azure 应用程序 ID。
将CLIENT_SECRET设置为 Azure 应用程序机密。
将TENANT_ID设置为想要使用应用访问Microsoft Defender XDR的用户的 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=https://securitycenter.onmicrosoft.com/windowsatpservice/.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"}

验证令牌

将令牌复制并粘贴到 JSON Web 令牌验证程序网站 JWT 以对其进行解码。
请确保解码令牌中 的角色 声明包含所需的权限。

在下图中，可以看到从应用 Incidents.Read.All获取的具有、 Incidents.ReadWrite.All和 AdvancedHunting.Read.All 权限的解码令牌：

使用令牌访问Microsoft Defender XDR API

选择要使用 (事件或高级搜寻) 的 API。有关详细信息，请参阅支持的Microsoft Defender XDR API。
在要发送的 http 请求中，将授权标头设置为 "Bearer" <token>，将 持有者 设置为授权方案，将令牌设置为验证令牌。
令牌将在一小时内过期。在此期间，可以使用同一令牌发送多个请求。

以下示例演示如何 使用 C# 发送请求以获取事件列表。

   var httpClient = new HttpClient();
   var request = new HttpRequestMessage(HttpMethod.Get, "https://api.security.microsoft.com/api/incidents");

   request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);

   var response = httpClient.SendAsync(request).GetAwaiter().GetResult();

提示

想要了解更多信息？请在我们的技术社区中与 Microsoft 安全社区互动：Microsoft Defender XDR 技术社区。

通过

创建具有Microsoft Defender XDR API 的合作伙伴访问权限的应用

创建多租户应用

获取访问令牌

使用 PowerShell 获取访问令牌

使用 C 获取访问令牌#

使用 Python 获取访问令牌

使用 curl 获取访问令牌

验证令牌

使用令牌访问Microsoft Defender XDR API

反馈

其他资源

通过

创建具有Microsoft Defender XDR API 的合作伙伴访问权限的应用

创建多租户应用

获取访问令牌

使用 PowerShell 获取访问令牌

使用 C 获取访问令牌#

使用 Python 获取访问令牌

使用 curl 获取访问令牌

验证令牌

使用令牌访问Microsoft Defender XDR API

相关文章

反馈

其他资源