创建应用以在没有用户的情况下访问Microsoft Defender for Endpoint

适用于:

重要

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

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

注意

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

提示

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

  • api-us.securitycenter.microsoft.com
  • api-eu.securitycenter.microsoft.com
  • api-uk.securitycenter.microsoft.com
  • api-au.securitycenter.microsoft.com

本页介绍如何创建一个应用程序,以便在没有用户的情况下以编程方式访问 Defender for Endpoint。 如果需要代表用户以编程方式访问 Defender for Endpoint,请参阅 使用用户上下文获取访问权限。 如果不确定需要哪种访问权限,请参阅 入门

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

通常,需要执行以下步骤才能使用 API:

  • 创建Microsoft Entra应用程序。
  • 使用此应用程序获取访问令牌。
  • 使用令牌访问 Defender for Endpoint API。

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

创建应用

  1. 使用具有全局管理员角色的用户登录到 Azure

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

    应用程序注册窗格

  3. 在注册表单中,选择应用程序的名称,然后选择“ 注册”。

  4. 若要使应用能够访问 Defender for Endpoint 并为其分配“读取所有警报”权限,请在应用程序页上选择“API 权限>”“添加我的组织使用>的权限> API”,键入“WindowsDefenderATP”,然后选择“WindowsDefenderATP”。

    注意

    WindowsDefenderATP 不显示在原始列表中。 开始在文本框中写入其名称以查看其显示。

    “API 权限”窗格

    选择“ 应用程序权限>警报.Read.All”,然后选择“ 添加权限”。

    应用程序权限信息窗格

    需要选择相关权限。 “读取所有警报”只是一个示例。 例如:

    • 若要 运行高级查询,请选择“运行高级查询”权限。
    • 若要 隔离设备,请选择“隔离计算机”权限。
    • 若要确定所需的权限,请查看要调用的 API 中的 “权限” 部分。
  5. 选择“ 授予同意”。

    注意

    每次添加权限时,都必须选择“ 授予同意 ”,使新权限生效。

    “授予权限”页

  6. 若要向应用程序添加机密,请选择“ 证书 & 机密”,向机密添加说明,然后选择“ 添加”。

    注意

    选择“ 添加”后,选择 “复制生成的机密值”。 离开后将无法检索此值。

    “创建应用程序”选项

  7. 记下应用程序 ID 和租户 ID。 在应用程序页上,转到 “概述” 并复制以下内容。

    创建的应用和租户 ID

  8. 仅适用于Microsoft Defender for Endpoint合作伙伴。 在同意) 后,将应用设置为多租户 (在所有租户中可用。 例如,如果创建一个应用打算在多个客户的租户) 中运行,则第三方应用需要此 (。 如果创建的服务仅在 (租户中运行,则 不需要 执行此操作,例如,创建一个应用程序供自己使用,该应用程序将仅与自己的数据) 交互。 若要将应用设置为多租户,请执行以下操作:

    • 转到 “身份验证”,并添加 https://portal.azure.com“重定向 URI”。

    • 在页面底部的 “支持的帐户类型”下,选择多租户应用 的任何组织目录应用程序许可中的帐户

    你需要在打算使用它的每个租户中批准应用程序。 这是因为应用程序代表客户与 Defender for Endpoint 交互。

    如果你正在编写第三方应用, (或你的客户) 需要选择同意链接并批准你的应用。 应与在 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-0000000000000 替换为应用程序 ID。

完成! 已成功注册应用程序! 有关令牌获取和验证,请参阅以下示例。

获取访问令牌

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

使用 PowerShell

# This script acquires the App Context Token and stores it in the variable $token for later use in the script.
# Paste your Tenant ID, App ID, and App Secret (App key) into the indicated quotes below.

$tenantId = '' ### Paste your tenant ID here
$appId = '' ### Paste your Application ID here
$appSecret = '' ### Paste your Application key here

$sourceAppIdUri = 'https://api.securitycenter.microsoft.com/.default'
$oAuthUri = "https://login.microsoftonline.com/$TenantId/oauth2/v2.0/token"
$authBody = [Ordered] @{
    scope = "$sourceAppIdUri"
    client_id = "$appId"
    client_secret = "$appSecret"
    grant_type = 'client_credentials'
}
$authResponse = Invoke-RestMethod -Method Post -Uri $oAuthUri -Body $authBody -ErrorAction Stop
$token = $authResponse.access_token
$token

使用 C#:

以下代码已使用 NuGet Microsoft.Identity.Client 3.19.8 进行了测试。

重要

Microsoft.IdentityModel.Clients.ActiveDirectory NuGet 包和 Azure AD 身份验证 库 (ADAL) 已弃用。 自 2020 年 6 月 30 日以来,未添加任何新功能。 强烈建议升级,请参阅 迁移指南 了解更多详细信息。

  1. 创建新的控制台应用程序。

  2. 安装 NuGet Microsoft.Identity.Client

  3. 将以下内容:

    using Microsoft.Identity.Client;
    
  4. 将以下代码复制并粘贴到应用中 (不要忘记更新三个变量: tenantId, appId, appSecret) :

    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;
    

使用 Python

请参阅 使用 Python 获取令牌

使用 Curl

注意

以下过程假定计算机上已安装 Curl for Windows。

  1. 打开命令提示符,并将CLIENT_ID设置为 Azure 应用程序 ID。

  2. 将CLIENT_SECRET设置为 Azure 应用程序机密。

  3. 将TENANT_ID设置为想要使用应用访问 Defender for Endpoint 的客户 Azure 租户 ID。

  4. 运行以下命令:

    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://securitycenter.onmicrosoft.com/windowsatpservice/.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"}
    

验证令牌

确保获得正确的令牌:

  1. 将上一步获取的令牌复制并粘贴到 JWT 中,以便对其进行解码。

  2. 验证是否获得具有所需权限的“角色”声明。

    在下图中,可以看到从具有对Microsoft Defender for Endpoint所有角色的权限的应用获取的解码令牌:

    令牌详细信息部分

使用令牌访问Microsoft Defender for Endpoint API

  1. 选择要使用的 API。 有关详细信息,请参阅 支持的 Defender for Endpoint API
  2. 在发送到“持有者 {token}”的 http 请求中设置授权标头, (持有者是授权方案) 。
  3. 令牌的过期时间为一小时。 可以使用同一令牌发送多个请求。

下面是 使用 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技术社区