Create应用以在没有用户的情况下访问Microsoft Defender XDR

项目
04/28/2024

适用于：

Microsoft Defender XDR

重要

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

本页介绍如何创建应用程序，以便在没有定义用户的情况下以编程方式访问Microsoft Defender XDR，例如，如果要创建守护程序或后台服务。

如果需要代表一个或多个用户以编程方式访问Microsoft Defender XDR，请参阅Create应用以代表用户访问Microsoft Defender XDR API，并Create具有合作伙伴访问权限的应用Microsoft Defender XDRAPI。如果不确定需要哪种类型的访问权限，请参阅入门。

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

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

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

本文介绍如何：

Create Microsoft Entra应用程序
获取访问令牌以Microsoft Defender XDR
验证令牌。

创建应用

以具有全局管理员角色的用户身份登录到 Azure。
导航到Microsoft Entra ID>应用注册>“新建注册”。
在窗体中，选择应用程序的名称，然后选择“ 注册”。
在应用程序页上，选择“API 权限>”“添加我组织使用>的权限> API”，键入“Microsoft 威胁防护”，然后选择“Microsoft 威胁防护”。你的应用现在可以访问Microsoft Defender XDR。

提示

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

注意

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

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

提示

选择“ 添加”后，选择 “复制生成的机密值”。离开后将无法检索机密值。
在安全的地方记录应用程序 ID 和租户 ID。它们在应用程序页的 “概述 ”下列出。
仅适用于Microsoft Defender XDR合作伙伴：按照这些说明通过Microsoft Defender XDR API 访问合作伙伴，将应用设置为多租户，以便在收到管理员同意后，它可在所有租户中使用。第三方应用需要合作伙伴访问权限，例如，如果你创建的应用打算在多个客户的租户中运行。如果创建仅在租户中运行的服务（例如用于自己使用的应用程序，仅与自己的数据交互）， 则不需要 它。若要将应用设置为多租户，请执行以下操作：
- 转到 “身份验证”，并添加 https://portal.azure.com 为 “重定向 URI”。
- 在页面底部的 “支持的帐户类型”下，选择多租户应用 的任何组织目录应用程序许可中的帐户 。
由于应用程序代表用户与Microsoft Defender XDR交互，因此需要针对你打算使用它的每个租户获得批准。

每个租户的 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。

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

获取访问令牌

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

重要

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

使用 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, such as the Azure Key Vault!

$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 日以来，未添加任何新功能。强烈建议升级，请参阅迁移指南了解更多详细信息。

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

将以下代码复制并粘贴到应用中， (不要忘记更新三个变量： tenantId、 clientId、 appSecret) ：

csharp
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://api.security.microsoft.com/.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();

提示

想要了解更多信息？ Engage技术社区中的 Microsoft 安全社区：Microsoft Defender XDR技术社区。

Share via

Create应用以在没有用户的情况下访问Microsoft Defender XDR

创建应用

获取访问令牌

使用 PowerShell 获取访问令牌

使用 C 获取访问令牌#

使用 Python 获取访问令牌

使用 curl 获取访问令牌

验证令牌

使用令牌访问Microsoft Defender XDR API

反馈

反馈

其他资源

Share via

Create应用以在没有用户的情况下访问Microsoft Defender XDR

创建应用

获取访问令牌

使用 PowerShell 获取访问令牌

使用 C 获取访问令牌#

使用 Python 获取访问令牌

使用 curl 获取访问令牌

验证令牌

使用令牌访问Microsoft Defender XDR API

相关文章

反馈

反馈

其他资源