Table of contents

权限范围 | Graph API 概念Permission scopes | Graph API concepts

Bryan Lamos|上次更新日期: 2018/6/19
|
2 参与人员

适用范围: 图形 API | Azure Active Directory (AD)Applies to: Graph API | Azure Active Directory (AD)

Graph API 公开了 OAuth 2.0 权限范围,此范围用于控制应用对客户目录数据的访问权限。The Graph API exposes OAuth 2.0 permission scopes that are used to control access that an app has to customer directory data.作为开发人员,可以将应用的权限范围配置为其要求的适当访问权限。As a developer, you configure your app with the permission scopes appropriate to the access that it requires.通常,可以通过 Azure 门户执行此操作。Typically you do this through the Azure portal.登录期间,用户或管理员有机会同意允许应用使用配置的权限范围访问其目录数据。During sign-in, users or administrators are given an opportunity to consent to allow your app access to their directory data with the permission scopes you configured.因此,应选择具有应用所需的最低权限级别的权限范围。For this reason, you should choose permission scopes that provide the least level of privilege needed by your app.有关如何配置应用的权限以及同意过程的详细信息,请参阅 Integrating Applications with Azure Active Directory(将应用程序与 Azure Active Directory 集成)For more details on how to configure permissions for your app and on the consent process, see Integrating Applications with Azure Active Directory.

重要事项

强烈建议使用 Microsoft Graph 代替 Azure AD Graph API 来访问 Azure Active Directory 资源。We strongly recommend that you use Microsoft Graph instead of Azure AD Graph API to access Azure Active Directory resources.现在我们的开发工作将重点集中在 Microsoft Graph 上,没有计划对 Azure AD Graph API 进行进一步的改进。Our development efforts are now concentrated on Microsoft Graph and no further enhancements are planned for Azure AD Graph API.Azure AD Graph API 仍适用的方案数量非常有限;有关详细信息,请参阅 Office 开发人员中心中的博客文章 Microsoft Graph 或 Azure AD GraphThere are a very limited number of scenarios for which Azure AD Graph API might still be appropriate; for more information, see the Microsoft Graph or the Azure AD Graph blog post in the Office Dev Center.

权限范围概念 Permission scope concepts

仅应用与委托的范围App-only vs. delegated scopes

权限范围可以是仅应用或委托的范围。Permission scopes can be either app-only or delegated.仅应用范围(也称为应用角色)可以授予应用由该范围提供的全部特权。App-only scopes (also known as app roles) grant the app the full set of privileges offered by the scope.如果没有已登录用户,则作为服务运行的应用通常会使用仅应用范围。App-only scopes are typically used by apps that run as a service without a signed-in user being present.委托的权限范围适用于用户登录的应用。Delegated permission scopes are for apps that a user signs in to.这些范围可以向应用委托已登录用户特权,允许应用充当已登录用户的角色。These scopes delegate the privileges of the signed-in user to the app, allowing the app to act as the signed in user.应用获得的实际特权至少应为通过该范围授予的特权和已登录用户拥有的特权的特权组合(交叉部分)。The actual privileges granted to the app will be the least privileged combination (the intersection) of the privileges granted by the scope and those possessed by the signed-in user.例如,如果权限范围授予写入所有目录对象的委托特权,但已登录用户只有更新其自身用户配置文件的特权,则该应用将只能写入已登录用户配置文件,而不能写入任何其他对象。For example, if the permission scope grants delegated privileges to write all directory objects, but the signed-in user has privileges only to update their own user profile, the app will only be able to write the signed-in user's profile but no other objects.

用户和组的完整和基本配置文件Full and basic profiles for users and groups

用户的完整配置文件包括该实体已声明的所有属性。The full profile (or profile) of a User or a Group includes all of the entity's declared properties.由于配置文件可能包含敏感的目录信息或个人身份信息 (PII),因此,有好几个范围都限制了应用对一组有限属性(称为基本配置文件)的访问。Because the profile may contain sensitive directory information or personally identifiable information (PII), several scopes constrain app access to a limited set of properties known as a basic profile.对用户而言,基本配置文件仅包括以下属性:显示名称、名字和姓氏、照片和电子邮件地址。For users, the basic profile includes only the following properties: display name, first and last name, photo, and email address.对组而言,基本配置文件仅包含显示名称。For groups, the basic profile contains only the display name.

权限范围详细信息 Permission scope details

下表列出了 Graph API 权限范围,并介绍了每个范围授予的访问权限。The following table lists the Graph API permission scopes and explains the access granted by each.

  • “范围”列列出了范围名称。The Scope column lists the scope name.范围名称采取 resource.operation.constraint 的形式;例如,Group.ReadWrite.All。Scope names take the form resource.operation.constraint; for example, Group.ReadWrite.All.如果约束是“All”,则范围允许应用在目录中所有指定的资源(组)上执行操作 (ReadWrite);否则,范围将仅允许在已登录用户的配置文件上执行操作。If the constraint is "All", the scope grants the app the ability to perform the operation (ReadWrite) on all of the specified resources (Group) in the directory; otherwise, the scope only permits the operation on the profile of the signed-in user.范围可以授予指定操作的有限特权,有关详细信息,请参见“说明”列。Scopes may grant limited privileges for the specified operation, see the Description column for details.
  • “权限”列显示了 Azure 门户中范围的显示方式。The Permission column shows how the scope is displayed on the Azure portal.
  • “说明”列描述了范围授予的全部特权。The Description column describes the full set of privileges granted by the scope.对于委托范围,应用获得的实际应用获得的实际特权至少应为通过该范围授予的访问权限和已登录用户的特权的特权组合(交叉部分)。For delegated scopes, the actual access granted to the app will be the least privileged combination (intersection) of the access granted by the scope and the privileges of the signed-in user.
作用域Scope权限Permission描述Description范围类型Scope Type需要管理员同意Requires Administrator Consent
User.ReadUser.Read允许登录和读取用户配置文件Enable sign-in and read user profile允许用户登录到应用,并允许应用读取已登录用户的完整配置文件。Allows users to sign in to the app and allows the app to read the full profile of the signed-in user.完整的配置文件包括用户实体已声明的所有属性。The full profile includes all of the declared properties of the User entity.借助 User.Read,应用可以读取登录用户的以下基本公司信息(通过 TenantDetail 对象):租户 ID、租户显示名称和已验证的域。User.Read allows the app to read the following basic company information of the signed-in user (through the TenantDetail object): tenant ID, tenant display name, and verified domains.应用无法读取导航属性,如管理器或直接下属。The app cannot read navigation properties, such as manager or direct reports.应用无法读取用户的密码。The app cannot read the user's password.委派delegatedNo
User.ReadBasic.AllUser.ReadBasic.All读取所有用户的基本配置文件Read all users' basic profiles允许应用代表已登录用户读取组织中所有用户的基本配置文件。Allows the app to read the basic profile of all users in the organization on behalf of the signed-in user.以下属性组成了用户的基本配置文件:显示名称、名字和姓氏、照片和电子邮件地址。The following properties comprise a user’s basic profile: display name, first and last name, photo, and email address.若要读取用户所在的组,该应用将还需要 Group.Read.All 或 Group.ReadWrite.All。To read the groups that a user is a member of, the app will also require Group.Read.All or Group.ReadWrite.All.委派delegatedNo
User.Read.AllUser.Read.All读取所有用户的完整配置文件Read all users' full profiles与 User.ReadBasic.All 相同,但还允许应用读取组织中所有用户的完整配置文件,且可读取经理及直接下属等导航属性。Same as User.ReadBasic.All, except that it allows the app to read the full profile of all users in the organization and when reading navigation properties like manager and direct reports.完整的配置文件包括用户实体已声明的所有属性。The full profile includes all of the declared properties of the User entity.若要读取用户所在的组,该应用还将需要 Group.Read.All 或 Group.ReadWrite.All。To read the groups that a user is a member of, the app will also require either Group.Read.All or Group.ReadWrite.All.应用无法读取用户的密码。The app cannot read users' passwords.委派delegatedYes
Group.Read.AllGroup.Read.All读取所有组(预览)Read all groups (preview)允许应用代表已登录用户读取组织中所有组的基本配置文件。Allows the app to read the basic profile of all groups in the organization on behalf of the signed-in user.该应用还可以读取某组是其成员的组的基本配置文件。The app can also read the basic profile of the groups that a group is a member of.组的基本配置文件仅包括组的显示名称。The basic profile for a group includes only the group’s display name.若要读取组成员的配置文件信息,该应用还需要 User.ReadBasic 或 User.Read.All。To read the profile information of a group’s members, the app will also require either User.ReadBasic or User.Read.All.委派delegatedYes
Group.ReadWrite.AllGroup.ReadWrite.All读取和写入所有组(预览)Read and write all groups (preview)允许应用代表已登录用户读取组织中所有组的完整配置文件以及创建和更新组。Allows the app to read the full profile of all groups in the organization, as well as to create and update groups on behalf of the signed-in user.该应用还可以读取某组是其成员的组的完整配置文件。The app can also read the full profile of the groups that a group is a member of.完整配置文件包括实体已声明的所有属性。The full profile includes all of the declared properties of the Group entity.若要读取组的成员的配置文件或更新组成员,该应用还需要 User.ReadBasic 或 User.Read.All。To read the profiles of or update a group’s members, the app will also require either User.ReadBasic or User.Read.All.委派delegatedYes
Device.ReadWrite.AllDevice.ReadWrite.All读取和写入所有设备Read and write all devices允许应用在无用户登录的情况下读取和写入全部设备属性。Allows the app to read and write all device properties without a signed in user.不允许创建设备、删除设备以及更新设备备用安全标识符。Does not allow device creation, device deletion, or update of device alternative security identifiers.仅限应用app-onlyYes
Directory.Read.AllDirectory.Read.All读取目录数据Read directory data允许应用读取组织目录中的所有数据,如用户、组、应用以及其关联的导航属性。Allows the app to read all of the data in the organization's directory, such as users, groups, and apps, and their associated navigation properties.注意:如果在用户自己的组织租户内注册应用程序,则用户可以同意需要此权限的应用程序。Note: Users may consent to applications that require this permission if the application is registered in their own organization’s tenant.仅限应用、委托app-only, delegatedYes
Directory.ReadWrite.AllDirectory.ReadWrite.All读取和写入目录数据Read and write directory data允许应用读取组织目录中的所有数据。Allows the app to read all of the data in the organization's directory.允许应用创建和更新用户和组,以及更新导航属性,但禁止删除用户或组。Allows the app to create and update users and groups, and update their navigation properties, but prohibits user or group deletion.还允许应用在应用程序上定义架构扩展。Also allows the app to define schema extensions on applications.有关特权的详细列表,请参见下面的 Directory.ReadWrite.All 特权明细For a detailed list of privileges, see Directory.ReadWrite.All privileges detail below.仅限应用、委托app-only, delegatedYes
Directory.AccessAsUser.AllDirectory.AccessAsUser.All使用已登录用户的身份访问目录Access directory as the signed-in user向应用授予与已登录用户相同的对组织目录中数据的访问权限。Allows the app the same access to data in the organization's directory as the signed-in user.注意:本机客户端应用可以使用户同意此权限,但 Web 应用需要管理员同意。Note: A native client app can have the user consent to this permission however, a web app requires administrator consent.委派delegatedYes

注意:默认情况下,使用 Azure 门户创建应用时,Azure AD 会为其分配 User.Read 委托的权限范围。Note: By default, when you create an app using the Azure portal, Azure AD assigns it a delegated permission scope of User.Read.

Directory.ReadWrite.All 特权明细Directory.ReadWrite.All privileges detail

Directory.ReadWrite.All 权限范围授予以下特权:The Directory.ReadWrite.All permission scope grants the following privileges:

  • 完整读取所有目录对象(已声明的属性和导航属性)Full read of all directory objects (both declared properties and navigation properties)
  • 创建和更新用户Create and update users
  • 禁用和启用用户(但不是公司管理员)Disable and enable users (but not company administrator)
  • 设置用户备用安全 ID(但不是管理员)Set user alternative security id (but not administrators)
  • 创建和更新组Create and update groups
  • 管理组成员身份Manage group memberships
  • 更新组所有者Update group owner
  • 管理许可证分配Manage license assignments
  • 在应用程序上定义架构扩展Define schema extensions on applications
  • 允许在创建用户时设置密码。Allows password to be set when creating a user.
  • 注意:无权重置用户密码Note: No rights to reset user passwords
  • 注意:无权读取用户密码Note: No rights to read user passwords
  • 注意:无权删除实体(包括用户或组)Note: No rights to delete entities (including users or groups)
  • 注意:特意排除创建或更新上面未列出的实体。Note: Specifically excludes create or update for entities not listed above.这些实体包括:Application、Oauth2PermissionGrant、AppRoleAssignment、Device、ServicePrincipal、TenantDetail、domains 等。This includes: Application, Oauth2PermissionGrant, AppRoleAssignment, Device, ServicePrincipal, TenantDetail, domains, etc.

权限范围方案 Permission scope scenarios

下表显示了应用能够执行特殊操作所需的权限范围。The following table shows the permission scopes needed for an app to be able to perform specific operations.请注意,在某些情况下,应用执行某些操作的能力将取决于权限范围是仅限应用还是委托,如果是委托的权限范围,则取决于已登录用户的特权。Note that in some cases the ability of the app to perform some operations will depend on whether the permission scope is app-only or delegated, and, in the case of delegated permission scopes, on the privileges of the signed-in user.

方案Scenario需要访问权限Access Required需要权限范围Permission Scope Needed
登录并显示带用户名称和缩略图照片的磁贴。Sign-in and show a tile with the user's name and thumbnail photo.读取已登录用户的完整配置文件。Read full profile of the signed-in user.
读取公司基本信息Read basic company information.
User.ReadUser.Read
基本的人员选取器。Basic people picker.读取代表已登录用户的所有用户的基本配置文件。Read basic profile of all users on behalf of the signed-in user.User.ReadBasic.AllUser.ReadBasic.All
具有完整配置文件的人员选取器。People picker with full profile.同上,但有权访问代表已登录用户的用户的完整配置文件。Same as above but access to full profile of users on behalf of the signed-in user.User.Read.AllUser.Read.All
组织图表导航器。Org chart navigator.读取代表已登录用户的所有用户、其管理器和直接下属的完整配置文件。Read full profile of all users, their managers, and direct reports on behalf of the signed-in user.User.Read.AllUser.Read.All
包括应用权限控制的人员选取器。People picker that includes groups for access control to your app.

组和成员身份查看器。Group and membership viewer.
读取代表已登录用户的所有组和用户的基本配置文件。Read basic profile of all groups and users on behalf of the signed-in user.
读取用户管理器和直接下属的基本配置文件。Read basic user profiles for users' manager and direct reports.
读取用户的组成员身份的基本配置文件。Read basic profile of users' group memberships.
读取组的组成员身份的基本配置文件。Read basic profile of groups' group memberships.
读取组成员的基本配置文件。Read basic profile of groups' members
User.ReadBasic.All 和 Group.Read.AllUser.ReadBasic.All and Group.Read.All
显示已登录用户和用户管理器、直接下属和组成员身份的配置文件。Show the profile of the signed-in user and the user's manager, direct reports, and group memberships.使用 me 操作进行读取:Use me operations to read:
已登录用户的完整配置文件。The full profile of the signed-in user.
已登录用户的管理器和直接下属的完整配置文件。The full profile of the signed-in user's manager and direct reports.
已登录用户所在的组的基本配置文件。The basic profile of the groups that the signed-in user is a member of.

注意:两个范围的组合要比此处所述的 me 操作授予的访问权限多。Note: The combination of the two scopes grants more access than that noted here for me operations.
User.Read.All 和 Group.Read.AllUser.Read.All and Group.Read.All
允许用户创建和管理组的组管理服务。Group management service that allows users to create and manage groups.读取代表已登录用户的所有组和用户的完整配置文件。Read full profile of all groups and users on behalf of the signed-in user.
读取用户管理器和直接下属的完整配置文件。Read full profiles for users' manager and direct reports.
读取用户的组成员身份的完整配置文件。Read full profile of users' group memberships.
读取组的组成员身份的完整配置文件。Read full profile of groups' group memberships.
读取组成员的完整配置文件。Read full profile of groups' members.
创建和更新组及其导航属性(成员)。Create and update groups and their navigation properties (members).
User.Read.All 和 Group.ReadWrite.AllUser.Read.All and Group.ReadWrite.All
读取所有目录对象(包括导航属性)。Read all directory objects (including navigation properties).Directory.Read.AllDirectory.Read.All
读取所有目录对象(包括导航属性)。Read all directory objects (including navigation properties).
创建和更新用户和组对象。Create and update user and group objects.
不允许删除用户或组。No user or group deletion.

注意:这里只列出了部分已授予特权。Note: Not all privileges granted are listed here.
Directory.ReadWrite.AllDirectory.ReadWrite.All
充当已登录用户角色。Act as the signed-in user.读取和写入代表已登录用户的目录对象(包括导航属性)。Read and write directory objects (including navigation properties) on behalf of the signed-in user.Directory.AccessAsUser.AllDirectory.AccessAsUser.All

管理员、用户和来宾用户的默认访问权限 Default access for administrators, users, and guest users

下表列出了(全局)管理员、用户和来宾在目录中的默认访问权限。The following table lists the default access of (global) administrators, users, and guest users in the directory.默认访问权限可能会根据该目录的配置设置和/或用户在一个或多个目录角色中的成员身份进一步补充或限制。The default access may be further augmented or restricted based on configuration settings for the directory and/or a user's membership in one or more directory roles.有关配置用户和来宾用户对目录数据的访问权限的详细信息,请参阅 Assigning administrator roles in Azure AD(在 Azure AD 中创建或编辑用户)For more detailed information about configuring the access of users and guest users to directory data, see Create or edit users in Azure AD.有关与各种目录角色关联的访问权限的详细信息,请参阅 Assigning administrator roles in Azure AD(在 Azure AD 中分配管理员角色)For more information about the access associated with various directory roles, see Assigning administrator roles in Azure AD.

用户类型User Type访问Access
全局管理员Global Administrator读取所有目录对象。Read all directory objects.
创建、更新和删除所有目录对象Create, Update, and Delete all directory objects
UserUser读取所有目录对象。Read all directory objects.
创建应用程序和关联的服务主体。Create applications and associated service principals.
更新其配置文件。Update their profile.
更新其所拥有的组(和成员属性)。Update groups that they own (and the members property).
更新其所拥有的应用程序和服务主体。Update applications and service principals that they own.
删除其所拥有的应用程序和服务主体。Delete applications and service principals that they own.
来宾用户Guest User读取其完整配置文件。Read their full profile.
读取所有其他用户的基本配置文件。Read the basic profiles of all other users
读取所有组的基本配置文件。Read basic profile of all groups.
读取应用程序。Read applications.
更新其配置文件的某些属性。Update some properties of their profile.
无用户或组搜索(请参见如下的来宾用户的用户和组搜索限制)。No user or group search (see User and group search limitations for guest users below).

来宾用户的用户和组搜索限制 User and group search limitations for guest users

用户和组搜索功能使应用能够通过在自定义目录中执行针对用户资源集的查询搜索任何用户或组(例如,https://graph.windows.net/myorganization/users?api-version=1.6)。User and group search capabilities allow the app to search for any user or group in the customer directory by performing queries against the users or groups resource set (for example, https://graph.windows.net/myorganization/users?api-version=1.6).管理员和用户都具有这个功能。Both administrators and users have this capability.但来宾用户不具有此功能。Guest users do not.如果已登录用户是来宾用户,根据权限范围,应用可以通过使用用户的对象 ID 或用户主体名称 (UPN) 或组的对象 ID 来读取特殊用户或组的配置文件(例如,https://graph.windows.net/myorganization/users/241f22af-f634-44c0-9a15-c8cd2cea5531?api-version=1.6);但是它不能针对可能请求多个实体的用户资源集执行查询。If the signed-in user is a guest user, depending on the permission scope, an app can read the profile of a specific user or group by using the object ID or user principal name (UPN) for a user or the object ID for a group (for example, https://graph.windows.net/myorganization/users/241f22af-f634-44c0-9a15-c8cd2cea5531?api-version=1.6); however, it cannot perform queries against the users or groups resource set that potentially request more than one entity.例如,根据权限范围,应用可以通过按照以下导航属性中的链接来读取其包含的用户和组的配置文件,但不能发出查询以返回目录中的所有用户或组。For example, depending on the permission scope, the app can read the profiles of users or groups that it obtains by following links in navigation properties, but it cannot issue a query to return all users or groups in the directory.

其他资源 Additional resources

© 2018 Microsoft