使用 Microsoft Defender for Endpoint API

项目
05/03/2024

适用于：

重要

高级搜寻功能不包括在 Defender for Business 中。

希望体验 Microsoft Defender for Endpoint？注册免费试用版。

注意

如果你是美国政府客户，请使用美国政府客户Microsoft Defender for Endpoint中列出的 URI。

提示

为了提高性能，可以使用离地理位置更近的服务器：

us.api.security.microsoft.com
eu.api.security.microsoft.com
uk.api.security.microsoft.com
au.api.security.microsoft.com
swa.api.security.microsoft.com

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

如果需要在没有用户的情况下进行编程访问Microsoft Defender for Endpoint，请参阅使用应用程序上下文访问Microsoft Defender for Endpoint。

如果不确定需要哪个访问权限，请阅读 “简介”页。

Microsoft Defender for Endpoint通过一组编程 API 公开其大部分数据和操作。这些 API 使你能够自动执行工作流，并根据Microsoft Defender for Endpoint功能进行创新。 API 访问需要 OAuth2.0 身份验证。有关详细信息，请参阅 OAuth 2.0 授权代码流。

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

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

本页介绍如何创建Microsoft Entra应用程序、获取访问令牌以Microsoft Defender for Endpoint并验证令牌。

注意

代表用户访问Microsoft Defender for Endpoint API 时，需要正确的应用程序权限和用户权限。如果不熟悉Microsoft Defender for Endpoint的用户权限，请参阅使用基于角色的访问控制管理门户访问权限。

提示

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

创建应用

使用具有全局管理员角色的用户帐户登录到 Azure。
导航到Microsoft Entra ID>应用注册>“新建注册”。

出现“注册应用程序”页面后，输入应用程序的注册信息：

名称 - 输入一个会显示给应用用户的有意义的应用程序名称。

支持的帐户类型 - 选择希望应用程序支持的具体帐户。

支持的帐户类型	说明
仅限此组织目录中的帐户	若要生成业务线 (LOB) 应用程序，请选择此选项。如果不在目录中注册应用程序，则此选项不可用。此选项映射到仅限Microsoft Entra单租户。这是默认选项，除非你是在目录外部注册应用。如果应用在目录外注册，则默认为Microsoft Entra多租户和个人 Microsoft 帐户。
任何组织目录中的帐户	若想要面向所有企业和教育客户，请选择此选项。此选项映射到仅限Microsoft Entra的多租户。如果将应用注册为仅限Microsoft Entra单租户，则可以将其更新为Microsoft Entra多租户，并通过“身份验证”边栏选项卡重新更新为单租户。
任何组织目录中的帐户和 Microsoft 个人帐户	若要面向最广泛的客户，请选择此选项。此选项映射到Microsoft Entra多租户和个人 Microsoft 帐户。如果将应用注册为Microsoft Entra多租户和个人 Microsoft 帐户，则无法在 UI 中更改此帐户。而只能使用应用程序清单编辑器来更改支持的帐户类型。

支持的帐户类型

说明

仅限此组织目录中的帐户

若要生成业务线 (LOB) 应用程序，请选择此选项。如果不在目录中注册应用程序，则此选项不可用。

此选项映射到仅限Microsoft Entra单租户。

这是默认选项，除非你是在目录外部注册应用。如果应用在目录外注册，则默认为Microsoft Entra多租户和个人 Microsoft 帐户。

任何组织目录中的帐户

若想要面向所有企业和教育客户，请选择此选项。

此选项映射到仅限Microsoft Entra的多租户。

如果将应用注册为仅限Microsoft Entra单租户，则可以将其更新为Microsoft Entra多租户，并通过“身份验证”边栏选项卡重新更新为单租户。

任何组织目录中的帐户和 Microsoft 个人帐户

若要面向最广泛的客户，请选择此选项。

此选项映射到Microsoft Entra多租户和个人 Microsoft 帐户。

如果将应用注册为Microsoft Entra多租户和个人 Microsoft 帐户，则无法在 UI 中更改此帐户。而只能使用应用程序清单编辑器来更改支持的帐户类型。

重定向 URI（可选） - 选择要生成的应用的类型：“Web”或“公共客户端(移动和桌面)”，然后输入应用程序的重定向 URI（或回复 URL）。
- 对于 Web 应用程序，请提供应用的基 URL。例如，http://localhost:31544 可以是本地计算机上运行的 Web 应用的 URL。用户将使用此 URL 登录到 Web 客户端应用程序。
- 对于公共客户端应用程序，请提供Microsoft Entra ID用于返回令牌响应的 URI。输入特定于应用程序的值，例如 myapp://auth。
若要查看 Web 应用程序或本机应用程序的特定示例，请参阅快速入门。

完成后，选择“注册”。

允许应用程序访问Microsoft Defender for Endpoint并为其分配“读取警报”权限：
- 在应用程序页上，选择“ API 权限>添加权限>API 我的组织使用>WindowsDefenderATP ”类型，然后在 WindowsDefenderATP 上选择。
  
  注意
  
  WindowsDefenderATP 不显示在原始列表中。开始在文本框中写入其名称以查看其显示。
- 选择 “委托的权限>警报”。Read> 选择“ 添加权限”。
重要

选择相关权限。读取警报只是一个示例。

例如：
- 若要运行高级查询，请选择“ 运行高级查询 权限”。
- 若要隔离设备，请选择“ 隔离计算机 权限”。
- 若要确定所需的权限，请查看要调用的 API 中的 “权限” 部分。
- 选择“ 授予同意”。
  
  注意
  
  每次添加权限时，都必须选择“ 授予同意 ”，使新权限生效。
记下应用程序 ID 和租户 ID。

在应用程序页上，转到 “概述” 并复制以下信息：

获取访问令牌

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

使用 C#

在应用程序中复制/粘贴以下类。

将 AcquireUserTokenAsync 方法与应用程序 ID、租户 ID、用户名和密码结合使用来获取令牌。

namespace WindowsDefenderATP
{
    using System.Net.Http;
    using System.Text;
    using System.Threading.Tasks;
    using Newtonsoft.Json.Linq;

    public static class WindowsDefenderATPUtils
    {
        private const string Authority = "https://login.microsoftonline.com";

        private const string WdatpResourceId = "https://api.securitycenter.microsoft.com";

        public static async Task<string> AcquireUserTokenAsync(string username, string password, string appId, string tenantId)
        {
            using (var httpClient = new HttpClient())
            {
                var urlEncodedBody = $"resource={WdatpResourceId}&client_id={appId}&grant_type=password&username={username}&password={password}";

                var stringContent = new StringContent(urlEncodedBody, Encoding.UTF8, "application/x-www-form-urlencoded");

                using (var response = await httpClient.PostAsync($"{Authority}/{tenantId}/oauth2/token", stringContent).ConfigureAwait(false))
                {
                    response.EnsureSuccessStatusCode();

                    var json = await response.Content.ReadAsStringAsync().ConfigureAwait(false);

                    var jObject = JObject.Parse(json);

                    return jObject["access_token"].Value<string>();
                }
            }
        }
    }
}

验证令牌

验证以确保获得正确的令牌：

将上一步中获取的令牌复制/粘贴到 JWT 中，以便对其进行解码。
验证是否获得具有所需应用权限的“scp”声明。
在下面的屏幕截图中，可以看到在教程中从应用获取的解码令牌：

使用令牌访问Microsoft Defender for Endpoint API

选择要使用的 API - 支持的Microsoft Defender for Endpoint API。
在发送到“持有者 {token}”的 HTTP 请求中设置授权标头， (持有者是授权方案) 。
令牌的过期时间为 1 小时， (可以发送多个具有相同令牌的请求) 。

使用 C# 发送请求以获取警报列表的示例：

var httpClient = new HttpClient();

var request = new HttpRequestMessage(HttpMethod.Get, "https://api.securitycenter.microsoft.com/api/alerts");

request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);

var response = httpClient.SendAsync(request).GetAwaiter().GetResult();

// Do something useful with the response

另请参阅

提示

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