创建应用以在没有用户的情况下访问Microsoft Defender XDR
适用于:
- Microsoft Defender XDR
重要
某些信息与预发布的产品有关,在商业发布之前可能有重大修改。 Microsoft 对此处所提供的信息不作任何明示或默示的保证。
本页介绍如何创建应用程序,以便在没有定义用户的情况下以编程方式访问Microsoft Defender XDR,例如,如果要创建守护程序或后台服务。
如果需要代表一个或多个用户以编程方式访问Microsoft Defender XDR,请参阅创建代表用户访问Microsoft Defender XDR API 的应用和创建具有合作伙伴访问Microsoft Defender XDR API 的应用。 如果不确定需要哪种类型的访问权限,请参阅 入门。
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
- 验证令牌。
登录到 Azure。
导航到Microsoft Entra ID>应用注册>“新建注册”。
在窗体中,选择应用程序的名称,然后选择“ 注册”。
在应用程序页上,选择“API 权限>”“添加组织使用>的权限> API”,键入“Microsoft威胁防护”,然后选择“Microsoft威胁防护”。 你的应用现在可以访问Microsoft Defender XDR。
提示
Microsoft威胁防护是Microsoft Defender XDR的前名称,不会显示在原始列表中。 你需要开始在文本框中写入其名称才能看到它出现。
选择“应用程序权限”。 选择方案的相关权限 (例如 Incident.Read.All) ,然后选择“ 添加权限”。
选择“ 授予管理员同意”。 每次添加权限时,都必须选择“ 授予管理员同意 ”才能使其生效。
若要向应用程序添加机密,请选择“ 证书 & 机密”,向机密添加说明,然后选择“ 添加”。
提示
选择“ 添加”后,选择 “复制生成的机密值”。 离开后将无法检索机密值。
在安全的地方记录应用程序 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 密钥保管库管理服务器应用中的机密。
# 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
备注
以下代码已使用 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
) :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;
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 预安装在 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
权限的解码令牌:
选择要使用 (事件或高级搜寻) 的 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 Defender XDR API 概述
- 访问Microsoft Defender XDR API
- 创建“Hello世界”应用程序
- 创建代表用户访问Microsoft Defender XDR API 的应用
- 创建具有对 Microsoft Defender XDR API 的多租户合作伙伴访问权限的应用
- 了解 API 限制和许可
- 了解错误代码
- 使用 Azure 密钥保管库管理服务器应用中的机密
- 用于用户登录和 API 访问的 OAuth 2.0 授权
提示
想要了解更多信息? 请在我们的技术社区中与 Microsoft 安全社区互动:Microsoft Defender XDR 技术社区。