通过

创建代表用户访问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 中执行操作。 有关角色和权限的详细信息，请参阅使用Microsoft Entra全局角色管理对Microsoft Defender XDR的访问权限。

创建应用

  1. 登录到 Azure。

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

    Azure 门户的“管理”窗格中的“新建注册”选项

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

    Azure 门户中的应用程序注册窗格

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

    提示

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

    Microsoft Defender门户中组织的 API 窗格

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

      Microsoft Defender门户中的“委派权限”窗格

    注意

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

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

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

    Microsoft Defender门户中的管理员同意授予窗格

  6. 在安全的地方记录应用程序 ID 和租户 ID。 它们在应用程序页的 “概述 ”下列出。

    Microsoft Defender门户中的“概述”窗格

获取访问令牌

有关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门户中“解码的令牌”窗格中的权限部分

使用令牌访问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 安全社区互动：Microsoft Defender XDR 技术社区。