受 Microsoft 标识同意框架保护的 API 示例

本文可帮助你以开发人员的身份设计“应用程序权限策略”，以提供“最低特权”。 在继续操作之前，请参阅 API 保护 一文，了解注册、权限和访问的最佳做法。

让我们看看如何通过 Microsoft 标识平台保护的 API 使用 Microsoft 标识同意框架。 我们使用 Microsoft Graph API 作为示例，因为它充分利用 Microsoft 标识平台同意框架。

权限名称的命名约定

Microsoft Graph 团队为权限名称创建了命名约定，以便更轻松地将权限与该权限所能访问的资源联系起来。 Microsoft Graph 权限名称遵循简单的 resource.operation.constraint 模式。 这两个主要操作是 Read 和 ReadWrite（包括更新和删除）。

“约束”元素会影响应用在目录中的访问程度。 Microsoft Graph 支持以下约束：

• “全部”授予应用对目录中指定类型的所有资源执行操作的权限。
• “共享”授予应用对其他用户与登录用户共享的资源执行操作的权限。
• AppFolder 授予你的应用读取和写入 OneDrive 中专用文件夹中文件的权限。 此约束仅在“文件权限”对象上公开，并且仅对 Microsoft 帐户有效。
• 如果指定“无约束”，则应用只能对已登录用户拥有的资源执行操作。

针对特定资源的访问和操作

让我们看看 Microsoft Graph 中用户对象的一些权限或范围，了解 Microsoft API 设计师如何针对特定资源启用特定访问和操作：

权限	显示字符串	说明
User.Read	登录并读取用户配置文件	允许用户登录到应用，并允许应用读取已登录用户的配置文件。 它还允许应用读取已登录用户的基本公司信息。
User.ReadWrite	对用户配置文件的读取和写入访问权限	允许应用读取已登录用户的完整配置文件。 它还允许应用代表已登录用户更新其配置文件信息。

User.Read 和 User.ReadWrite 存在（而不是单个权限，如不存在的 User.Access），使应用程序可以遵循最低特权“零信任”原则。 如果开发人员没有更新用户配置文件的要求和代码，应用不会要求 User.ReadWrite。 因此，攻击者无法破坏应用程序，并用它来更改数据。

请注意，User.Read 不只是授予应用程序对用户对象的访问权限。 每个权限都表示特定的操作范围。 开发人员和管理员必须阅读权限描述，以准确了解任何特定权限启用的内容。 除了启用读取当前用户的完整配置文件之外，User.Read 还可以让应用程序查看 Microsoft Graph 中组织对象的基本信息。

让我们查看另一个权限：

权限	显示字符串	说明
User.ReadBasic.All	读取所有用户的基本配置文件	允许应用代表已登录用户读取组织中其他用户的基本配置文件属性集。 包括显示名称、名字和姓氏、电子邮件地址、开放扩展和照片。 允许应用读取已登录用户的完整配置文件。

User.ReadBasic.All 的操作范围始于 User.Read 所做的一切。 此外，可以访问其他组织用户的显示名称、名字和姓氏、电子邮件地址、照片和开放扩展。 特定的操作范围使应用程序能够拥有良好的人员选取器 UI，并且是 API 设计师使用权限启用特定操作范围的示例。

让我们查看对 Microsoft Graph 用户对象的更多权限：

权限	显示字符串	说明
User.Read.All	读取所有用户的完整个人资料	允许应用代表已登录用户读取组织中其他用户的全套配置文件属性、报告和直属经理。
User.ReadWrite.All	读取和写入所有用户的完整配置文件	允许应用代表已登录用户读取和写入组织中其他用户的全套配置文件属性、报告和直属经理。 还允许应用代表已登录用户来创建和删除用户并重置用户密码。

与 User.Read 和 User.ReadWrite 一样，User.Read.All 和 User.ReadWrite.All 是允许应用程序遵循最低特权零信任原则的不同权限。

User.Read.All 很有趣，因为组织中的每个用户都具有此功能（例如打开 Outlook、在报告链上向上和向下）。 个人可以查看组织中所有其他用户的完整用户配置文件。 但是，Microsoft Graph API 设计师决定只有管理员才应允许应用程序执行相同的操作，因为 User.Read.All 包括租户的组织层次结构。 如果不良参与者访问了此信息，他们可能会发动有针对性的网络钓鱼攻击，其中钓鱼电子邮件来自某个人的经理或更高一层的经理。

User.ReadWrite.All 是一个强大的操作范围。 授予此权限的应用程序可以更新，甚至删除租户中的每个用户。 作为委托的权限，当用户在应用前面时，应用只能执行当前用户可以执行的操作。 无论应用的权限是什么，常规用户都无法更新或删除其他用户。 但是，在租户管理员使用应用可以执行这些操作。 在决定授予或拒绝此权限时，应考虑租户管理员用户来评估你的应用。

需要管理员同意的权限

鉴于 User.Read.All 和 User.ReadWrite.All 的强大功能， Microsoft Graph API 设计师将这些权限指定为需要管理员同意。 让我们在权限表中添加管理员？列，用于指示权限何时需要管理员同意：

权限	显示字符串	说明	管理员？
User.Read	登录并读取用户配置文件	允许用户登录到应用，并允许应用读取已登录用户的配置文件。 它还允许应用读取已登录用户的基本公司信息。	否
User.ReadWrite	对用户配置文件的读取和写入访问权限	允许应用读取已登录用户的完整配置文件。 它还允许应用代表已登录用户更新其配置文件信息。	否
User.ReadBasic.All	读取所有用户的基本配置文件	允许应用代表已登录用户读取组织中其他用户的基本配置文件属性集。 包括显示名称、名字和姓氏、电子邮件地址、开放扩展和照片。 允许应用读取已登录用户的完整配置文件。	否
User.Read.All	读取所有用户的完整个人资料	允许应用代表已登录用户读取组织中其他用户的全套配置文件属性、报告和直属经理。	是
User.ReadWrite.All	读取和写入所有用户的完整配置文件	允许应用代表已登录用户读取和写入组织中其他用户的全套配置文件属性、报告和直属经理。 还允许应用代表已登录用户来创建和删除用户并重置用户密码。	是

如请求需要管理同意的权限一文所述，租户管理员可以否决要求，并将其租户中的任何或所有应用程序权限指定为需要管理员同意。 最好将应用设计为在未收到请求的令牌时能够正常处理理。 未经同意是应用可能无法收到令牌的众多原因之一。

后续步骤

• 从另一个 API 调用 API 可帮助你在一个 API 需要调用另一个 API 时确保零信任，并在应用程序代表用户工作时安全地开发应用程序。
• 获取访问资源的授权有助于了解在获取应用程序的资源访问权限时如何最好地确保零信任。
• 自定义令牌介绍了可以在 Microsoft Entra 令牌中接收的信息。 它说明如何自定义令牌以提高灵活性和控制，同时提高最低特权下的应用程序零信任安全性。
• 在令牌中配置组声明和应用角色介绍了如何使用应用角色定义来配置应用，以及如何将安全组分配给应用角色。 这些方法有助于提高灵活性和控制，同时提高最低特权下的应用程序零信任安全性。
• 请求需要管理同意的权限介绍了当应用程序权限需要管理同意时的权限和同意体验。
• 在本快速入门：使用 Microsoft 标识平台保护 Web API中，下载并运行演示如何保护 ASP.NET Web API 的代码示例。
• 在此教程 - 在 Azure API Management 中转换和保护 API 中，了解如何配置常用策略，以隐藏 API 的 HTTP 响应正文中的技术堆栈信息，或原始 URL。
• 授权最佳做法可帮助你为应用程序实现最佳授权、权限和同意模型。