授权和 Microsoft Graph 安全性 APIAuthorization and the Microsoft Graph Security API

可通过 Microsoft Graph 安全性 API 访问的安全数据是很敏感的,它受到权限和 Azure Active Directory (Azure AD) 角色保护。Security data accessible via the Microsoft Graph Security API is sensitive and protected by both permissions and Azure Active Directory (Azure AD) roles.

Microsoft Graph 安全性 API 支持以下两种类型的授权:The Microsoft Graph Security API supports two types of authorization:

  • 应用级授权 - 没有已登录用户(例如,SIEM 方案)。Application-level authorization - There is no signed-in user (for example, a SIEM scenario). 授权由授予给应用程序的权限决定。The permissions granted to the application determine authorization.

    注意: 此选项还可以支持基于角色的访问控制 (RBAC) 由应用程序管理的情况。Note: This option can also support cases where Role-Based Access Control (RBAC) is managed by the application.

  • 用户委派授权 - 身份为 Azure AD 租户成员的用户已登录。User delegated authorization - A user who is a member of the Azure AD tenant is signed in. 除了已被授予所需权限的应用程序之外,用户必须是 Azure AD 有限管理员角色的成员 - 安全读者或安全管理员。The user must be a member of an Azure AD Limited Admin role - either Security Reader or Securty Administrator - in addition to the application having been granted the required permissions.

若要从 Graph 浏览器调用 Microsoft Graph 安全性 API:If you're calling the Microsoft Graph Security API from Graph Explorer:

  • Azure AD 租户管理员必须对 Graph 浏览器应用显式授予所请求的权限。The Azure AD tenant admin must explicitly grant consent for the requested permissions to the Graph Explorer application.
  • 用户必须是 Azure AD 中安全读者有限管理员角色的成员(安全读者或安全管理员)。The user must be a member of the Security Reader Limited Admin role in Azure AD (either Security Reader or Security Administrator).

注意:Graph 浏览器不支持应用级授权。Note: Graph Explorer does not support application-level authorization.

若要从自定义应用或你自己的应用调用 Microsoft Graph 安全性 API:If you're calling the Microsoft Graph Security API from a custom or your own application:

  • Azure AD 租户管理员必须对你的应用显式授权。The Azure AD tenant admin must explicitly grant consent to your application. 这对于应用程序级别授权和用户委派授权都是必需的。This is required both for application-level authorization and user delegated authorization.
  • 如果正在使用用户委派授权,用户必须是 Azure AD 中安全读者或安全管理员有限管理员角色的成员。If you're using user delegated authorization, the user must be a member of the Security Reader or Security Administrator Limited Admin role in Azure AD.

管理安全性 API 客户端应用中的授权Manage authorization in security API client applications

通过 Microsoft Graph 安全性 API 提供的安全数据是很敏感的,必须受到适当身份验证和授权机制的保护。Security data provided via the Microsoft Graph Security API is sensitive and must be protected by appropriate authentication and authorization mechanisms. 下表列出了注册和创建可访问 Microsoft Graph 安全性 API 的客户端应用的步骤。The following table lists the steps to register and create a client application that can access the Microsoft Graph Security API.

Who 操作Action
应用程序开发人员或所有者:Application developer or owner 将应用程序注册为企业应用程序。Register the application as an enterprise application.
租户管理员Tenant admin 向应用程序授予权限。Grant permissions to the application.
租户管理员Tenant admin 为用户分配角色。Assign roles to users.
应用开发人员Application developer 以用户身份登录,并使用应用访问 Microsoft Graph 安全性 API。Sign in as the user and use the application to access the Microsoft Graph Security API.

应用注册仅定义运行应用所需的权限。Application registration only defines which permissions the application needs in order to run. 它不对应用程序进行这些权限的授予。It does NOT grant these permissions to the application.

Azure AD 租户管理员必须对应用程序显式授予权限。The Azure AD tenant administrator MUST explicitly grant the permissions to the application. 这必须按每租户实施,并且必须在应用程序权限在应用程序注册门户中每次更改时执行This must be done per tenant and must be performed every time the application permissions are changed in the application registration portal.

例如,假定你拥有一个应用程序、两个 Azure AD 租户(T1T2),以及两个权限(P1P2)。For example, assume that you have an application, two Azure AD tenants, T1 and T2, and two permissions, P1 and P2. 以下是授权过程:The following is the authorization process:

  • 应用程序注册以请求权限 P1The application registers to require permission P1.
  • 当租户 T1 中的用户获取此应用程序的 Azure AD 令牌时,该令牌不包含任何权限。When users in tenant T1 get an Azure AD token for this application, the token does not contain any permissions.
  • 租户 T1 的 Azure AD 管理员向应用程序显式授予权限。The Azure AD admin of tenant T1 explicitly grants permissions to the application. 当租户 T1 中的用户获取应用程序的 Azure AD 令牌时,它将包含权限 P1When users in tenant T1 get an Azure AD token for the application, it will contain permission P1.
  • 当租户 T2 中的用户获取应用程序的 Azure AD 令牌时,该令牌不包含任何权限,因为租户 T2 的管理员尚未向该应用程序授予权限。When users in tenant T2 get an Azure AD token for the application, the token does not contain any permissions - because the admin of tenant T2 did not yet grant permissions to the application. 权限必须按照每个租户每个应用程序进行授予。Permission must be granted per tenant and per application.
  • 应用程序将其注册更改为现在需要权限 P1P2The application has its registration changed to now require permissions P1 and P2.
  • 当租户 T1 中的用户获取应用程序的 Azure AD 令牌时,它仅包含权限 P1When users in tenant T1 get an Azure AD token for the application, it only contains permission P1. 授予应用程序的权限作为授予内容快照进行记录,它们在应用程序注册(权限)更改后不会自动更改Permissions granted to an application are recorded as snapshots of what was granted - they do not change automatically after the application registration (permission) changes.
  • 租户 T2 的管理员对应用程序授予权限 P1P2The admin of tenant T2 grants permissions P1 and P2 to the application. 当租户 T2 中的用户获取应用程序的 Azure AD 令牌时,该令牌将包含权限 P1P2Now, when users in tenant T2 get an Azure AD token for the application, the token will contain permissions P1 and P2.

注意:租户 T1 中的应用程序和租户 T2 中的应用程序的 Azure AD 令牌包含不同权限,因为每个租户管理员已为应用程序授予不同的权限。Note: The Azure AD tokens for the application in tenant T1 and the application in tenant T2 contain different permissions, because each tenant admin has granted different permissions to the application.

  • 如需使租户 T1 中的应用程序再次运行,租户 T1 的管理员必须向应用程序显式授予权限 P1P2To make the application work again in tenant T1, the admin of tenant T1 must explicitly grant permissions P1 and P2 to the application.

向 Microsoft 标识平台终结点注册应用程序Register an application with the Microsoft identity platform endpoint

若要向 Microsoft 标识平台终结点注册应用程序,你需要:To register an application to the Microsoft identity platform endpoint, you'll need:

  • 应用程序名称 - 表示应用程序名称的字符串。Application name - A string used for the application name.
  • 重定向 URL - 该 URL 发送来自 Azure AD 的身份验证响应。Redirect URL - The URL where the authentication response from Azure AD is sent. 请使用测试客户端 web 应用主页以开始。To start, you can use the test client web app homepage.
  • 所需的权限 - 应用程序需要的用于调用 Microsoft Graph 的权限。Required Permissions - The permissions that your application requires to be able to call Microsoft Graph.

注册应用程序:To register your application:

  1. 转到 Azure 应用注册门户并登录。Go to the Azure app registration portal and sign in.

    注意:你无需是租户管理员。你将被重定向到“我的应用程序”列表。Note: You don't have to be a tenant admin. You will be redirected to the My applications list.

  2. 选择“新注册”。Choose New registration.

  3. 在新应用程序的注册页面上,输入“名称”的值,然后选择希望支持的帐户类型。On the registration page for the new application, enter a value for Name and select the account types you wish to support. 在“重定向 URI”字段中,输入重定向 URL。In the Redirect URI field, enter the redirect URL.

  4. 选择“注册”以创建应用并查看其概述页面。Select Register to create the app and view its overview page. *

  5. 转到应用的“API 权限”页面。Go to the app's API permissions page.

  6. 选择“添加权限”,然后在浮出控件中选择“Microsoft Graph”。Select Add a permission and then choose Microsoft Graph in the flyout. 选择“委托的权限”。Select Delegated permissions. 使用搜索框查找并选择所需的权限。Use the search box to find and select the required permissions. 如需查看权限列表,请参阅安全权限For a list of permissions, see Security permissions.

    注释: Microsoft Graph 安全性 API 需要 *.Read.All scope 才能进行 GET 查询,需要 *.ReadWrite.All scope 才能进行 PATCH/POST/DELETE 查询。Note: The Microsoft Graph Security API requires the *.Read.All scope for GET queries, and the *.ReadWrite.All scope for PATCH/POST/DELETE queries.

    权限Permission 实体Entity 受支持的请求Supported requests
    SecurityActions.Read.AllSecurityActions.Read.All securityActions(预览)securityActions (preview) GETGET
    SecurityActions.ReadWrite.AllSecurityActions.ReadWrite.All securityActions(预览)securityActions (preview) GET, POSTGET, POST
    SecurityEvents.Read.AllSecurityEvents.Read.All alertsalerts
    secureScoressecureScores
    secureScoreControlProfilessecureScoreControlProfiles
    GETGET
    SecurityEvents.ReadWrite.AllSecurityEvents.ReadWrite.All alertsalerts
    secureScoressecureScores
    secureScoreControlProfilessecureScoreControlProfiles
    GET, POST, PATCHGET, POST, PATCH
    ThreatIndicators.ReadWrite.OwnedByThreatIndicators.ReadWrite.OwnedBy tiIndicator(预览)tiIndicator (preview) GET, POST, PATCH, DELETEGET, POST, PATCH, DELETE
  7. 选择“添加权限”。Choose Add permissions.

保存以下信息:Save the following information:

  • 应用程序(客户端)IDApplication (client) ID
  • 重定向 URLRedirect URL
  • 所需权限列表List of required permissions

与 Microsoft Graph 安全 API 相比,* Windows Defender 高级威胁防护 (WDATP) 所需的用户角色更多;因此,只有同时具备 WDATP 和 Microsoft Graph 安全 API 角色的用户才可访问 WDATP 数据。* Windows Defender Advanced Threat Protection (WDATP) requires additional user roles than what is required by the Microsoft Graph Security API; therefore, only the users in both WDATP and Microsoft Graph Security API roles can have access to the WDATP data. 仅限应用程序的身份验证不受此约束限制;因此,建议使用仅限应用的身份验证令牌。Application-only authentication is not limited by this; therefore, we recommend that you use an app-only authentication token.

有关详细信息,请参阅向 Microsoft 标识平台注册应用For more information, see Register your app with the Microsoft identity platform.

向应用程序授予权限Grant permissions to an application

应用程序注册仅定义应用程序所需的权限,它并不向应用程序授予这些权限。Application registration only defines which permission the application requires - it does not grant these permissions to the application. Azure AD 租户管理员必须通过调用管理员许可终结点来显示授予这些权限。An Azure AD tenant administrator must explicitly grant these permissions by making a call to the admin consent endpoint. 如需了解详细信息,请参阅使用管理员许可终结点For details, see Using the admin consent endpoint.

如要向应用程序授予权限,将需要:To grant permissions to an application, you'll need:

  • 应用程序 ID - Azure 应用程序注册门户中的应用程序 ID。Application ID - The application ID from the Azure application registration portal.
  • 重定向 URL - 在 Azure 应用程序注册门户中为身份验证响应设置的字符串。Redirect URL - The string you set in the Azure application registration portal for authentication response.

若要授予权限,请执行下列操作:To grant the permissions:

  • 在文本编辑器中,创建以下 URL 字符串:In a text editor, create the following URL string:

    https://login.microsoftonline.com/common/adminconsent?client_id=<Application Id>&state=12345&redirect_uri=<Redirect URL>

  • 在 web 浏览器中转到此 URL,并以租户管理员身份登录。In a web browser, go to this URL, and sign in as a tenant administrator. 对话框将显示应用程序需要的权限列表,如应用程序注册门户中所指定的。The dialog box shows the list of permission the application requires, as specified in the application registration portal. 选择“确定”,以向应用程序授予这些权限。Choose OK to grant the application these permissions.

注意: 此步骤向应用程序授予权限,而不是向用户授权。Note: This step grants permissions to the application - not to users. 这意味着属于 Azure AD 租户的所有使用此应用程序的用户将被授予权限,甚至包括非管理员用户。This means that all users belonging to the Azure AD tenant that use this application will be granted these permissions - even non-admin users.

向用户分配 Azure AD 角色Assign Azure AD roles to users

应用程序被授予权限后,每个可以访问该应用程序的人(即 Azure AD 租户的成员)都将获得所授予的权限。After an application is granted permissions, everyone with access to the application (that is, members of the Azure AD tenant) will receive the granted permissions. 为了进一步保护敏感安全数据,Microsoft Graph 安全性 API 还要求必须为用户分配 Azure AD 安全读者角色。To further protect sensitive security data, the Microsoft Graph Security API also requires users to be assigned the Azure AD Security Reader role. 有关详细信息,请参阅 Azure Active Directory 中的管理员角色权限为具有 Azure Active Directory 的用户分配管理员和非管理员角色For details, see Administrator role permissions in Azure Active Directory and Assign administrator and non-administrator roles to users with Azure Active Directory.

注意: 必须是租户管理员才能执行此步骤。Note: You must be a tenant admin to perform this step.

向用户分配角色:To assign a role to a user:

  1. 登录到 Azure 门户 (https://portal.azure.com)。Sign in to the Azure portal (https://portal.azure.com).
  2. 单击左上角的图标以展开 Azure 门户菜单。Click the icon in the top left to expand the Azure portal menu. 选择“Azure Active Directory” > “用户”。Select Azure Active Directory > Users.
  3. 单击相应用户的姓名。Click the user name of the account.
  4. 选择“分配的角色”,然后选择“添加分配”。Choose Assigned roles, and then Add assignment.
  5. 选择“安全读取者”,然后单击“添加”。Select Security reader, and click Add.

创建身份验证代码Create an authentication code

若要创建身份验证代码,将需要:To create an authentication code, you'll need:

  • 应用程序 ID - 应用程序注册门户中的应用程序 ID。Application ID - The application ID from application registration portal.
  • 重定向 URL - 该 URL 发送来自 Azure AD 的身份验证响应。Redirect URL - The URL where the authentication response from Azure AD is sent. 请使用 https://localhost 或测试客户端 web 应用主页以开始。To start, you can use https://localhost or the test client web app homepage.
  • 应用程序密钥(可选)- 应用程序的密钥。Application Key (optional) - The key of the application. 这适用于将使用仅应用程序身份验证代码(即不支持用户委派身份验证)的应用程序的开发。This applies when you're developing an application that will use application-only authentication code (that is, will not support user delegated authentication).

下表列出了可用于创建身份验证代码的资源。The following table lists resources that you can use to create an authentication code.

应用程序类型Type of application 身份验证库Authentication library
桌面应用 - iOSDesktop apps - iOS MSAL.framework:适用于 iOS 的 Microsoft 身份验证库预览版MSAL.framework: Microsoft Authentication Library Preview for iOS
桌面应用 - AndroidDesktop apps - Android Microsoft 身份验证库 (MSAL)Microsoft Authentication Library (MSAL)
桌面应用 - .NetDesktop apps - .Net Microsoft 身份验证库 (MSAL)Microsoft Authentication Library (MSAL)
Web 应用 - JavaScript SPAWeb apps - JavaScript SPA 适用于 JavaScript 的 Microsoft 身份验证库预览版Microsoft Authentication Library for JavaScript Preview
Web 应用 - .NET Web 服务器Web apps - .NET Web Server OpenIdConnection、Cookie、SystemWebOpenIdConnection, Cookies, SystemWeb
Web 应用 - NodeJS Web 应用Web apps - NodeJS Web App

对于不使用任何现有库的应用程序,请参阅代表用户获取访问权限For applications that don't use any of the existing libraries, see Get access on behalf of a user.

  1. 从 Azure AD 获取代码。Get a code from Azure AD. 调用的查询包含应用程序 ID 参数、重定向 URl 和所需的权限The query to call contains parameter for Application ID, Redirect URl, and required permissions.
  2. 使用代码获取访问令牌。Use the code to get an access token.

如果你使用 OpenId Connect 库,请参阅使用 Azure AD 和 OpenID Connect 进行身份验证并调用 app.UseOpenIdConnectAuthentication()If you use OpenId Connect library, see Authenticate using Azure AD and OpenID Connect and call app.UseOpenIdConnectAuthentication().

注意: 如果请求的是用户委派身份验证令牌,库的参数是请求的作用域Note: If you're requesting user delegated authentication tokens, the parameter for the library is Requested Scopes. 请对该参数使用 User.Read,而非注册的应用程序所要求的值。Use User.Read for this parameter instead of what the registered application requires. 请求的作用域参数不影响包含在返回身份验证令牌中的权限。The Requested Scopes parameter does NOT affect the permissions contained in the returned authentication tokens. 这些由租户管理员授予应用程序的权限所确定。These are determined by the permissions that the tenant admin granted the application.

例如,如果使用 .NET MSAL 库,请执行以下调用:For example, if you're using the .NET MSAL library, call the following:

var accessToken = (await client.AcquireTokenAsync(scopes)).AccessToken;

注意: 此示例应使用最低的许可权限,如 User.Read。Note: This example should use the least privileged permission, such as User.Read. 但是,返回的访问令牌可包含由租户管理员授予当前用户租户的权限,如 User.Read.All 或 User.ReadWrite.All。However, the returned access token can contain permissions that were granted by the tenant admin for the current user tenant, such as User.Read.All or User.ReadWrite.All.

Azure AD 返回的令牌(字符串)包含身份验证信息和应用程序所需的权限。A token (string) is returned by Azure AD that contains your authentication information and the permissions required by the application. 将此令牌作为持有者令牌分配到 HTTP 标头,如下例所示。Assign this token to the HTTP header as a bearer token, as shown in the following example.

request.Headers.Authorization = new AuthenticationHeaderValue("bearer", accessToken);

Microsoft Graph 将验证包含在此令牌中的信息,并授予或拒绝访问权限。Microsoft Graph will validate the information contained in this token and grant, or reject, access.

如要查看包含在返回令牌中的声明,请使用 NuGet 库 System.IdentityModel.Tokens.Jwt。To view claims contained in the returned token, use NuGet library System.IdentityModel.Tokens.Jwt.

JwtSecurityTokenHandler tokenHandler = new JwtSecurityTokenHandler();
var securityToken = tokenHandler.ReadToken(accessToken) as JwtSecurityToken;

来自 Microsoft Graph 的响应包含一个被称为 client-request-id 的标头,这是一个 GUID。The response from Microsoft Graph contains a header called client-request-id, which is a GUID. 如果访问被拒绝,在 Microsoft 技术社区寻求支持时请指明此 GUID,以便帮助调查此身份验证故障的原因。If access is denied, please specify this GUID when seeking support at Microsoft Tech Community, so we can help investigate the cause of this authentication failure.