Microsoft Graph 权限概述

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

向应用授予通过 Microsoft Graph 访问和处理数据所需的权限的一种方法是为其分配 Microsoft Graph 权限

本文介绍 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 Entra RBAC)获得权限。

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

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

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

注意

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

应用程序权限

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

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

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

  • 为应用分配要管理的资源的所有权时。
  • 为应用分配Microsoft Entra内置或自定义管理角色时。

注意

通过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 资源。 UserApplication、 或 Group
    {operation} 指对资源公开的数据允许的 Microsoft 图形 API操作。 例如, Read 仅用于读取操作,或者 ReadWrite 对于读取、创建、更新和删除操作。 ReadReadBasicReadWriteCreateManageMigrate
    {constraint} 确定应用在目录中具有的潜在访问范围。 此值可能不会显式声明。 未声明时,默认约束仅限于已登录用户拥有的数据。 All, AppFolder, OwnedBy, Selected, Shared, Hidden

    示例:

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

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

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

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

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

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

    若要读取组成员(即用户)的基本属性,应用至少需要 User.Read.All 权限。 若要读取属于组的组成员的基本属性,应用至少需要 Group.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 权限会使其特权过大,因为应用不需要更新用户的配置文件。
    • 应用需要在没有登录用户的情况下读取租户中的组。 应用只需要 Group.Read.All 应用程序权限,这是在没有登录用户的情况下读取租户中的组的最低特权权限。
    • 应用需要读取或写入已登录用户的日历。 应用管理动态作业,并从用户的 Outlook 日历同步,使应用保持最新状态,以便为用户计划作业。 尽管 获取 用户的日历数据需要 Calendars.Read,但使用计划作业 更新 日历需要更高的特权权限 Calendars.ReadWrite。 在这种情况下,应用应请求 Calendars.ReadWrite

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

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

    每个应用请求的权限限制

    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 中的 Get 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
    

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