如何:在应用程序中添加应用角色并在令牌中接收它们How to: Add app roles in 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 little effort on their part.

另一种方法是使用 Azure AD 组和组声明,如 WebApp-GroupClaims-DotNet 中所示。Another approach is to use Azure AD Groups and Group Claims, as shown in WebApp-GroupClaims-DotNet. Azure AD 组和应用程序角色绝不会互相排斥,它们可以配合使用,进行更精细的访问控制。Azure AD Groups and Application Roles are by no means mutually exclusive; they can be used in tandem to provide even finer grained access control.

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

这些应用程序角色在 Azure 门户的应用程序注册清单中定义。These application roles are defined in the Azure portal in the application's registration manifest. 当用户登录到应用程序时,Azure AD 会针对每个角色发出一个 roles 声明。这些角色包括单独授予用户的,以及通过组成员身份获得的。When a user signs into 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. 可以通过门户的 UI 为用户或组分配角色,也可以使用 Microsoft Graph 以编程方式进行分配。Assignment of users and groups to roles can be done through the portal's UI, or programmatically using Microsoft Graph.

使用 Azure 门户声明应用角色Declare app roles using Azure portal

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

  2. 在顶栏中选择帐户,然后选择“切换目录”。 On the top bar, select your account, and then Switch Directory.

  3. “目录 + 订阅”窗格打开后,请从“收藏夹”或“所有目录”列表中选择要在其中注册应用程序的 Active Directory 租户。 Once the Directory + subscription pane opens, choose the Active Directory tenant where you wish to register your application, from the Favorites or All Directories list.

  4. 选择左侧导航栏中的“所有服务” ,并选择“Azure Active Directory” 。Select All services in the left-hand nav, and choose Azure Active Directory.

  5. 在“Azure Active Directory”窗格中选择“应用注册”,查看一个包含所有应用程序的列表 。In the Azure Active Directory pane, select App registrations to view a list of all your applications.

    如果看不到希望其显示在这里的应用程序,请使用“应用注册”列表顶部的各种筛选器来限制此列表,或者在列表中向下滚动,以便找到应用程序。 If you do not see the application you want show up here, use the various filters at the top of the App registrations list to restrict the list or scroll down the list to locate your application.

  6. 选择一个应用程序,以便在其中定义应用角色。Select the application you want to define app roles in.

  7. 在应用程序的边栏选项卡中,选择“清单” 。In the blade for your application, select Manifest.

  8. 编辑应用清单,方法是先查找 appRoles 设置,然后添加所有应用程序角色。Edit the app manifest by locating the appRoles setting and adding all your Application Roles.

    Note

    此清单中的每个应用角色定义都必须对 id 属性具有不同的有效 GUID。Each app role definition in this manifest must have a different valid GUID for the id property.

    每个应用角色定义的 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.

  9. 保存清单。Save the manifest.

示例Examples

以下示例显示的 appRoles 可以分配给 usersThe following example shows the appRoles that you can assign to users.

Note

id 必须是唯一的 GUID。The id must be a unique GUID.

"appId": "8763f1c4-f988-489c-a51e-158e9ef97d6a",
"appRoles": [
    {
      "allowedMemberTypes": [
        "User"
      ],
      "displayName": "Writer",
      "id": "d1c2ade8-98f8-45fd-aa4a-6d06b947c66f",
      "isEnabled": true,
      "description": "Writers Have the ability to create tasks.",
      "value": "Writer"
    }
  ],
"availableToOtherTenants": false,

Note

displayName 不能包含空格。The displayName cannot contain spaces.

可以针对 users 和/或 applications 来定义应用角色。You can define app roles to target users, applications, or both. 可供 applications 使用时,应用角色在“所需的权限”边栏选项卡中显示为应用程序权限。 When available to applications, app roles appear as application permissions in the Required Permissions blade. 以下示例显示一个以 Application 为目标的应用角色。The following example shows an app role targeted towards an Application.

"appId": "8763f1c4-f988-489c-a51e-158e9ef97d6a",
"appRoles": [
    {
      "allowedMemberTypes": [
        "Application"
      ],
      "displayName": "ConsumerApps",
      "id": "47fbb575-859a-4941-89c9-0f7a6c30beac",
      "isEnabled": true,
      "description": "Consumer apps have access to the consumer data.",
      "value": "Consumer"
    }
  ],
"availableToOtherTenants": false,

定义的角色数会影响应用程序清单的限制。The number of roles defined affects the limits that the application manifest has. 已在清单限制页上对这些限制进行了详细讨论。They have been discussed in detail on the manifest limits page.

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

在应用程序中添加应用角色以后,即可将这些角色分配给用户和组。Once you've added app roles in your application, you can assign users and groups to these roles.

  1. 使用 Azure Active Directory 左侧导航菜单,在“Azure Active Directory”窗格中选择“企业应用程序” 。In the Azure Active Directory pane, select Enterprise applications from the Azure Active Directory left-hand navigation menu.

  2. 选择“所有应用程序” ,查看所有应用程序的列表。Select All applications to view a list of all your applications.

    如果看不到希望其显示在这里的应用程序,请使用“所有应用程序”列表顶部的各种筛选器来限制此列表,或者在列表中向下滚动,以便找到应用程序。 If you do not see the application you want show up here, use the various filters at the top of the All applications list to restrict the list or scroll down the list to locate your application.

  3. 选择一个应用程序,以便在其中为角色分配用户或安全组。Select the application in which you want to assign users or security group to roles.

  4. 在应用程序的左侧导航菜单中选择“用户和组”窗格 。Select the Users and groups pane in the application’s left-hand navigation menu.

  5. 在“用户和组”列表顶部选择“添加用户”按钮,以便打开“添加分配”窗格。 At the top of the Users and groups list, select the Add user button to open the Add Assignment pane.

  6. 在“添加分配” 窗格中,选择“用户和组” 选择器。Select the Users and groups selector from the Add Assignment pane.

    将会显示用户和安全组的列表和一个文本框,后者用于搜索和查找特定用户或组。A list of users and security groups will be shown along with a textbox to search and locate a certain user or group. 此屏幕允许一次选择多个用户和组。This screen allows you to select multiple users and groups in one go.

  7. 选择好用户和组以后,按底部的“选择”按钮即可转到下一部分。 Once you are done selecting the users and groups, press the Select button on bottom to move to the next part.

  8. 在“添加分配” 窗格中,选择“选择角色” 选择器。Choose the Select Role selector from the Add assignment pane. 此前在应用清单中声明的所有角色都会显示。All the roles declared earlier in the app manifest will show up.

  9. 选择一个角色,然后按“选择” 按钮。Choose a role and press the Select button.

  10. 按底部的“分配”按钮即可完成将用户和组分配到应用的操作。 Press the Assign button on the bottom to finish the assignments of users and groups to the app.

  11. 确认已添加的用户和组显示在更新的“用户和组”列表中。 Confirm that the users and groups you added are showing up in the updated Users and groups list.

详细信息More information