Microsoft Graph 权限范围

Microsoft Graph 公开了 OAuth 2.0 权限范围,用于控制应用的资源访问权限。作为开发者,你可以指定与应用所需访问权限相对应的权限范围。(如果使用的是 Azure AD 身份验证,通常通过 Azure 管理门户执行此操作。如果使用的是 Azure AD v2.0 终结点,则可在运行时期间动态请求权限。)

登录后,用户或管理员将有机会同意允许你的应用访问属于你配置的权限范围的资源。出于这个原因,应选择提供应用所需的最小权限级别的权限范围。有关如何为应用以及在同意流程中配置权限的详细信息,请参阅将应用程序与 Azure Active Directory 集成

注意:某些 Microsoft Graph 权限(如与组和任务相关的权限)不适用于个人帐户。

仅限应用与委派权限

权限范围可以仅限应用,也可以是委托的范围。仅限应用的范围(也称为应用角色)授予应用该范围提供的整套权限。仅限应用的范围通常由无需登录用户在场的情况下作为服务运行的应用所使用。

委派的权限范围针对的是代表用户运行的应用。这些范围将委派登录用户的权限,使应用作为该用户运行。授予应用程序的实际权限将是范围授予的权限和登录用户所拥有的权限的最小权限组合(交集)。例如,如果权限范围授予写入所有目录对象的委托权限,但登录用户只有更新自身用户个人资料的权限,那么应用将只能写入登录用户的个人资料,而无法写入其他对象。

注意:对于组来说,只有一部分与核心组管理和管理相关的组 API 才同时支持仅限应用权限和委派权限。其他所有的组 API 成员仅支持委派权限。有关示例,请参阅已知问题

用户和组的完整和基本个人资料

用户或组的完整个人资料(或个人资料)包括所有实体的声明属性。因为该个人资料可能包含敏感目录信息或个人身份信息 (PII),多个范围将限制应用访问有限的属性集,称为基本个人资料。对于用户,基本个人资料仅包括以下属性:

  • 显示名称
  • 姓和名
  • 照片
  • 电子邮件地址

对于组,基本个人资料仅包含显示名称。

权限范围详细信息

必须将应用配置为具有访问 Microsoft Graph 资源必需的权限。各个资源的权限进行了范围划分,读取权限、写入权限或者两者皆有。

下表列出了 Microsoft Graph 的权限范围,并说明了每个范围授予的访问权限。

  • 范围列中列出了范围名称。范围名称采用 resource.operation.constraint 的形式,例如,Group.ReadWrite.All。如果约束为“全部”,则范围将授予应用对目录中的所有指定资源(组)执行操作(读写)的能力;否则,范围仅允许对登录用户的个人资料执行操作。范围可能会为指定的操作授予有限的权限。请参阅说明列获取详细信息。
  • 权限列显示范围在 Azure 门户上的显示方式。
  • 说明列描述由范围授予的完整权限集。对于委托范围而言,授予应用程序的实际访问权限将是范围授予的访问权限和登录用户的权限的最小权限组合(交集)。
  • 根据权限是否需要管理员的许可,对范围进行分组。

注意:请参阅 v1.0beta 权限范围限制的 已知问题

需要管理员同意的权限

范围 权限 说明
Directory.AccessAsUser.All 以登录用户身份访问目录 允许应用以登录用户身份访问目录中的信息。
Directory.Read.All 读取目录数据 允许应用读取组织目录中的数据,如用户、组和应用。
Directory.ReadWrite.All 读取和写入目录数据 允许应用读取和写入组织目录中的数据,如用户和组。不允许删除用户或组。它不允许应用删除用户或组,或重置用户密码。
Group.Read.All 读取所有组 允许应用代表登录用户列出组,并读取其属性以及所有组成员身份。此外,还允许应用读取登录用户可以访问的所有组的日历、 对话、 文件和其他组内容。
Group.ReadWrite.All 读取和写入所有组 允许应用代表登录用户创建组并读取所有组属性和成员身份。此外,还允许组所有者管理他们的组并允许组成员更新组内容。
User.Read.All 读取所有用户的完整个人资料 与 User.ReadBasic.All 相同,区别是它允许应用读取组织中所有用户的完整个人资料,并且读取经理和直接下属等导航属性时,完整个人资料包括 User 实体所有声明的属性。若要读取用户所在的组,应用还将需要 Group.Read.All 或 Group.ReadWrite.All。
User.ReadWrite.All 读取和写入所有用户的完整个人资料 允许应用代表登录用户读取和写入组织中其他用户的整套个人资料属性、下属和经理。

无需征得管理员同意的权限

范围 权限 说明
Calendars.Read 读取用户日历 允许应用读取用户日历中的事件。
Calendars.Read.Shared 读取用户日历和共享日历 允许应用读取用户可以访问的所有日历(包括委派日历和共享日历)中的事件。
Calendars.ReadWrite 具有对用户日历的完整访问权限 允许应用创建、读取、更新和删除用户日历中的事件。
Calendars.ReadWrite.Shared 读取和写入用户日历和共享日历 允许应用创建、读取、更新和删除用户有权访问的所有日历中的事件。这包括委派日历和共享日历。
Contacts.Read 读取用户联系人 允许应用读取用户联系人。
Contacts.Read.Shared 读取用户联系人和共享联系人 允许应用读取用户有权访问的联系人,包括用户个人联系人和共享联系人。
Contacts.ReadWrite 具有对用户联系人的完整访问权限 允许应用创建、读取、更新和删除用户联系人。
Contacts.ReadWrite.Shared 读取和写入用户联系人和共享联系人 允许应用创建、读取、更新和删除用户有权访问的联系人,包括用户个人联系人和共享联系人。
Files.Read 读取用户文件以及与用户共享的文件 允许应用读取登录用户的文件以及与该用户共享的文件。
Files.Read.All 读取用户可以访问的所有文件 允许应用读取登录用户可以访问的所有文件。
Files.Read.Selected 读取用户选择的文件 允许应用读取用户选择的文件。用户选择文件后,应用具有几个小时的访问权限。
Files.ReadWrite 具有访问用户文件以及与用户共享的文件的完整权限 允许应用读取、创建、更新和删除登录用户的文件以及与该用户共享的文件。
Files.ReadWrite.All 具备对用户可以访问的所有文件的完全访问权限 允许应用读取、创建、更新和删除登录用户可以访问的所有文件。
Files.ReadWrite.AppFolder 具备对应用程序文件夹的完全访问权限 允许应用读取、创建、更新和删除应用程序文件夹中的文件。
Files.ReadWrite.Selected 读取和写入用户选择的文件 允许应用读取和写入用户选择的文件。用户选择文件后,应用具有几个小时的访问权限。
Mail.Read 读取用户邮件 允许应用读取用户邮箱中的电子邮件。
Mail.Read.Shared 读取用户邮件和共享邮件 允许应用读取用户可以访问的邮件,包括用户个人邮件和共享邮件。
Mail.ReadWrite 对用户邮件的读写权限 允许应用创建、读取、更新和删除用户邮箱中的电子邮件。不包括发送电子邮件的权限。
Mail.ReadWrite.Shared 读取和写入用户邮件和共享邮件 允许应用创建、读取、更新和删除用户有权访问的邮件,包括用户个人邮件和共享邮件。不包括邮件发送权限。
Mail.Send 以用户身份发送邮件 允许应用以组织用户身份发送邮件。
Mail.Send.Shared 代表他人发送邮件 允许应用以登录用户身份发送邮件,包括代表他人发送邮件。
MailboxSettings.ReadWrite 读取和写入用户邮箱设置 允许应用创建、读取、更新和删除用户邮箱设置。不包括邮件发送权限。
offline_access 随时访问用户数据(预览) 允许应用读取和更新用户数据,即使用户暂时没有使用该应用,也是如此。
openid 让用户登录(预览) 允许用户以其工作或学校帐户登录应用,并允许应用查看用户的基本个人资料信息。
User.Read 登录并读取用户个人资料 允许用户登录应用,并允许应用读取登录用户的个人资料。整套个人资料包括“User”实体所有声明的属性。应用无法读取经理或直接下属导航属性。此外,还允许应用读取登录用户的以下基本公司信息(通过 TenantDetail 对象):租户 ID、租户显示名称和已验证的域。
User.ReadWrite 对用户个人资料的读写权限 允许应用读取您的个人资料。此外,它还允许应用代表您更新您的个人资料。
User.ReadBasic.All 读取所有用户的基本个人资料 允许应用代表登录用户读取组织中所有用户的基本个人资料。以下属性包括用户的基本个人资料:显示名称、名字和姓氏、照片和电子邮件地址。若要读取用户所在的组,应用还将需要 Group.Read.All 或 Group.ReadWrite.All。

需要征得管理员同意的仅限应用权限

范围 权限 说明
Calendars.Read 读取所有邮箱中的日历 允许应用在没有登录用户的情况下读取所有日历的事件。
Calendars.ReadWrite 读取和写入所有邮箱中的日历 允许应用在没有登录用户的情况下创建、读取、更新和删除所有日历的事件。
Contacts.Read 读取所有邮箱中的联系人 允许应用在没有登录用户的情况下读取所有邮箱中的所有联系人。
Contacts.ReadWrite 读取和写入所有邮箱中的联系人 允许应用在没有登录用户的情况下创建、读取、更新和删除所有邮箱中的全部联系人。
Device.ReadWrite.All 读取和写入设备 允许应用在没有登录用户的情况下读取和写入所有设备属性。不允许创建设备、删除设备或更新设备备用安全标识符。
Directory.Read.All 读取目录数据 允许应用在没有登录用户的情况下读取组织目录中的数据(如用户、组和应用)。
Directory.ReadWrite.All 读取和写入目录数据 允许应用在没有登录用户的情况下读取和写入组织目录中的数据(如用户和组)。不允许删除用户或组。
Files.Read.All 读取用户可以访问的所有文件 允许应用在没有登录用户的情况下读取所有网站集中的全部文件。
Files.ReadWrite.All 具备对用户可以访问的所有文件的完全访问权限 允许应用在没有登录用户的情况下读取、创建、更新和删除所有网站集中的全部文件。
Group.Read.All 读取所有组 允许应用在没有登录用户的情况下读取所有组的成员。请注意,并非所有组 API 都支持使用仅限应用权限进行访问。有关示例,请参阅已知问题
Group.ReadWrite.All 读取和写入所有组 允许应用创建组、读取和更新组成员以及删除组。应用可以在没有登录用户的情况下执行所有这些操作。请注意,并非所有组 API 都支持使用仅限应用权限进行访问。有关示例,请参阅已知问题
Mail.Read 读取所有邮箱中的邮件 允许应用在没有登录用户的情况下读取所有邮箱中的邮件。
Mail.ReadWrite 读取和写入所有邮箱中的邮件 允许应用在没有登录用户的情况下创建、读取、更新和删除所有邮箱中的邮件。不包括发送电子邮件的权限。
Mail.Send 以任意用户身份发送邮件 允许应用在没有登录用户的情况下以任意用户身份发送邮件。
MailboxSettings.ReadWrite 读取和写入所有用户邮箱设置 允许应用在没有登录用户的情况下创建、读取、更新和删除用户邮箱设置。不包括邮件发送权限。
Member.Read.Hidden 读取所有隐藏成员 允许应用在没有登录用户的情况下读取隐藏的组和管理单元中的成员。
Reports.Read.All 读取所有使用情况报告 允许应用在没有登录用户的情况下读取所有服务使用情况报告。提供使用情况报告的服务包括 Office 365 和 Azure Active Directory。
User.Read.All 读取所有用户的完整个人资料 允许应用在没有登录用户的情况下读取组织中其他用户的整套个人资料属性、组成员身份、下属和经理。
User.ReadWrite.All 读取和写入所有用户的完整个人资料 允许应用在没有登录用户的情况下读取和写入组织中其他用户的整套个人资料属性、组成员身份、下属和经理。

处于预览阶段的权限范围

需要征得管理员同意的权限(预览)

范围 权限 说明
IdentityRiskEvent.Read.All 读取标识风险事件信息(预览) 允许应用代表登录用户为组织中所有用户读取标识风险事件信息。
DeviceManagementServiceConfiguration.Read.All 读取 Microsoft Intune 配置(预览) 允许应用读取 Microsoft Intune 服务属性,其中包括设备注册和第三方服务连接配置。
DeviceManagementServiceConfiguration.ReadWrite.All 读取和写入 Microsoft Intune 配置(预览) 允许应用读取和写入 Microsoft Intune 服务属性,其中包括设备注册和第三方服务连接配置。
DeviceManagementConfiguration.Read.All 读取 Microsoft Intune 设备配置和策略(预览) 允许应用读取 Microsoft Intune 管理的设备配置的属性和设备符合性策略以及它们对组的分配情况。
DeviceManagementConfiguration.ReadWrite.All 读取和写入 Microsoft Intune 设备配置和策略(预览) 允许应用读取和写入 Microsoft Intune 管理的设备配置的属性和设备符合性策略以及它们对组的分配情况。
DeviceManagementApps.Read.All 读取 Microsoft Intune 应用(预览) 允许应用读取由 Microsoft Intune 管理的应用、应用配置和应用保护策略的属性、组分配情况和状态。
DeviceManagementApps.ReadWrite.All 读取和写入 Microsoft Intune 应用(预览) 允许应用读取和写入由 Microsoft Intune 管理的应用、应用配置和应用保护策略的属性、组分配情况和状态。
DeviceManagementRBAC.Read.All 读取 Microsoft Intune RBAC 设置(预览) 允许应用读取与基于 Microsoft Intune 角色的访问控制 (RBAC) 设置相关的属性。
DeviceManagementRBAC.ReadWrite.All 读取和写入 Microsoft Intune RBAC 设置(预览) 允许应用读取和写入与基于 Microsoft Intune 角色的访问控制 (RBAC) 设置相关的属性。
DeviceManagementManagedDevices.Read.All 读取 Microsoft Intune 设备(预览) 允许应用读取由 Microsoft Intune 管理的设备的属性。
DeviceManagementManagedDevices.ReadWrite.All 读取和写入 Microsoft Intune 设备(预览) 允许应用读取和写入由 Microsoft Intune 管理的设备的属性。不允许执行具有高影响级别的操作,例如针对设备所有者的远程擦除和密码重置。
DeviceManagementManagedDevices.PrivilegedOperations.All 在 Microsoft Intune 设备上执行影响用户的远程操作(预览) 允许应用执行高影响级别远程操作,如在由 Microsoft Intune 管理的设备上擦除设备或重置密码。

无需征得管理员同意的权限(预览)

范围 权限 说明
Notes.Create 在用户的笔记本中创建页面(预览) 允许应用代表登录用户读取笔记本和分区标题并创建新的页面、笔记本和分区。
Notes.Read 读取用户笔记本(预览) 允许应用代表登录用户查看 OneNote 笔记本和分区标题并读取所有页面。它不能查看受密码保护的分区。
Notes.Read.All 读取用户可以访问的所有笔记本(预览) 允许应用读取登录用户可以访问的所有笔记本和分区的内容。 它不能读取受密码保护的分区。
Notes.ReadWrite 读取和写入用户笔记本(预览) 允许应用代表登录用户读取笔记本和分区标题、读取所有页面、写入所有页面并创建新的页面。 它不能访问受密码保护的分区。
Notes.ReadWrite.All 读取和写入用户可以访问的所有笔记本(预览) 允许应用读取和写入登录用户可以访问的所有笔记本和分区的内容。它不能访问受密码保护的分区。
Notes.ReadWrite.CreatedByApp 有限的笔记本访问权限(预览) 允许应用代表登录用户读取笔记本和分区标题、创建新的页面。此外,还允许应用读取和更新应用所创建的页面。
People.Read 读取用户的相关人员列表(预览) 允许应用读取登录用户相关人员的排名列表。该列表包括当地联系人、来自社交网络的联系人、您所在组织的目录以及来自最近通信(例如电子邮件和 Skype)的人员。
Sites.Read.All 读取所有网站集中的项目 允许应用程序代表登录用户读取所有网站集中的文档和列表项。
Sites.ReadWrite.All 在所有网站集中读取和写入项 允许应用程序代表登录用户编辑或删除所有网站集中的文档和列表项。
Tasks.Read 读取用户任务 允许应用读取用户任务。
Tasks.Read.Shared 读取用户任务和共享任务 允许应用读取用户有权访问的任务,包括用户个人任务和共享任务。
Tasks.ReadWrite 创建、读取、更新和删除用户任务和计划(预览) 允许应用创建、读取、更新和删除分配给登录用户或与登录用户共享的任务和计划(以及项目中的任务)。
Tasks.ReadWrite.Shared 读取和写入用户任务和共享任务 允许应用创建、读取、更新和删除用户有权访问的任务,包括用户个人任务和共享任务。

权限范围应用场景

以下是使用 UserGroup 资源及其对应的所需范围的一些应用场景。下表显示了应用能够执行特定操作所需的权限范围。请注意,在某些情况下,应用能否执行某些操作将取决于权限范围是仅限应用还是委托的范围,并且如果是委托的权限范围,则取决于登录用户的权限。

使用用户资源和所需范围的访问场景

涉及用户的应用任务 必需的作用域 权限
应用想要读取其他用户的基本信息(仅限显示名称和图片),例如展示人员挑选经验 User.ReadBasic.All 读取所有用户的基本个人资料
应用想要读取登录用户的完整用户个人资料(请参见直接下属和经理等) User.Read 允许登录和读取用户个人资料
应用想要读取所有用户的完整用户个人资料 User.Read.All 读取所有用户的完整个人资料
应用要读取登录用户的文件、邮件和日历信息 User.Read, Files.Read, Mail.Read, Calendars.Read 允许登录和读取用户配置文件、读取用户文件、读取用户邮件、读取用户日历
应用想要读取登录用户(我)的文件,以及其他用户与登录用户(我)共享的文件。 User.Read, Files.Read, Sites.Read.All 允许登录和读取用户个人资料、读取用户文件、读取所有网站集中的项目
应用想要读取和写入登录用户的完整用户个人资料 User.ReadWrite 对用户个人资料的读写权限
应用想要读取和写入所有用户的完整用户个人资料 User.ReadWrite.All 读取和写入所有用户的完整个人资料
应用要读取和写入登录用户的文件、邮件和日历信息 User.ReadWrite, Files.ReadWrite, Mail.ReadWrite, Calendars.ReadWrite 对用户个人资料的读写权限、对用户个人资料的读写权限、对用户邮件的读写权限、具有访问用户日历的完整权限

使用组资源和所需范围的访问场景

涉及组的应用任务 必需的作用域 权限
应用想要读取基本组信息(仅限显示名称和图片),例如展示组挑选经验 Group.Read.All 读取所有组
应用想要读取所有 Office 365 组中的全部内容(包括文件、对话)。它还需要显示组成员,同时能够更新组成员(若是所有者)。 Group.Read.All 读取所有网站集中的项、读取所有组
应用想要读取和写入所有 Office 365 组中的全部内容(包括文件、对话)。它还需要显示组成员,同时能够更新组成员(若是所有者)。 Group.ReadWrite.All, Sites.ReadWrite.All 读取和写入所有组、编辑或删除所有网站集中的项
应用想要发现(找到)Office 365 组。它允许用户搜索特定组,然后从枚举列表中选择一个组,从而允许用户加入组。 Group.ReadWrite.All 读取和写入所有组
应用想要通过 AAD Graph 创建一个组 Group.ReadWrite.All 读取和写入所有组