Create应用以代表用户访问Microsoft Defender XDR API
适用于:
- Microsoft Defender XDR
重要
某些信息与预发布的产品有关,在商业发布之前可能有重大修改。 Microsoft 对此处所提供的信息不作任何明示或默示的保证。
本页介绍如何创建应用程序,以便代表单个用户以编程方式访问Microsoft Defender XDR。
如果需要在没有定义用户 (的情况下以编程方式访问Microsoft Defender XDR,例如,如果要编写后台应用或守护程序) ,请参阅Create应用以在没有用户的情况下访问Microsoft Defender XDR。 如果需要为多个租户提供访问权限(例如,如果你为大型组织或一组客户提供服务),请参阅Create具有对Microsoft Defender XDR API 的合作伙伴访问权限的应用。如果不确定需要哪种类型的访问权限,请参阅入门。
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
- 验证令牌
注意
代表用户访问Microsoft Defender XDR API 时,需要正确的应用程序权限和用户权限。
提示
如果有权在门户中执行操作,则有权在 API 中执行操作。
创建应用
以具有全局管理员角色的用户身份登录到 Azure。
导航到Microsoft Entra ID>应用注册>“新建注册”。
在窗体中,为应用程序选择一个名称,并为重定向 URI 输入以下信息,然后选择“ 注册”。
- 应用程序类型: 公共客户端
- 重定向 URI:https://portal.azure.com
在应用程序页上,选择“API 权限>”“添加我组织使用>的权限> API”,键入“Microsoft 威胁防护”,然后选择“Microsoft 威胁防护”。 你的应用现在可以访问Microsoft Defender XDR。
提示
Microsoft 威胁防护是Microsoft Defender XDR的前名称,不会显示在原始列表中。 你需要开始在文本框中写入其名称才能看到它出现。
选择“ 授予管理员同意”。 每次添加权限时,都必须选择“ 授予管理员同意 ”才能使其生效。
在安全的地方记录应用程序 ID 和租户 ID。 它们在应用程序页的 “概述 ”下列出。
获取访问令牌
有关Microsoft Entra令牌的详细信息,请参阅Microsoft Entra教程。
使用 PowerShell 代表用户获取访问令牌
使用 MSAL.PS 库获取具有委派权限的访问令牌。 运行以下命令以代表用户获取访问令牌:
Install-Module -Name MSAL.PS # Install the MSAL.PS module from PowerShell Gallery
$TenantId = " " # Paste your directory (tenant) ID here.
$AppClientId="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" # Paste your application (client) ID here.
$MsalParams = @{
ClientId = $AppClientId
TenantId = $TenantId
Scopes = 'https://graph.microsoft.com/User.Read.All','https://graph.microsoft.com/Files.ReadWrite','https://api.securitycenter.windows.com/AdvancedQuery.Read'
}
$MsalResponse = Get-MsalToken @MsalParams
$AccessToken = $MsalResponse.AccessToken
$AccessToken # Display the token in PS console
验证令牌
- 将令牌复制并粘贴到 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 Defender XDR API 概述
- 访问Microsoft Defender XDR API
- Create“Hello世界”应用
- Create应用以在没有用户的情况下访问Microsoft Defender XDR
- Create具有多租户合作伙伴访问Microsoft Defender XDR API 的应用
- 了解 API 限制和许可
- 了解错误代码
- 用于用户登录和 API 访问的 OAuth 2.0 授权
提示
想要了解更多信息? Engage技术社区中的 Microsoft 安全社区:Microsoft Defender XDR技术社区。
反馈
https://aka.ms/ContentUserFeedback。
即将发布:在整个 2024 年,我们将逐步淘汰作为内容反馈机制的“GitHub 问题”,并将其取代为新的反馈系统。 有关详细信息,请参阅:提交和查看相关反馈