将应用角色添加到应用程序中并在令牌中接收它们

基于角色的访问控制 (RBAC) 是一种常用的机制，用于在应用程序中强制进行授权。 使用 RBAC，管理员可以向角色授予权限，而不是向特定用户或组授予权限。 然后，管理员再将角色分配给不同的用户和组，以便控制用户对特定内容和功能的访问。

将 RBAC 与应用程序角色和角色声明配合使用，开发人员就可以安全地在应用中强制实施授权，相当轻松。

另一种方法是使用 Microsoft Entra 组和组声明，如 GitHub 上的 active-directory-aspnetcore-webapp-openidconnect-v2 代码示例中所示。 Microsoft Entra 组和应用程序角色不会互相排斥；它们可以配合使用，以提供更精细的访问控制。

为应用程序声明角色

在应用注册过程中，使用 Microsoft Entra 管理中心定义应用角色。 应用角色在表示服务、应用或 API 的应用程序注册上定义。 当用户登录到应用程序时，Microsoft Entra ID 会为用户或服务主体授予的每个角色发出 roles声明。 这可用于实现基于声明的授权。 应用角色可以分配给一个用户或一组用户。 应用角色也可以分配给另一个应用程序的服务主体，或者分配给托管标识的服务主体。

目前，如果将服务主体添加到组，然后将应用角色分配给该组，则 Microsoft Entra ID 不会将 roles 声明添加到它颁发的令牌中。

使用 Microsoft Entra 管理中心的应用角色 UI 声明应用角色：

你添加的角色数量计入 Microsoft Entra ID 强制实施的应用程序清单限制。 有关这些限制的信息，请参阅 Microsoft Entra 应用清单参考的清单限制部分。

应用角色 UI

使用 Microsoft Entra 管理中心的用户界面创建应用角色：

1. 至少以云应用程序管理员身份登录到 Microsoft Entra 管理中心。

2. 如果有权访问多个租户，请使用顶部菜单中的“设置”图标 ，从“目录 + 订阅”菜单切换到包含应用注册的租户。

3. 浏览到“标识”>“应用程序”>“应用注册”，然后选择要在其中定义应用角色的应用程序。

4. 在“管理”下，选择“应用角色”，然后选择“创建应用角色”。

   

5. 在“创建应用角色”窗格中，输入角色的设置。 图像下面的表格描述每个设置及其参数。

   

   字段	说明	示例
   显示名称	管理员同意和应用分配体验中显示的应用角色显示名称。 此值可以包含空格。	Survey Writer
   允许的成员类型	指定是否可以将此应用角色分配给用户和/或应用程序。 当应用角色可用于 applications 时，它将在应用注册的“管理”部分 >“API 权限”>“添加权限”>“我的 API”>“选择 API”>“应用程序权限”中显示为应用程序权限。	Users/Groups
   值	指定应用程序在令牌中所需的角色声明的值。 该值应与应用程序代码中引用的字符串完全匹配。 该值不能包含空格。	Survey.Create
   说明	在管理应用分配和同意体验期间显示的应用角色的更详细说明。	Writers can create surveys.
   要启用此应用角色吗？	指定是否启用应用角色。 若要删除应用角色，请取消选中此复选框，并在尝试删除操作之前应用更改。 此设置控制应用角色的使用情况和可用性，同时能够暂时或永久禁用它，而无需完全移除它。	已选中

6. 选择“应用”以保存所做的更改。

当应用角色设置为“已启用”时，所分配的任何用户、应用程序或组都将其包含在其令牌中。 当应用是正在调用的 API 时，这些可以是访问令牌；当应用正在使用户登录时，这些可以是 ID 令牌。 如果设置为“已禁用”，则它变为非活动且不再可分配。 之前的任何被分派人仍将在其令牌中包含应用角色，但该角色不起作用，因为不再可主动分配它。

分配应用程序所有者

如果你尚未将自己分配为应用程序所有者，则需要执行此操作。

1. 在应用注册中的“管理”下，选择“所有者”，然后选择“添加所有者”。
2. 在新窗口中，找到并选择要分配给应用程序的所有者。 所选所有者将显示在右侧面板中。 完成后，通过“选择”进行确认。 应用所有者现在将显示在所有者列表中。

向应用程序分配应用角色

在应用程序中添加应用角色后，可以使用 Microsoft Entra 管理中心或以编程方式使用 Microsoft Graph 将应用角色分配给客户端应用。 这不应与向用户分配角色相混淆。

将应用角色分配给应用程序时，将创建应用程序权限。 应用程序权限通常由需要进行身份验证和经授权的 API 调用的守护程序应用或后端服务使用，而无需用户的交互。

使用 Microsoft Entra 管理中心将应用角色分配给应用程序：

1. 至少以云应用程序管理员身份登录到 Microsoft Entra 管理中心。
2. 浏览到“标识”>“应用程序”>“应用注册”，然后选择“所有应用程序”。
3. 选择“所有应用程序”，查看所有应用程序的列表。 如果应用程序未显示在列表中，请使用“所有应用程序”列表顶部的筛选器来限制此列表，或者在列表中向下滚动寻找你的应用程序。
4. 选择要向其分配应用角色的应用程序。
5. 选择“API 权限”>“添加权限” 。
6. 选择“我的 API”选项卡，然后选择为其定义了应用角色的应用。
7. 在“权限”下，选择要分配的角色。
8. 选择“添加权限”按钮完成角色添加。

新添加的角色应显示在应用注册的“API 权限”窗格中。

授予管理员同意

由于这些是应用程序权限，而不是委派的权限，因此管理员必须授予同意，才能使用分配给应用程序的应用角色。

1. 在应用注册的“API 权限”窗格中，选择“为 <租户名称> 授予管理员同意”。
2. 当系统提示授予所请求权限的同意时，选择“是”。

“状态”列应反映已为 <租户名称> 授予同意。

应用角色的使用方案

如果是在应用程序方案中实现使用户登录的应用角色业务逻辑，请首先在“应用注册”中定义应用角色。 然后，管理员将它们分配给“企业应用程序”窗格中的用户和组。 所分配的这些应用角色包含在为应用程序颁发的任何令牌中。

如果是在应用调用 API 方案中实现应用角色业务逻辑，则有两个应用注册。 一个应用注册用于应用，另一个应用注册用于 API。 在这种情况下，请定义应用角色，并将其分配给 API 的应用注册中的用户或组。 当用户使用应用进行身份验证并请求访问令牌以调用 API 时，该令牌中会包含角色声明。 下一步是将代码添加到 Web API，以在调用 API 时检查这些角色。

若要了解如何将授权添加到 Web API，请参阅受保护的 Web API：验证范围和应用角色。

应用角色和组

尽管可以使用应用角色或组进行授权，但它们之间的关键差异可能会影响你将哪一种用于你的场景的决定。

开发人员可以使用应用角色来控制用户是否可以登录到应用，或者应用是否可以获取 Web API 的访问令牌。 为了将此安全控件扩展到组，开发人员和管理员还可以将安全组分配给应用角色。

当开发人员想要描述和控制其应用中的授权参数时，应用角色是首选。 例如，使用组进行授权的应用将在下一个租户中中断，因为组 ID 和名称可能不同。 使用应用角色的应用处于安全状态。 事实上，由于相同的原因，将组分配给应用角色对 SaaS 应用而言很常见，因为它允许在多个租户中预配 SaaS 应用。

将用户和组分配到 Microsoft Entra 角色

在应用程序中添加应用角色以后，您可以将用户和组分配给 Microsoft Entra 角色。 可以通过门户的 UI 为用户或组分配角色，也可以使用 Microsoft Graph 以编程方式进行分配。 当分配到各种角色的用户登录到应用程序时，其令牌将在 roles 声明中包含为其分配的角色。

使用 Microsoft Entra 管理中心将用户和组分配到角色：

1. 至少以云应用程序管理员身份登录到 Microsoft Entra 管理中心。
2. 如果有权访问多个租户，请使用顶部菜单中的“设置”图标 ，从“目录 + 订阅”菜单切换到包含应用注册的租户。
3. 浏览到“标识”>“应用程序”>“企业应用程序”。
4. 选择“所有应用程序”，查看所有应用程序的列表。 如果应用程序未显示在列表中，请使用“所有应用程序”列表顶部的筛选器来限制此列表，或者在列表中向下滚动寻找你的应用程序。
5. 选择一个应用程序，以便在其中为角色分配用户或安全组。
6. 在“管理”下，选择“用户和组”。
7. 选择“添加用户”，打开“添加分配”窗格。
8. 在“添加分配”窗格中，选择“用户和组”选择器。 随即显示用户和安全组的列表。 可以搜索特定用户或组，并选择列表中显示的多个用户和组。
9. 选择用户和组后，请选择“选择”按钮以继续。
10. 在“添加分配”窗格中选择“选择角色” 。 随即显示已为应用程序定义的所有角色。
11. 选择一个角色，然后选择“选择”按钮。
12. 选择“分配”按钮可完成将用户和组分配到应用的操作。

确认已添加的用户和组显示在“用户和组”列表中。

后续步骤

通过以下资源详细了解应用角色。

• GitHub 上的代码示例
  • 将使用应用角色和角色声明的授权添加到 ASP.NET Core Web 应用
• 参考文档
  • Microsoft Entra 应用清单