通过

Microsoft Graph 权限概述

  • 项目

在Microsoft 标识平台授权应用访问Microsoft云中的数据之前，必须授予应用所需的权限。 同样，在Microsoft 标识平台授权应用通过 Microsoft Graph 访问数据之前，必须向应用授予所需的权限。

通过 Microsoft Graph 授予应用访问和处理数据所需的权限的一种方法是向其分配 Microsoft Graph 权限。 另一种方法是通过基于角色的访问控制 (RBAC) 系统，如 Microsoft Entra RBAC。 在某些情况下，通过 Microsoft Graph API 访问数据可能需要Microsoft Graph 权限和 RBAC 权限。

本文介绍Microsoft Graph 权限，并提供使用这些权限的指导。 若要查看 Microsoft Graph 公开的权限的完整列表，请参阅 Microsoft Graph 权限参考。

若要了解有关权限工作原理的详细信息，watch以下视频。

权限类型

Microsoft Graph 支持 两种访问方案： 委托访问 和 仅应用访问。 在委托访问中，应用代表已登录用户调用 Microsoft Graph。 在仅限应用的访问中，应用使用自己的标识调用 Microsoft Graph，而无需登录用户。

为了支持这些访问方案，Microsoft Graph 公开 了委托的权限 和 应用程序权限。

委派权限

委托的权限（也称为 范围）用于委派访问方案。 它们是允许应用程序代表已登录用户执行操作的权限。 但是，应用程序无法访问已登录用户无法访问的任何内容。

例如，已代表用户 Tom 向应用程序授予 Files.Read.All 委托权限。 应用程序只能读取 Tom 已访问的组织中的所有文件。 Tom 可能能够访问这些文件，因为他通过以下方式之一拥有权限：

  • Tom 创建或拥有这些文件。
  • 文件直接与 Tom 共享，或通过团队或组成员身份间接共享。
  • Tom 已通过受支持的 RBAC 系统获得权限。

因此，在委派方案中，应用必须代表用户执行操作的权限由已授予应用的 Microsoft Graph 权限 和 用户自己的权限决定。

在委派访问方案中，应用可能允许用户使用其个人Microsoft帐户（如 Outlook.com、工作或学校帐户）登录，或同时允许这两种帐户类型。 所有委托的权限都对工作或学校帐户有效，但并非所有权限都对个人Microsoft帐户有效。 使用 Microsoft Graph 权限引用 来标识对个人Microsoft帐户有效的委派权限。

当用户登录到应用时，他们（或在某些情况下是管理员）有机会同意委派的权限。 如果他们授予同意，则应用可以访问用户权限边界内的资源和 API。

注意

通过Microsoft Entra内置角色授予的权限不会将应用限制为仅调用 Microsoft Graph API。

应用程序权限

应用程序权限（也称为 应用角色）在仅应用访问方案中使用，没有登录用户存在。 应用程序能够访问与权限关联的 任何 数据。 例如，授予 Files.Read.All 权限的应用程序可以读取组织中的任何文件。

对于在没有登录用户的情况下访问资源和 API 的应用，当应用安装在租户中或通过Microsoft Entra 管理中心时，管理员会同意应用程序权限。 只有特权角色管理员和全局管理员才能同意应用程序权限。

除了为应用分配Microsoft Graph 应用程序权限外，还可以通过以下条件之一授予应用所需的权限：

  • 为应用分配要管理的资源的所有权时。
  • 通过 RBAC 系统或自定义管理角色为应用分配权限时。

注意

通过Microsoft Entra内置角色授予的权限不会将应用限制为仅调用 Microsoft Graph API。

委派权限和应用程序权限的比较

类别 委派权限 应用程序权限
应用类型 Web 应用/移动/单页应用 (SPA) Web/守护程序
访问上下文 代表用户获取访问权限 不代表用户获取访问权限
谁可以同意
  • 用户可以同意其数据
  • 管理员可以同意所有用户
    		•  只有管理员才能同意
    其他名称
  • Scopes
  • OAuth2 权限
    		•
  • 应用角色
  • 仅应用权限
  • 直接访问权限
    		•
    同意结果 oAuth2PermissionGrant 对象 appRoleAssignment 对象
    支持的 signInAudience 类型 AzureADMyOrg
    AzureADMultleOrgs
    AzureADandPersonalMicrosoftAccount
    PersonalMicrosoftAccount    		 AzureADMyOrg
    AzureADMultleOrgs
    AzureADandPersonalMicrosoftAccount

    下图演示了应用在委派访问与仅应用访问方案中的权限。

    委派访问与仅应用访问方案中的应用程序特权的插图。

    权限命名模式

    Microsoft Graph 公开精细权限，可帮助你控制应用Microsoft Graph 资源（如用户、组和邮件）的访问权限。 这些权限按以下模式命名：

    {resource}。{operation}。{constraint}

    值 说明 示例
    {resource} 指权限允许访问的Microsoft Graph 资源。 例如， user 资源。 User、 Application、 或 Group
    {operation} 指对资源公开的数据允许的Microsoft图形 API操作。 例如， Read 仅用于读取操作，或者 ReadWrite 对于读取、创建、更新和删除操作。 Read、 ReadBasic、 ReadWrite、 Create、 Manage或 Migrate
    {constraint} 确定应用在目录中具有的潜在访问范围。 此值可能不会显式声明。 未声明时，默认约束仅限于已登录用户拥有的数据。 All, AppFolder, OwnedBy, Selected, Shared, Hidden

    示例：

    • User.Read - 允许应用读取有关已登录用户的信息。
    • Application.ReadWrite.All - 允许应用管理租户中的所有应用程序。
    • Application.ReadWrite.OwnedBy - 允许应用仅管理它创建或拥有的应用程序。
    • Group.Create - 允许应用程序创建新组，但不允许修改或删除它们。
    • Member.Read.Hidden - 允许应用读取隐藏的成员身份

    有关 Microsoft Graph 公开的权限的完整列表，请参阅 Microsoft Graph 权限参考。

    RSC 是一个授权框架，允许授予对资源公开的数据的作用域访问权限。 通过 RSC，授权用户可以向应用授予对资源类型特定实例的数据的访问权限。 他们不需要向应用授予对整个租户中资源类型每个实例的访问权限。

    RSC 权限也可供许可使用，并且仅受Microsoft Graph 提供的一部分功能（如 Teams、聊天和消息）的支持。 详细了解 RSC 权限 或发现 可用的 RSC 权限的完整列表。

    为不可访问的成员对象返回有限的信息

    容器对象（例如组）支持各种类型的成员（例如用户和设备）。 当具有适当特权的应用程序查询容器对象的成员身份时，它会收到 200 OK 响应和对象的集合。 但是，如果应用无权读取容器中的特定对象类型，则会返回该类型的对象，但信息有限，例如，只能返回对象类型和 ID，并且其他属性指示为 null。 将返回应用有权读取的对象类型的完整信息。

    此原则应用于 directoryObject 类型的所有关系。 示例包括 /groups/{id}/members、 /users/{id}/memberOf和 me/ownedObjects。

    例如，组可以将用户、组、应用程序、服务主体、设备和联系人作为成员。 向应用授予对列表组成员的 GroupMember.Read.All 最低特权权限。 在响应对象中，仅为返回的所有成员填充 id 和 @odata.type 属性。 其他属性指示为 null。 对于此 API：

    • 若要读取组成员（即用户）的基本属性，应用至少需要 User.ReadBasic.All 权限。
    • 若要读取组成员（即组）的基本属性，应用至少需要 GroupMember.Read.All 权限。
    • 若要读取组成员（即设备）的基本属性，应用至少需要 Device.Read.All 权限等。
    • 但是，作为单个资源级权限的替代方法，至少可以为应用分配 Directory.Read.All 权限，以读取 所有成员类型的所有属性。

    示例

    请求

    GET https://graph.microsoft.com/v1.0/groups/{id}/members

    响应

    以下对象是响应的示例：

    {
"@odata.context":"https://graph.microsoft.com/v1.0/$metadata#directoryObjects",
    "value":[
        {
            "@odata.type":"#microsoft.graph.user",
            "id":"69d035a3-29c9-469f-809d-d21a4ae69e65",
            "displayName":"Adele Vance",
            "createdDateTime":"2019-09-18T09:06:51Z",
        },
        {
            "@odata.type":"#microsoft.graph.group",
            "id":"c43a7cc9-2d95-44b6-bf6a-6392e41949b4",
            "displayName":"All Company",
            "description":null,
            "createdDateTime":"2019-10-24T01:34:35Z"
        },
        {
            "@odata.type":"#microsoft.graph.device",
            "id": "d282309e-f91d-43b6-badb-9e68aa4b4fc8",
            "accountEnabled":null,
            "deviceId":null,
            "displayName":null,
            "operatingSystem":null,
            "operatingSystemVersion":null
        }
    ]
}

    使用 Microsoft Graph 权限的最佳做法

    Microsoft Graph 公开精细权限，允许应用仅请求运行所需的权限。 通过向应用授予操作所需的 最低权限 ，精细权限允许你在向应用分配和授予权限时应用最小特权原则。

    请考虑下面的示例：

    • 应用只需读取已登录用户的个人资料信息。 应用只需要 User.Read 权限，这是访问已登录用户信息的最低特权权限。 授予应用 User.ReadWrite 权限会使其特权过大，因为应用不需要更新用户的配置文件。
    • 应用需要在没有登录用户的情况下读取租户中的组。 应用只需要 GroupMember.Read.All 应用程序权限，这是在没有登录用户的情况下读取租户中的组的最低特权权限。
    • 应用需要读取或写入已登录用户的日历。 应用管理动态作业，并从用户的 Outlook 日历同步，使应用保持最新状态，以便为用户计划作业。 尽管 获取 用户的日历数据需要 Calendars.Read，但使用计划作业 更新 日历需要更高的特权权限 Calendars.ReadWrite。 在这种情况下，应用应请求 Calendars.ReadWrite。

    向应用程序授予比所需更多的特权是一种糟糕的安全做法，它会增加应用的攻击面，并使其受到未经授权和意外的数据或操作访问。 此外，请求超过所需权限可能会导致用户不同意应用，从而影响应用的采用和使用。

    在向应用分配和授予Microsoft Graph 权限时，应用最小特权原则。 有关详细信息，请参阅 使用最低特权原则增强安全性 和 生成通过权限和同意保护标识的应用。

    谨慎使用的权限

    某些Microsoft Graph 权限授予对范围更广的数据或操作的访问权限。 请谨慎使用此类权限。 例如，Directory.AccessAsUser.All 权限是授予对跨Microsoft Entra ID几乎所有 API 操作的访问权限的最高特权委派权限。 Directory.ReadWrite.All 权限在特权排名中名列第二。 Directory.Read.All 是Microsoft Entra ID资源的最高特权只读权限。 应谨慎使用这些权限，并且仅在必要时使用。 请始终改用特权较低的选项权限。

    在与Microsoft Entra ID资源相关的 API 参考文档中，可能会有意从支持访问 API 的权限表中排除其中一些较高特权的权限。

    此外，全局管理员角色是 Microsoft Entra ID 中特权最高的内置角色。 在 API 参考文档中，此角色被有意排除在支持访问 API 的角色列表中，而支持较低特权的角色。

    每个应用请求的权限限制

    Microsoft Entra ID限制客户端应用可以请求和同意的权限数。 这些限制取决于 signInAudience 应用的值，如 应用清单中所示。

    signInAudience 允许的用户 应用可以请求的最大权限 应用可以请求的最大 Microsoft Graph 权限 单个请求中可同意的最大权限
    AzureADMyOrg 注册应用的组织中的用户 400 400 大约 155 个委派权限和大约 300 个应用程序权限
    AzureADMultleOrgs 任何Microsoft Entra组织中的用户 400 400 大约 155 个委派权限和大约 300 个应用程序权限
    PersonalMicrosoftAccount 消费者用户（如 Outlook.com 或 Live.com 帐户） 30 30 30
    AzureADandPersonalMicrosoftAccount 使用者用户和来自任何Microsoft Entra组织的用户 30 30 30

    通过 Microsoft Graph 检索权限 ID

    若要使用 Azure CLI、PowerShell 或基础结构即代码框架设置权限，可能需要要使用的权限的标识符，而不是名称。 权限参考列出了所有 Microsoft Graph 权限的 ID。 或者，可以通过 Microsoft Graph 中的 获取 servicePrincipal API 以编程方式读取有关所有 Microsoft Graph 权限的信息。 以下示例显示了一个请求。

    GET https://graph.microsoft.com/v1.0/servicePrincipals(appId='00000003-0000-0000-c000-000000000000')?$select=id,appId,displayName,appRoles,oauth2PermissionScopes,resourceSpecificApplicationPermissions

    appRoles、oauth2PermissionScopes 和 resourceSpecificApplicationPermissions 对象分别存储应用程序、委托和资源特定的许可权限。

    相关内容