创建应用以代表用户访问Microsoft Defender XDR API

适用于：

• Microsoft Defender XDR

重要

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

本页介绍如何创建应用程序，以便代表单个用户以编程方式访问 Microsoft Defender XDR。

如果需要在没有定义用户 (的情况下以编程方式访问 Microsoft Defender XDR，例如，如果要编写后台应用或守护程序) ，请参阅 创建应用以在没有用户的情况下访问 Microsoft Defender XDR。 如果需要为多个租户提供访问权限（例如，如果你为大型组织或一组客户提供服务），请参阅 创建具有合作伙伴访问权限的应用，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 的访问令牌
• 验证令牌

注意

代表用户访问 Microsoft Defender XDR API 时，需要正确的应用程序权限和用户权限。

提示

如果有权在门户中执行操作，则有权在 API 中执行操作。

创建应用

1. 以具有全局管理员角色的用户身份登录到 Azure。

2. 导航到 Microsoft Entra ID>应用注册>新注册。

   

3. 在窗体中，为应用程序选择一个名称，并为重定向 URI 输入以下信息，然后选择“ 注册”。

   

   • 应用程序类型： 公共客户端
   • 重定向 URI：https://portal.azure.com

4. 在应用程序页上，选择“API 权限>”“添加组织使用>的权限> API”，键入“Microsoft威胁防护”，然后选择“Microsoft威胁防护”。 你的应用现在可以访问 Microsoft Defender XDR。

   提示

   Microsoft威胁防护 是 Microsoft Defender XDR 的前名称，不会显示在原始列表中。 你需要开始在文本框中写入其名称才能看到它出现。

   

   • 选择 “委托的权限”。 选择方案的相关权限 (例如 Incident.Read) ，然后选择“ 添加权限”。

     

   注意

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

   例如，若要 运行高级查询，请选择“运行高级查询”权限;若要 隔离设备，请选择“隔离计算机”权限。

5. 选择“ 授予管理员同意”。 每次添加权限时，都必须选择“ 授予管理员同意 ”才能使其生效。

   

6. 在安全的地方记录应用程序 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

验证令牌

1. 将令牌复制并粘贴到 JWT 中以对其进行解码。
2. 请确保解码令牌中 的角色 声明包含所需的权限。

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

使用令牌访问 Microsoft Defender XDR API

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

以下示例演示如何 使用 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 world”应用
• 创建无需用户即可访问 Microsoft Defender XDR 的应用
• 创建对 Microsoft Defender XDR API 具有多租户合作伙伴访问权限的应用
• 了解 API 限制和许可
• 了解错误代码
• 用于用户登录和 API 访问的 OAuth 2.0 授权

提示

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