授权和 Microsoft Graph 安全性 API

  • 项目

通过 Microsoft Graph 安全性 API访问的安全数据是敏感的，受权限和Microsoft Entra角色的保护。

Microsoft Graph 安全性 API 支持以下两种类型的授权：

  • 应用程序级授权： 没有登录用户（例如 SIEM 应用场景）。 授权由授予给应用程序的权限决定。

    注意

    此选项还可以支持应用程序管理基于角色的访问控制（RBAC）的情况。

  • 用户委托的授权：Microsoft Entra租户成员的用户已登录。 用户必须是Microsoft Entra ID受限管理员角色（安全读取者或安全管理员）的成员，此外还必须是已授予所需权限的应用程序。

若要从 Graph 浏览器调用 Microsoft Graph 安全性 API：

  • Microsoft Entra租户管理员必须显式授予对 Graph 资源管理器应用程序所请求权限的同意。

  • 用户必须是安全读取者限制管理员角色的成员，Microsoft Entra ID (安全读取者或安全管理员) 。

    注意

    Graph 浏览器不支持应用程序级授权。

若要从自定义应用或你自己的应用调用 Microsoft Graph 安全性 API：

  • Microsoft Entra租户管理员必须显式向应用程序授予许可。 这对于应用程序级别授权和用户委派授权都是必需的。
  • 如果使用用户委托授权，则用户必须是Microsoft Entra ID中安全读取者或安全管理员有限管理员角色的成员。

管理安全性 API 客户端应用中的授权

通过 Microsoft Graph 安全性 API 提供的安全数据是很敏感的，必须受到适当身份验证和授权机制的保护。 下表列出了注册和创建可访问 Microsoft Graph 安全性 API 的客户端应用的步骤。

谁 操作
应用程序开发人员或所有者： 将应用程序注册为企业应用程序。
租户管理员 向应用程序授予权限。
租户管理员 为用户分配角色。
应用开发人员 以用户身份登录，并使用应用访问 Microsoft Graph 安全性 API。

应用注册仅定义运行应用所需的权限。 它不对应用程序进行这些权限的授予。

Microsoft Entra租户管理员必须显式授予对应用程序的权限。 这必须按每租户实施，并且必须在应用程序权限在应用程序注册门户中每次更改时执行。

例如，假设你有一个应用程序、两个Microsoft Entra租户（T1 和 T2）以及两个权限（P1 和 P2）。 以下是授权过程：

  • 应用程序注册以请求权限 P1。

  • 当租户 T1 中的用户获取此应用程序的Microsoft Entra令牌时，该令牌不包含任何权限。

  • 租户 T1 的Microsoft Entra管理员向应用程序显式授予权限。 当租户 T1 中的用户获取应用程序的Microsoft Entra令牌时，它将包含权限 P1。

  • 当租户 T2 中的用户获取应用程序的Microsoft Entra令牌时，该令牌不包含任何权限，因为租户 T2 的管理员尚未向应用程序授予权限。 权限必须按照每个租户和每个应用程序进行授予。

  • 应用程序将其注册更改为现在需要权限 P1 和 P2。

  • 当租户 T1 中的用户获取应用程序的Microsoft Entra令牌时，它仅包含权限 P1。 授予应用程序的权限将记录为所授予内容的快照;它们不会在应用程序注册（权限）更改后 自动更改。

  • 租户 T2 的管理员对应用程序授予权限 P1 和 P2。 现在，当租户 T2 中的用户获取应用程序的Microsoft Entra令牌时，令牌将包含权限 P1 和 P2。

    注意

    租户 T1 中的应用程序和租户 T2 中的应用程序Microsoft Entra令牌包含不同的权限，因为每个租户管理员都向应用程序授予了不同的权限。

  • 如需使租户 T1 中的应用程序再次运行，租户 T1 的管理员必须向应用程序显式授予权限 P1 和 P2。

向 Microsoft 标识平台终结点注册应用程序

若要向 Microsoft 标识平台终结点注册应用程序，你需要：

  • 应用程序名称： 用作应用程序名称的字符串。
  • 重定向 URL：发送来自Microsoft Entra ID的身份验证响应的 URL。 请使用测试客户端 web 应用主页以开始。
  • 所需权限： 应用程序调用 Microsoft Graph 所需的权限。

注册应用程序：

  1. 转到 Azure 应用注册门户并登录。

    注意

    你无需是租户管理员。你将被重定向到“我的应用程序”列表。

  2. 选择“新注册”。

  3. 在新应用程序的注册页面上，输入“名称”的值，然后选择希望支持的帐户类型。 在“重定向 URI”字段中，输入重定向 URL。

  4. 选择“注册”以创建应用并查看其概述页面。 *

  5. 转到应用的“API 权限”页面。

  6. 选择“添加权限”，然后在浮出控件中选择“Microsoft Graph”。 选择“委托的权限”。 使用搜索框查找并选择所需的权限。 如需查看权限列表，请参阅安全权限。

    注意

    Microsoft Graph 安全性 API 需要 GET 查询的 *.Read.All 作用域和 PATCH/POST/DELETE 查询的 *.ReadWrite.All 作用域。

    权限 实体 受支持的请求
    SecurityActions.Read.All • securityActions (预览版) GET
    SecurityActions.ReadWrite.All • securityActions (预览版) GET, POST
    SecurityEvents.Read.All • 警报
    • secureScores
    • secureScoreControlProfiles    		 GET
    SecurityEvents.ReadWrite.All • 警报
    • secureScores
    • secureScoreControlProfiles    		 GET, POST, PATCH
    ThreatIndicators.ReadWrite.OwnedBy • tiIndicator (预览版) GET, POST, PATCH, DELETE

  7. 选择“添加权限”。

保存以下信息：

  • 应用程序（客户端）ID
  • 重定向 URL
  • 所需权限列表

*Windows Defender高级威胁防护 (WDATP) 需要比 Microsoft Graph 安全性 API所需的用户角色更多的用户角色;因此，只有 WDATP 和 Microsoft Graph 安全性 API 角色中的用户才能访问 WDATP 数据。 仅限应用程序的身份验证不受此约束限制；因此，建议使用仅限应用的身份验证令牌。

有关详细信息，请参阅向 Microsoft 标识平台注册应用。

向应用程序授予权限

应用程序注册仅定义应用程序所需的权限;它不会向应用程序授予这些权限。 Microsoft Entra租户管理员必须通过调用管理员同意终结点来显式授予这些权限。 如需了解详细信息，请参阅使用管理员许可终结点。

如要向应用程序授予权限，将需要：

  • 应用程序 ID： Azure 应用程序注册门户中的应用程序 ID。
  • 重定向 URL： 在 Azure 应用程序注册门户中为身份验证响应设置的字符串。

若要授予权限，请执行下列操作：

  • 在文本编辑器中，创建以下 URL 字符串：

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

  • 在 web 浏览器中转到此 URL，并以租户管理员身份登录。 对话框将显示应用程序需要的权限列表，如应用程序注册门户中所指定的。 选择“确定”，以向应用程序授予这些权限。

    注意

    此步骤向应用程序授予权限，而不是向用户授权。 这意味着，属于使用此应用程序的Microsoft Entra租户的所有用户（甚至是非管理员用户）都将获得这些权限。

向用户分配Microsoft Entra角色

向应用程序授予权限后，有权访问应用程序 (即Microsoft Entra租户) 的成员将接收授予的权限。 为了进一步保护敏感的安全数据，Microsoft Graph 安全性 API还要求向用户分配Microsoft Entra ID安全读取者角色。 有关详细信息，请参阅 Microsoft Entra ID 中的管理员角色权限和将管理员和非管理员角色分配给具有Microsoft Entra ID的用户。

注意

必须是租户管理员才能执行此步骤。

向用户分配角色：

  1. 登录到 Microsoft Entra 管理中心。
  2. 展开“ 标识 ”菜单 > ，展开 “用户> ”，选择“ 所有用户”。
  3. 选择该用户。
  4. 选择“分配的角色”，然后选择“添加分配”。
  5. 选择“安全读取者”，然后单击“添加”。

创建身份验证代码

若要创建身份验证代码，将需要：

  • 应用程序 ID： 应用程序注册门户中的应用程序 ID。
  • 重定向 URL：发送来自Microsoft Entra ID的身份验证响应的 URL。 请使用 https://localhost 或测试客户端 web 应用主页以开始。
  • 应用程序密钥（可选）： 应用程序的密钥。 这适用于将使用仅应用程序身份验证代码（即不支持用户委派身份验证）的应用程序的开发。

下表列出了可用于创建身份验证代码的资源。

应用程序类型 身份验证库
桌面应用 - iOS MSAL.framework：适用于 iOS 的 Microsoft 身份验证库预览版
桌面应用 - Android Microsoft 身份验证库 (MSAL)
桌面应用 - .Net Microsoft 身份验证库 (MSAL)
Web 应用 - JavaScript SPA 适用于 JavaScript 的 Microsoft 身份验证库预览版
Web 应用 - .NET Web 服务器 OpenIdConnection、Cookie、SystemWeb
Web 应用 - NodeJS Web 应用

对于不使用任何现有库的应用程序，请参阅代表用户获取访问权限。

  1. 从Microsoft Entra ID获取代码。 调用的查询包含应用程序 ID 参数、重定向 URl 和所需的权限。
  2. 使用代码获取访问令牌。

如果使用 OpenId Connect 库，请参阅使用 Microsoft Entra ID 进行身份验证和 OpenID Connect 并调用 app.UseOpenIdConnectAuthentication()。

注意

如果请求的是用户委派的身份验证令牌，则库的参数为 请求的作用域。 请对该参数使用 User.Read，而非注册的应用程序所要求的值。 请求的作用域参数不影响包含在返回身份验证令牌中的权限。 这些由租户管理员授予应用程序的权限所确定。

例如，如果使用 .NET MSAL 库，请执行以下调用：

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

注意

此示例应使用最低特权权限，例如 User.Read。 但是，返回的访问令牌可包含由租户管理员授予当前用户租户的权限，如 User.Read.All 或 User.ReadWrite.All。

令牌 (字符串) 由包含身份验证信息和应用程序所需权限的Microsoft Entra ID返回。 将此令牌作为持有者令牌分配到 HTTP 标头，如下例所示。

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

Microsoft Graph 将验证包含在此令牌中的信息，并授予或拒绝访问权限。

如要查看包含在返回令牌中的声明，请使用 NuGet 库 System.IdentityModel.Tokens.Jwt。

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

来自 Microsoft Graph 的响应包含一个被称为 client-request-id 的标头，这是一个 GUID。 如果访问被拒绝，在 Microsoft 技术社区寻求支持时请指明此 GUID，以便帮助调查此身份验证故障的原因。