您现在访问的是微软AZURE全球版技术文档网站,若需要访问由世纪互联运营的MICROSOFT AZURE中国区技术文档网站,请访问 https://docs.azure.cn.

Azure Active Directory v1.0 终结点中的权限和许可Permissions and consent in the Azure Active Directory v1.0 endpoint

适用于:Applies to:
  • Azure AD v1.0 终结点Azure AD v1.0 endpoint

Azure Active Directory (Azure AD) 对 OAuth 和 OpenID Connect (OIDC) 流广泛使用权限。Azure Active Directory (Azure AD) makes extensive use of permissions for both OAuth and OpenID Connect (OIDC) flows. 当应用从 Azure AD 接收访问令牌时,访问令牌将包含声明,这些声明描述了应用对特定资源的权限。When your app receives an access token from Azure AD, the access token will include claims that describe the permissions that your app has in respect to a particular resource.

利用权限(也称为作用域),资源可以轻松进行授权,因为资源只需要检查令牌是否包含对应用要调用的 API 的合适权限 。Permissions, also known as scopes, make authorization easy for the resource because the resource only needs to check that the token contains the appropriate permission for whatever API the app is calling.

权限的类型Types of permissions

Azure AD 定义两种权限:Azure AD defines two kinds of permissions:

  • 委托的权限 - 由包含登录用户的应用使用。Delegated permissions - Are used by apps that have a signed-in user present. 对于这些应用,用户或管理员需许可应用请求的权限,并向应用授予委托的权限,以便在对 API 发出调用时,该应用可充当登录的用户。For these apps, either the user or an administrator consents to the permissions that the app requests and the app is delegated permission to act as the signed-in user when making calls to an API. 根据 API,用户可能无法直接许可 API,而是要求管理员提供“管理员同意”Depending on the API, the user may not be able to consent to the API directly and would instead require an administrator to provide "admin consent".
  • 应用程序权限 - 由无需存在登录用户即可运行的应用使用;例如,以后台服务或守护程序形式运行的应用。Application permissions - Are used by apps that run without a signed-in user present; for example, apps that run as background services or daemons. 应用程序权限只能由管理员许可,因为它们通常非常强大,允许访问跨用户边界的数据,或者访问仅限管理员访问的数据。Application permissions can only be consented by an administrator because they are typically powerful and allow access to data across user-boundaries, or data that would otherwise be restricted to administrators.

有效权限是应用在对 API 发出请求时拥有的权限。Effective permissions are the permissions that your app will have when making requests to an API.

  • 对于委托的权限,应用的有效权限是(通过许可)授予应用的委托权限与当前登录用户的特权的最低特权交集。For delegated permissions, the effective permissions of your app will be the least privileged intersection of the delegated permissions the app has been granted (through consent) and the privileges of the currently signed-in user. 应用的特权永远不会超过登录用户的特权。Your app can never have more privileges than the signed-in user. 在组织内部,可以通过策略或者一个或多个管理员角色的成员身份来确定登录用户的特权。Within organizations, the privileges of the signed-in user may be determined by policy or by membership in one or more administrator roles. 若要了解哪些管理员角色可以同意委托的权限,请参阅 Azure AD 中的管理员角色权限To learn which administrator roles can consent to delegated permissions, see Administrator role permissions in Azure AD. 例如,假设为应用授予了 Microsoft Graph 中的 User.ReadWrite.All 委托权限。For example, assume your app has been granted the User.ReadWrite.All delegated permission in Microsoft Graph. 此权限在名义上会授予应用读取和更新组织中每个用户的个人资料的权限。This permission nominally grants your app permission to read and update the profile of every user in an organization. 如果登录用户是全局管理员,则应用可以更新组织中每个用户的个人资料。If the signed-in user is a global administrator, your app will be able to update the profile of every user in the organization. 但是,如果登录用户不是充当管理员角色,则应用只能更新登录用户的个人资料。However, if the signed-in user is not in an administrator role, your app will be able to update only the profile of the signed-in user. 它无法更新组织中其他用户的个人资料,因为该应用有权代表的用户没有这些特权。It will not be able to update the profiles of other users in the organization because the user that it has permission to act on behalf of does not have those privileges.
  • 对于应用程序权限,应用的有效权限是权限默示的完整特权级别。For application permissions, the effective permissions of your app are the full level of privileges implied by the permission. 例如,拥有 User.ReadWrite.All 应用程序权限的应用可以更新组织中每个用户的个人资料。For example, an app that has the User.ReadWrite.All application permission can update the profile of every user in the organization.

权限特性Permission attributes

Azure AD 中的权限提供多个属性用于帮助用户、管理员或应用开发人员在权限授予哪些对象的访问权限方面做出明智的决策。Permissions in Azure AD have a number of properties that help users, administrators, or app developers make informed decisions about what the permission grants access to.

备注

可以使用 Azure 门户或 PowerShell 查看 Azure AD 应用程序或服务主体公开的权限。You can view the permissions that an Azure AD Application or Service Principal exposes using the Azure portal, or PowerShell. 请尝试运行以下脚本来查看 Microsoft Graph 公开的权限。Try this script to view the permissions exposed by Microsoft Graph.

Connect-AzureAD

# Get OAuth2 Permissions/delegated permissions
(Get-AzureADServicePrincipal -filter "DisplayName eq 'Microsoft Graph'").OAuth2Permissions

# Get App roles/application permissions
(Get-AzureADServicePrincipal -filter "DisplayName eq 'Microsoft Graph'").AppRoles
属性名称Property name 描述Description 示例Example
ID 这是唯一标识此权限的 GUID 值。Is a GUID value that uniquely identifies this permission. 570282fd-fa5c-430d-a7fd-fc8dc98a9dca570282fd-fa5c-430d-a7fd-fc8dc98a9dca
IsEnabled 指示此权限是否可供使用。Indicates whether this permission is available for use. truetrue
Type 指示此权限是否需要用户许可或管理员许可。Indicates whether this permission requires user consent or admin consent. 用户User
AdminConsentDescription 这是在管理员许可体验期间向管理员显示的说明Is a description that's shown to administrators during the admin consent experiences 允许应用读取用户邮箱中的电子邮件。Allows the app to read email in user mailboxes.
AdminConsentDisplayName 这是在管理员许可体验期间向管理员显示的友好名称。Is the friendly name that's shown to administrators during the admin consent experience. 读取用户邮件Read user mail
UserConsentDescription 这是在用户许可体验期间向用户显示的说明。Is a description that's shown to users during a user consent experience. 允许应用读取你邮箱中的电子邮件。Allows the app to read email in your mailbox.
UserConsentDisplayName 这是在用户许可体验期间向用户显示的友好名称。Is the friendly name that's shown to users during a user consent experience. 读取你的邮件Read your mail
Value 这是在 OAuth 2.0 授权流期间用于标识权限的字符串。Is the string that's used to identify the permission during OAuth 2.0 authorize flows. 还可以将 Value 与应用 ID URI 字符串进行组合,以构成完全限定的权限名称。Value may also be combined with the App ID URI string in order to form a fully qualified permission name. Mail.Read

Azure AD 中的应用程序必须获得许可才能访问所需的资源或 API。Applications in Azure AD rely on consent in order to gain access to necessary resources or APIs. 应用可能需要了解多种类型的许可才能成功访问。There are a number of kinds of consent that your app may need to know about in order to be successful. 在定义权限时,还需要了解用户如何获取应用或 API 的访问权限。If you are defining permissions, you will also need to understand how your users will gain access to your app or API.

  • 静态用户许可 - 在执行 OAuth 2.0 授权流期间指定应用想要交互的资源时自动发生。Static user consent - Occurs automatically during the OAuth 2.0 authorize flow when you specify the resource that your app wants to interact with. 在静态用户许可方案中,应用必须已指定它在 Azure 门户的应用配置中所需的所有权限。In the static user consent scenario, your app must have already specified all the permissions it needs in the app's configuration in the Azure portal. 如果用户(或管理员)未授予此应用的许可,则 Azure AD 现在会提示用户提供许可。If the user (or administrator, as appropriate) has not granted consent for this app, then Azure AD will prompt the user to provide consent at this time.

    详细了解如何注册请求访问一组静态 API 的 Azure AD 应用。Learn more about registering an Azure AD app that requests access to a static set of APIs.

  • 动态用户许可 - 是 v2 Azure AD 应用模型的一项功能。Dynamic user consent - Is a feature of the v2 Azure AD app model. 在此方案中,你的应用请求它在 v2 应用的 OAuth 2.0 授权流中所需的一组权限。In this scenario, your app requests a set of permissions that it needs in the OAuth 2.0 authorize flow for v2 apps. 如果用户尚未许可,系统现在会提示他们许可。If the user has not consented already, they will be prompted to consent at this time. 详细了解动态许可Learn more about dynamic consent.

    重要

    动态许可有时十分方便,但对于管理员许可的权限而言,可能会带来很大的挑战,因为管理员许可体验在许可时不知道这些权限。Dynamic consent can be convenient, but presents a big challenge for permissions that require admin consent, since the admin consent experience doesn't know about those permissions at consent time. 如果你需要管理员特权权限,或者应用使用动态许可,则必须在 Azure 门户中注册所有权限(而不仅仅是需要管理员同意的权限子集)。If you require admin privileged permissions or if your app uses dynamic consent, you must register all of the permissions in the Azure portal (not just the subset of permissions that require admin consent). 这使租户管理员能够代表其所有用户同意。This enables tenant admins to consent on behalf of all their users.

  • 管理员同意 - 当应用需要访问特定的高特权权限时必须执行。Admin consent - Is required when your app needs access to certain high-privilege permissions. 管理员同意可以确保管理员在授权应用或用户访问组织中的高特权数据之前拥有某些额外的控制权。Admin consent ensures that administrators have some additional controls before authorizing apps or users to access highly privileged data from the organization. 详细了解如何授予管理员许可Learn more about how to grant admin consent.

最佳做法Best practices

客户端最佳实践Client best practices

  • 仅请求你的应用需要的权限。Only request for permissions that your app needs. 拥有过多权限的应用一旦泄密,则存在透露用户数据的风险。Apps with too many permissions are at risk of exposing user data if they are compromised.
  • 根据你的应用支持的方案在委派的权限与应用程序权限之间进行选择。Choose between delegated permissions and application permissions based on the scenario that your app supports.
    • 如果调用是以用户身份执行的,请始终使用委派的权限。Always use delegated permissions if the call is being made on behalf of a user.
    • 如果应用是非交互的并且不以任何特定用户的身份执行调用,请仅使用应用程序权限。Only use application permissions if the app is non-interactive and not making calls on behalf of any specific user. 应用程序权限有很高的特权,只有绝对必要时才应使用。Application permissions are highly privileged and should only be used when absolutely necessary.
  • 使用基于 v2.0 终结点的应用时,请始终将静态权限(在应用程序注册中指定的那些权限)设置为你在运行时请求的动态权限(在代码中指定的并且在授权请求中作为查询参数发送的那些权限)的超集,以便管理员同意等方案可以正常工作。When using an app based on the v2.0 endpoint, always set the static permissions (those specified in your application registration) to be the superset of the dynamic permissions you request at runtime (those specified in code and sent as query parameters in your authorize request) so that scenarios like admin consent works correctly.

资源 /API 最佳做法Resource/API best practices

  • 公开 API 的资源应当定义与它们所要保护的数据或操作相关的权限。Resources that expose APIs should define permissions that are specific to the data or actions that they are protecting. 遵循此最佳做法有助于确保客户端最终不会有权访问它们不需要的数据,并合理告知用户他们需要许可的数据。Following this best practice helps to ensure that clients do not end up with permission to access data that they do not need and that users are well informed about what data they are consenting to.
  • 资源应该单独显式定义 ReadReadWrite 权限。Resources should explicitly define Read and ReadWrite permissions separately.
  • 资源应将允许访问跨用户边界的数据的所有权限标记为 Admin 权限。Resources should mark any permissions that allow access to data across user boundaries as Admin permissions.
  • 资源应当遵循命名模式 Subject.Permission[.Modifier],其中:Resources should follow the naming pattern Subject.Permission[.Modifier], where:
    • Subject 对应于可用的数据类型Subject corresponds with the type of data that is available

    • Permission 对应于用户可以对该数据执行的操作Permission corresponds to the action that a user may take upon that data

    • 可以选择使用 Modifier 来描述另一个权限的专用化Modifier is used optionally to describe specializations of another permission

      例如:For example:

    • Mail.Read - 允许用户读取邮件。Mail.Read - Allows users to read mail.

    • Mail.ReadWrite - 允许用户读取或写入邮件。Mail.ReadWrite - Allows users to read or write mail.

    • Mail.ReadWrite.All - 允许管理员或用户访问组织中的所有邮件。Mail.ReadWrite.All - Allows an administrator or user to access all mail in the organization.