如何:在应用程序中添加应用角色并在令牌中接收它们How to: Add app roles to your application and receive them in the token

基于角色的访问控制 (RBAC) 是一种常用的机制,用于在应用程序中强制进行授权。Role-based access control (RBAC) is a popular mechanism to enforce authorization in applications. 使用 RBAC 时,管理员将权限授予角色而不是单个用户或组。When using RBAC, an administrator grants permissions to roles, and not to individual users or groups. 然后,管理员再将角色分配给不同的用户和组,以便控制用户对特定内容和功能的访问。The administrator can then assign roles to different users and groups to control who has access to what content and functionality.

将 RBAC 与应用程序角色和角色声明配合使用,开发人员就可以安全地在应用中强制实施授权,相当轻松。Using RBAC with Application Roles and Role Claims, developers can securely enforce authorization in their apps with less effort.

另一种方法是使用 Azure AD 组和组声明,如 GitHub 上的 active-directory-aspnetcore-webapp-openidconnect-v2 代码示例中所示。Another approach is to use Azure AD Groups and Group Claims as shown in the active-directory-aspnetcore-webapp-openidconnect-v2 code sample on GitHub. Azure AD 组和应用程序角色不会互相排斥;它们可以配合使用,进行更精细的访问控制。Azure AD Groups and Application Roles are not mutually exclusive; they can be used in tandem to provide even finer-grained access control.

为应用程序声明角色Declare roles for an application

使用 Azure 门户定义应用角色。You define app roles by using the Azure portal. 当用户登录到应用程序时,Azure AD 会针对每个角色发出一个 roles 声明。这些角色包括单独授予用户的,以及通过组成员身份获得的。When a user signs in to the application, Azure AD emits a roles claim for each role that the user has been granted individually to the user and from their group membership.

可以通过两种方法使用 Azure 门户来声明应用角色:There are two ways to declare app roles by using the Azure portal:

你添加的角色数量计入 Azure Active Directory 强制实施的应用程序清单限制。The number of roles you add counts toward application manifest limits enforced by Azure Active Directory. 有关这些限制的信息,请参阅 Azure Active Directory 应用清单参考清单限制部分。For information about these limits, see the Manifest limits section of Azure Active Directory app manifest reference.

应用角色 UI | 预览App roles UI | Preview

重要

应用角色门户 UI 功能 以公共预览版提供。is in public preview. 此预览版在提供时没有附带服务级别协议,不建议用于生产工作负载。This preview is provided without a service level agreement and isn't recommended for production workloads. 某些功能可能不受支持或者受限。Certain features might be unsupported or have constrained capabilities. 有关详细信息,请参阅适用于 Azure 预览版的补充使用条款For more information, see Supplemental Terms of Use for Azure Previews.The app roles portal UI feature 以公共预览版提供。is in public preview. 此预览版在提供时没有附带服务级别协议,不建议用于生产工作负载。This preview is provided without a service level agreement and isn't recommended for production workloads. 某些功能可能不受支持或者受限。Certain features might be unsupported or have constrained capabilities. 有关详细信息,请参阅适用于 Azure 预览版的补充使用条款For more information, see Supplemental Terms of Use for Azure Previews.

若要使用 Azure 门户的用户界面创建应用角色,请执行以下操作:To create an app role by using the Azure portal's user interface:

  1. 登录到 Azure 门户Sign in to the Azure portal.

  2. 在顶部菜单中选择“目录 + 订阅”筛选器,然后选择包含要向其添加应用角色的应用注册的 Azure Active Directory 租户。Select the Directory + subscription filter in top menu, and then choose the Azure Active Directory tenant that contains the app registration to which you want to add an app role.

  3. 搜索并选择“Azure Active Directory” 。Search for and select Azure Active Directory.

  4. 在“管理”下,选择“应用注册”,然后选择要在其中定义应用角色的应用程序 。Under Manage, select App registrations, and then select the application you want to define app roles in.

  5. 选择“应用角色 | 预览”,然后选择“创建应用角色” 。Select App roles | Preview, and then select Create app role.

    Azure 门户中应用注册的应用角色窗格

  6. 在“创建应用角色”窗格中,输入角色的设置。In the Create app role pane, enter the settings for the role. 图像下面的表格描述每个设置及其参数。The table following the image describes each setting and their parameters.

    Azure 门户中应用注册的“应用角色创建上下文”窗格

    字段Field 描述Description 示例Example
    显示名称Display name 管理员同意和应用分配体验中显示的应用角色显示名称。Display name for the app role that appears in the admin consent and app assignment experiences. 此值可以包含空格。This value may contain spaces. Survey Writer
    允许的成员类型Allowed member types 指定是否可以将此应用角色分配给用户和/或应用程序。Specifies whether this app role can be assigned to users, applications, or both.

    可供 applications 使用时,应用角色会在应用注册的“管理”部分 >“API 权限”>“添加权限”>“我的 API”>“选择 API”>“应用程序权限”中显示为应用程序权限 。When available to applications, app roles appear as application permissions in an app registration's Manage section > API permissions > Add a permission > My APIs > Choose an API > Application permissions.
    Users/Groups
    Value 指定应用程序在令牌中所需的角色声明的值。Specifies the value of the roles claim that the application should expect in the token. 该值应与应用程序代码中引用的字符串完全匹配。The value should exactly match the string referenced in the application's code. 该值不能包含空格。The value cannot contain spaces. Survey.Create
    说明Description 在管理应用分配和同意体验期间显示的应用角色的更详细说明。A more detailed description of the app role displayed during admin app assignment and consent experiences. Writers can create surveys.
    要启用此应用角色吗?Do you want to enable this app role? 指定是否启用应用角色。Specifies whether the app role is enabled. 若要删除应用角色,请取消选中此复选框,并在尝试删除操作之前应用更改。To delete an app role, deselect this checkbox and apply the change before attempting the delete operation. 已选中Checked
  7. 选择“应用”以保存所做的更改。Select Apply to save your changes.

应用清单编辑器App manifest editor

如需通过直接编辑清单来添加角色,请执行以下操作:To add roles by editing the manifest directly:

  1. 登录到 Azure 门户Sign in to the Azure portal.
  2. 在顶部菜单中选择“目录 + 订阅”筛选器,然后选择包含要向其添加应用角色的应用注册的 Azure Active Directory 租户。Select the Directory + subscription filter in top menu, and then choose the Azure Active Directory tenant that contains the app registration to which you want to add an app role.
  3. 搜索并选择“Azure Active Directory” 。Search for and select Azure Active Directory.
  4. 在“管理”下,选择“应用注册”,然后选择要在其中定义应用角色的应用程序 。Under Manage, select App registrations, and then select the application you want to define app roles in.
  5. 再次在“管理”下选择“清单” 。Again under Manage, select Manifest.
  6. 编辑应用清单,方法是先查找 appRoles 设置,然后添加应用程序角色。Edit the app manifest by locating the appRoles setting and adding your application roles. 可以针对 users 和/或 applications 来定义应用角色。You can define app roles that target users, applications, or both. 以下 JSON 代码片段演示了这两者的示例。The following JSON snippets show examples of both.
  7. 保存清单。Save the manifest.

清单中的每个应用角色定义的 id 值必须具有唯一 GUID。Each app role definition in the manifest must have a unique GUID for its id value.

每个应用角色定义的 value 属性应该与应用程序的代码中使用的字符串完全匹配。The value property of each app role definition should exactly match the strings that are used in the code in the application. value 属性不能包含空格。The value property can't contain spaces. 如果包含空格,则在保存清单时会收到错误。If it does, you'll receive an error when you save the manifest.

示例:用户应用角色Example: User app role

此示例定义了一个名为 Writer 的应用角色,可将其分配给 UserThis example defines an app role named Writer that you can assign to a User:

"appId": "8763f1c4-0000-0000-0000-158e9ef97d6a",
"appRoles": [
    {
      "allowedMemberTypes": [
        "User"
      ],
      "displayName": "Writer",
      "id": "d1c2ade8-0000-0000-0000-6d06b947c66f",
      "isEnabled": true,
      "description": "Writers Have the ability to create tasks.",
      "value": "Writer"
    }
  ],
"availableToOtherTenants": false,

示例:应用程序应用角色Example: Application app role

可供 applications 使用时,应用角色会在应用注册的“管理”部分 >“API 权限”>“添加权限”>“我的 API”>“选择 API”>“应用程序权限”中显示为应用程序权限 。When available to applications, app roles appear as application permissions in an app registration's Manage section > API permissions > Add a permission > My APIs > Choose an API > Application permissions.

此示例显示一个以 Application 为目标的应用角色:This example shows an app role targeted to an Application:

"appId": "8763f1c4-0000-0000-0000-158e9ef97d6a",
"appRoles": [
    {
      "allowedMemberTypes": [
        "Application"
      ],
      "displayName": "ConsumerApps",
      "id": "47fbb575-0000-0000-0000-0f7a6c30beac",
      "isEnabled": true,
      "description": "Consumer apps have access to the consumer data.",
      "value": "Consumer"
    }
  ],
"availableToOtherTenants": false,

将用户和组分配到角色Assign users and groups to roles

在应用程序中添加应用角色以后,即可将此角色分配给用户和组。Once you've added app roles in your application, you can assign users and groups to the roles. 可以通过门户的 UI 为用户或组分配角色,也可以使用 Microsoft Graph 以编程方式进行分配。Assignment of users and groups to roles can be done through the portal's UI, or programmatically using Microsoft Graph. 当分配到各种应用角色的用户登录到应用程序时,其令牌会在 roles 声明中具有其分配的角色。When the users assigned to the various app roles sign in to the application, their tokens will have their assigned roles in the roles claim.

若要使用 Azure 门户将用户和组分配给角色,请执行以下操作:To assign users and groups to roles by using the Azure portal:

  1. 登录到 Azure 门户Sign in to the Azure portal.
  2. 在 Azure Active Directory 的左侧导航菜单中选择“企业应用程序” 。In Azure Active Directory, select Enterprise applications in the left-hand navigation menu.
  3. 选择“所有应用程序”,查看所有应用程序的列表。Select All applications to view a list of all your applications. 如果应用程序未显示在列表中,请使用“所有应用程序”列表顶部的筛选器来限制此列表,或者在列表中向下滚动寻找你的应用程序。If your application doesn't appear in the list, use the filters at the top of the All applications list to restrict the list, or scroll down the list to locate your application.
  4. 选择一个应用程序,以便在其中为角色分配用户或安全组。Select the application in which you want to assign users or security group to roles.
  5. 在“管理”下,选择“用户和组”。Under Manage, select Users and groups.
  6. 选择“添加用户”,打开“添加分配”窗格 。Select Add user to open the Add Assignment pane.
  7. 在“添加分配”窗格中,选择“用户和组”选择器。Select the Users and groups selector from the Add Assignment pane. 随即显示用户和安全组的列表。A list of users and security groups is displayed. 可以搜索特定用户或组,并选择列表中显示的多个用户和组。You can search for a certain user or group as well as select multiple users and groups that appear in the list.
  8. 选择用户和组后,请选择“选择”按钮以继续。Once you've selected users and groups, select the Select button to proceed.
  9. 在“添加分配”窗格中选择“选择角色” 。Select Select a role in the Add assignment pane. 随即显示已为应用程序定义的所有角色。All the roles that you've defined for the application are displayed.
  10. 选择一个角色,然后选择“选择”按钮。Choose a role and select the Select button.
  11. 选择“分配”按钮可完成将用户和组分配到应用的操作。Select the Assign button to finish the assignment of users and groups to the app.

确认已添加的用户和组显示在“用户和组”列表中。Confirm that the users and groups you added appear in the Users and groups list.

向应用程序分配应用角色Assign app roles to applications

在应用程序中添加应用角色后,可以使用 Azure 门户或以编程方式使用 Microsoft Graph 将应用角色分配给客户端应用。Once you've added app roles in your application, you can assign an app role to a client app by using the Azure portal or programmatically by using Microsoft Graph.

将应用角色分配给应用程序时,将创建应用程序权限。When you assign app roles to an application, you create application permissions. 应用程序权限通常由需要进行身份验证和经授权的 API 调用的守护程序应用或后端服务使用,而无需用户的交互。Application permissions are typically used by daemon apps or back-end services that need to authenticate and make authorized API calls as themselves, without the interaction of a user.

若要使用 Azure 门户将应用角色分配给应用程序,请执行以下操作:To assign app roles to an application by using the Azure portal:

  1. 登录到 Azure 门户Sign in to the Azure portal.
  2. 在 Azure Active Directory 的左侧导航菜单中,选择“应用注册” 。In Azure Active Directory, select App registrations in the left-hand navigation menu.
  3. 选择“所有应用程序”,查看所有应用程序的列表。Select All applications to view a list of all your applications. 如果应用程序未显示在列表中,请使用“所有应用程序”列表顶部的筛选器来限制此列表,或者在列表中向下滚动寻找你的应用程序。If your application doesn't appear in the list, use the filters at the top of the All applications list to restrict the list, or scroll down the list to locate your application.
  4. 选择要向其分配应用角色的应用程序。Select the application to which you want to assign an app role.
  5. 选择“API 权限” > “添加权限” 。Select API permissions > Add a permission.
  6. 选择“我的 API”选项卡,然后选择为其定义了应用角色的应用。Select the My APIs tab, and then select the app for which you defined app roles.
  7. 选择“应用程序权限”。Select Application permissions.
  8. 选择要分配的角色。Select the role(s) you want to assign.
  9. 选择“添加权限”按钮完成角色添加。Select the Add permissions button complete addition of the role(s).

新添加的角色应显示在应用注册的“API 权限”窗格中。The newly added roles should appear in your app registration's API permissions pane.

由于这些是应用程序权限,而不是委派的权限,因此管理员必须授予同意,才能使用分配给应用程序的应用角色。Because these are application permissions, not delegated permissions, an admin must grant consent to use the app roles assigned to the application.

  1. 在应用注册的“API 权限”窗格中,选择“为 <tenant name> 授予管理员同意” 。In the app registration's API permissions pane, select Grant admin consent for <tenant name>.
  2. 当系统提示授予所请求权限的同意时,选择“是”。Select Yes when prompted to grant consent for the requested permissions.

“状态”列应反映已为 <tenant name> 授予同意 。The Status column should reflect that consent has been Granted for <tenant name>.

在 Web API 中使用应用角色Use app roles in your web API

定义应用角色并将其分配给用户、组或应用程序后,下一步是向 Web API 添加代码,以便在调用 API 时检查这些角色。Once you've defined app roles and assigned them to a user, group, or application, your next step is to add code to your web API that checks for those roles when the API is called. 也就是说,当客户端应用请求你决定需要授权的 API 操作时,API 的代码必须验证范围是否在客户端应用调用中提供的访问令牌中。That is, when a client app requests an API operation you've decided requires authorization, your API's code must verify the scopes are in the access token presented in the client app's call.

若要了解如何将授权添加到 Web API,请参阅受保护的 Web API:验证范围和应用角色To learn how to add authorization to your web API, see Protected web API: Verify scopes and app roles.

应用角色和组App roles vs. groups

尽管可以使用应用角色或组进行授权,但它们之间的关键差异可能会影响你将哪一种用于你的场景的决定。Though you can use app roles or groups for authorization, key differences between them can influence which you decide to use for your scenario.

应用角色App roles Groups
它们特定于应用程序,并在应用注册中定义。They are specific to an application and are defined in the app registration. 它们随应用程序一起移动。They move with the application. 它们不是特定于应用,而是特定于 Azure AD 租户。They are not specific to an app, but to an Azure AD tenant.
删除应用注册时,应用角色会被删除。App roles are removed when their app registration is removed. 即使删除了应用,组也会保持不变。Groups remain intact even if the app is removed.
roles 声明中提供。Provided in the roles claim. groups 声明中提供。Provided in groups claim.

开发人员可以使用应用角色来控制用户是否可以登录到应用,或者应用是否可以获取 Web API 的访问令牌。Developers can use app roles to control whether a user can sign in to an app or an app can obtain an access token for a web API. 为了将此安全控件扩展到组,开发人员和管理员还可以将安全组分配给应用角色。To extend this security control to groups, developers and admins can also assign security groups to app roles.

当开发人员想要描述和控制其应用中的授权参数时,应用角色是首选。App roles are preferred by developers when they want to describe and control the parameters of authorization in their app themselves. 例如,使用组进行授权的应用将在下一个租户中中断,因为组 ID 和名称可能不同。For example, an app using groups for authorization will break in the next tenant as both the group ID and name could be different. 使用应用角色的应用处于安全状态。An app using app roles remains safe. 事实上,出于同样的原因,将组分配给应用角色在 SaaS 应用中非常流行。In fact, assigning groups to app roles is popular with SaaS apps for the same reasons.

后续步骤Next steps

通过以下资源详细了解应用角色。Learn more about app roles with the following resources.