授权和 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。
通过 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 中应用程序的 Microsoft Entra 令牌和租户 T2 中的应用程序包含不同的权限,因为每个租户管理员都向应用程序授予了不同的权限。
如需使租户 T1 中的应用程序再次运行,租户 T1 的管理员必须向应用程序显式授予权限 P1 和 P2。
若要向 Microsoft 标识平台终结点注册应用程序,你需要:
- 应用程序名称: 用作应用程序名称的字符串。
- 重定向 URL: 发送来自 Microsoft Entra ID 的身份验证响应的 URL。 请使用测试客户端 web 应用主页以开始。
- 所需权限: 应用程序调用 Microsoft Graph 所需的权限。
注册应用程序:
转到 Azure 应用注册门户并登录。
备注
你无需是租户管理员。你将被重定向到“我的应用程序”列表。
选择“新注册”。
在新应用程序的注册页面上,输入“名称”的值,然后选择希望支持的帐户类型。 在“重定向 URI”字段中,输入重定向 URL。
选择“注册”以创建应用并查看其概述页面。 *
转到应用的“API 权限”页面。
选择“添加权限”,然后在浮出控件中选择“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
• secureScoreControlProfilesGET SecurityEvents.ReadWrite.All • 警报
• secureScores
• secureScoreControlProfilesGET, POST, PATCH ThreatIndicators.ReadWrite.OwnedBy • tiIndicator (预览版) GET, POST, PATCH, DELETE 选择“添加权限”。
保存以下信息:
- 应用程序(客户端)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 Graph 安全 API 还要求向用户分配Microsoft Entra ID 安全读取者 角色。 有关详细信息,请参阅 Microsoft Entra ID 中的管理员角色权限 和 将管理员和非管理员角色分配给具有Microsoft Entra ID 的用户。
备注
必须是租户管理员才能执行此步骤。
向用户分配角色:
- 登录到 Microsoft Entra 管理中心。
- 展开“ 标识 ”菜单 > ,展开 “用户> ”,选择“ 所有用户”。
- 选择该用户。
- 选择“分配的角色”,然后选择“添加分配”。
- 选择“安全读取者”,然后单击“添加”。
若要创建身份验证代码,将需要:
- 应用程序 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 应用 |
对于不使用任何现有库的应用程序,请参阅代表用户获取访问权限。
- 从 entra ID Microsoft获取代码。 调用的查询包含应用程序 ID 参数、重定向 URl 和所需的权限。
- 使用代码获取访问令牌。
如果使用 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。
令牌 (字符串) 由包含身份验证信息和应用程序所需权限的 Entra ID Microsoft 返回。 将此令牌作为持有者令牌分配到 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,以便帮助调查此身份验证故障的原因。