创建应用以代表用户访问 Microsoft 365 Defender APICreate an app to access Microsoft 365 Defender APIs on behalf of a user

重要

改进的 Microsoft 365 安全中心现已提供公共预览版。The improved Microsoft 365 security center is now available in public preview. 此新体验将 Defender for Endpoint、Defender for Office 365、Microsoft 365 Defender 等引入 Microsoft 365 安全中心。This new experience brings Defender for Endpoint, Defender for Office 365, Microsoft 365 Defender, and more into the Microsoft 365 security center. 安全团队现可管理所有终结点、电子邮件和跨产品调查、配置和修正,而无需导航到单独的产品门户。Security teams can now manage all endpoint, email and cross product investigations, configuration and remediation without the need to navigate to separate product portals. 了解有关更改的详细信息Learn more about what's changed.

适用于:Applies to:

  • Microsoft 365 DefenderMicrosoft 365 Defender

重要

某些信息与预发布的产品有关,在商业发布之前可能有重大修改。Some information relates to prereleased product which may be substantially modified before it's commercially released. Microsoft 对此处所提供的信息不作任何明示或默示的保证。Microsoft makes no warranties, express or implied, with respect to the information provided here.

此页面介绍如何创建应用程序以代表单个用户以编程方式访问 Microsoft 365 Defender。This page describes how to create an application to get programmatic access to Microsoft 365 Defender on behalf of a single user.

如果你需要在未定义用户 (的情况下以编程方式访问 Microsoft 365 Defender,例如,如果你正在编写后台应用或守护程序) ,请参阅创建应用以在没有用户的情况下访问Microsoft 365 Defender。If you need programmatic access to Microsoft 365 Defender without a defined user (for example, if you're writing a background app or daemon), see Create an app to access Microsoft 365 Defender without a user. 如果你需要为多个租户提供访问权限(例如,如果你为大型组织或一组客户提供服务)请参阅创建具有 Microsoft 365 Defender API合作伙伴访问权限的应用。如果你不确定需要哪种类型的访问,请参阅 入门If you need to provide access for multiple tenants—for example, if you're serving a large organization or a group of customers—see Create an app with partner access to Microsoft 365 Defender APIs.If you're not sure which kind of access you need, see Get started.

Microsoft 365 Defender 通过一组编程 API 公开其大部分数据和操作。Microsoft 365 Defender exposes much of its data and actions through a set of programmatic APIs. 这些 API 可帮助你自动化工作流和利用 Microsoft 365 Defender 的功能。Those APIs help you automate workflows and make use of Microsoft 365 Defender's capabilities. 此 API 访问需要 OAuth2.0 身份验证。This API access requires OAuth2.0 authentication. 有关详细信息,请参阅 OAuth 2.0 授权代码流For more information, see OAuth 2.0 Authorization Code Flow.

通常,你将需要执行以下步骤来使用这些 API:In general, you'll need to take the following steps to use these APIs:

  • 创建 Azure Active Directory (Azure AD) 应用程序。Create an Azure Active Directory (Azure AD) application.
  • 使用此应用程序获取访问令牌。Get an access token using this application.
  • 使用令牌访问 Microsoft 365 Defender API。Use the token to access Microsoft 365 Defender API.

本文介绍如何:This article explains how to:

  • 创建 Azure AD 应用程序Create an Azure AD application
  • 获取 Microsoft 365 Defender 的访问令牌Get an access token to Microsoft 365 Defender
  • 验证令牌Validate the token

备注

代表用户访问 Microsoft 365 Defender API 时,需要正确的应用程序权限和用户权限。When accessing Microsoft 365 Defender API on behalf of a user, you will need the correct application permissions and user permissions.

提示

如果你有权在门户中执行一个操作,则你有权在 API 中执行此操作。If you have the permission to perform an action in the portal, you have the permission to perform the action in the API.

创建应用Create an app

  1. 以具有全局管理员角色的用户 登录 Azure。Sign in to Azure as a user with the Global Administrator role.

  2. 导航到 Azure Active Directory > 应用注册 > 新注册Navigate to Azure Active Directory > App registrations > New registration.

    Microsoft Azure 的图像和应用程序注册导航

  3. 在表单中,为应用程序选择一个名称,然后输入重定向 URI 的以下信息,然后选择"注册 "。In the form, choose a name for your application and enter the following information for the redirect URI, then select Register.

    "创建应用程序"窗口的图像

  4. 在应用程序页面上,选择 "API 权限""添加我的组织使用> > > API",键入 "Microsoft 威胁 防护",然后选择 "Microsoft 威胁防护"。On your application page, select API Permissions > Add permission > APIs my organization uses >, type Microsoft Threat Protection, and select Microsoft Threat Protection. 你的应用现在可以访问 Microsoft 365 Defender。Your app can now access Microsoft 365 Defender.

    提示

    Microsoft 威胁防护 是 Microsoft 365 Defender 的以前名称,不会显示在原始列表中。Microsoft Threat Protection is a former name for Microsoft 365 Defender, and will not appear in the original list. 你需要开始在文本框中写入其名称,以查看其显示。You need to start writing its name in the text box to see it appear.

    API 权限选择的图像

    • 选择 "委派权限"。Choose Delegated permissions. 为方案选择相关权限,例如 (Incident.Read) ,然后选择"添加权限"。Choose the relevant permissions for your scenario (for example Incident.Read), and then select Add permissions.

    API 访问和 API 选择的图像

    备注

    您需要为方案选择相关权限。You need to select the relevant permissions for your scenario. 读取所有事件 只是一个示例。Read all incidents is just an example. 若要确定所需的权限,请查看要调用的 API中的"权限"部分。To determine which permission you need, please look at the Permissions section in the API you want to call.

    例如,若要 运行高级查询,请选择"运行高级查询"权限;若要 隔离设备,请选择"隔离计算机"权限。For instance, to run advanced queries, select the 'Run advanced queries' permission; to isolate a device, select the 'Isolate machine' permission.

  5. 选择 "授予管理员同意"。Select Grant admin consent. 每次添加权限时,都必须选择"授予管理员 同意 ,让权限生效"。Every time you add a permission, you must select Grant admin consent for it to take effect.

    授予权限的图像

  6. 在安全的地方记录应用程序 ID 和租户 ID。Record your application ID and your tenant ID somewhere safe. 它们列在应用程序 页面上的" 概述"下。They're listed under Overview on your application page.

    已创建应用 ID 的图像

获取访问令牌Get an access token

有关 Azure Active Directory 令牌详细信息,请参阅 Azure AD 教程For more information on Azure Active Directory tokens, see the Azure AD tutorial.

使用 PowerShell 获取访问令牌Get an access token using PowerShell

if(!(Get-Package adal.ps)) { Install-Package -Name adal.ps } # Install the ADAL.PS package in case it's not already present

$tenantId = '' # Paste your directory (tenant) ID here.
$clientId = '' # Paste your application (client) ID here.
$redirectUri = '' # Paste your app's redirection URI

$authority = "https://login.windows.net/$tenantId"
$resourceUrl = 'https://api.security.microsoft.com'

$response = Get-ADALToken -Resource $resourceUrl -ClientId $cleintId -RedirectUri $redirectUri -Authority $authority -PromptBehavior:Always
$response.AccessToken | clip

$response.AccessToken

验证令牌Validate the token

  1. 将令牌复制并粘贴到 JWT 中以解码它。Copy and paste the token into JWT to decode it.
  2. 确保解码 令牌 中的角色声明包含所需的权限。Make sure that the roles claim within the decoded token contains the desired permissions.

在下图中,你可以看到从应用获取的解码令牌,具有 、 和 Incidents.Read.All Incidents.ReadWrite.All AdvancedHunting.Read.All 权限:In the following image, you can see a decoded token acquired from an app, with Incidents.Read.All, Incidents.ReadWrite.All, and AdvancedHunting.Read.All permissions:

令牌验证图像

使用令牌访问 Microsoft 365 Defender APIUse the token to access the Microsoft 365 Defender API

  1. 选择要用于事件或高级搜寻 () API。Choose the API you want to use (incidents, or advanced hunting). 有关详细信息,请参阅支持的Microsoft 365 Defender API。For more information, see Supported Microsoft 365 Defender APIs.
  2. 在即将发送的 http 请求中,将授权标头设置为 "Bearer" <token> ,Bearer 为授权方案,令牌为经过验证的令牌。In the http request you're about to send, set the authorization header to "Bearer" <token>, Bearer being the authorization scheme, and token being your validated token.
  3. 令牌将在一小时内过期。The token will expire within one hour. 在此期间,可以使用同一令牌发送多个请求。You can send more than one request during this time with the same token.

以下示例演示如何发送请求,以使用 C# 获取 事件列表The following example shows how to send a request to get a list of incidents using 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();