配置角色声明

项目
07/01/2024

你可以在应用程序获得授权后收到的访问令牌中自定义角色声明。如果应用程序需要令牌中的自定义角色，请使用此功能。可以根据需要创建任意多个角色。

先决条件

具有已配置租户的 Microsoft Entra 订阅。有关详细信息，请参阅快速入门：设置租户。
已添加到租户的企业应用程序。有关详细信息，请参阅快速入门：添加企业应用程序。
为应用程序配置的单一登录 (SSO)。有关详细信息，请参阅为企业应用程序启用单一登录。
已分配给角色的用户帐户。有关详细信息，请参阅快速入门：创建和分配用户帐户。

注意

本文介绍了如何使用 API 在服务主体上创建、更新或删除应用程序角色。若要将新用户界面用于应用角色，请参阅在应用程序中添加应用角色并在令牌中接收它们。

定位企业应用程序

提示

本文中的步骤可能因开始使用的门户而略有不同。

使用以下步骤定位企业应用程序：

至少以云应用程序管理员身份登录到 Microsoft Entra 管理中心。
浏览到“标识”>“应用程序”>“企业应用程序”>“所有应用程序”。
在“搜索”框中输入现有应用程序的名称，然后从搜索结果中选择该应用程序。
选择应用程序后，从概述窗格中复制对象 ID。

添加角色

使用 Microsoft Graph 浏览器向企业应用程序添加角色。

在另一个窗口中打开 Microsoft Graph 浏览器，使用租户的管理员凭据登录。

注意

云应用程序管理员和应用程序管理员角色在此场景中不适用，请使用特权角色管理员。
选择“修改权限”，为列表中的 Application.ReadWrite.All 和 Directory.ReadWrite.All 权限选择“同意”。
将以下请求中的 <objectID> 替换为之前记录的对象 ID，然后运行查询：

https://graph.microsoft.com/v1.0/servicePrincipals/<objectID>

企业应用程序也称为服务主体。记录返回的服务主体对象中的 appRoles 属性。以下示例演示典型的 appRoles 属性：

{
  "appRoles": [
    {
      "allowedMemberTypes": [
        "User"
      ],
      "description": "msiam_access",
      "displayName": "msiam_access",
      "id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
      "isEnabled": true,
      "origin": "Application",
      "value": null
    }
  ]
}

在 Graph 浏览器中，将方法从 GET 更改为 PATCH。
将以前记录的 appRoles 属性复制到 Graph 浏览器的“请求正文”窗格中，添加新的角色定义，然后选择“运行查询”以执行补丁操作。一条成功消息会确认角色已创建。以下示例显示如何添加“管理员”角色：
```
{
  "appRoles": [
    {
      "allowedMemberTypes": [
        "User"
      ],
      "description": "msiam_access",
      "displayName": "msiam_access",
      "id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
      "isEnabled": true,
      "origin": "Application",
      "value": null
    },
    {
      "allowedMemberTypes": [
        "User"
      ],
      "description": "Administrators Only",
      "displayName": "Admin",
      "id": "11bb11bb-cc22-dd33-ee44-55ff55ff55ff",
      "isEnabled": true,
      "origin": "ServicePrincipal",
      "value": "Administrator"
    }
  ]
}
```
除了请求正文中的任何新角色之外，还必须包括 msiam_access 角色对象。请求正文中未包含任何现有角色会将这些角色从 appRoles 对象中删除。此外，可以根据组织的需要添加任意数量的角色。这些角色的值在 SAML 响应中作为声明值发送。若要为新角色的 ID 生成 GUID 值，请使用 Web 工具，例如联机 GUID/UUID 生成器。响应中的 appRoles 属性包含查询的请求正文中的内容。

编辑特性

更新属性以定义令牌中包含的角色声明。

在 Microsoft Entra 管理中心找到该应用程序，然后在左侧菜单中选择“单一登录”。
在“属性和声明”部分，选择“编辑”。
选择“添加新声明”。
在“名称”框中，键入属性名称。此示例中使用角色名称作为声明名称。
将“命名空间”框留空。
在“源属性”列表中，选择“user.assignedroles”。
选择“保存”。新的“角色名称”属性现在应显示在“属性和声明”部分。登录应用程序时，该声明现在应包含在访问令牌中。

分配角色

在使用更多角色修补服务主体后，可以将用户分配到相应的角色。

在 Microsoft Entra 管理中心中找到添加了角色的应用程序。
在左侧菜单中选择“用户和组”，然后选择你要为其分配新角色的用户。
选择窗格顶部的“编辑分配”以更改角色。
选择“未选择任何内容”，从列表中选择角色，然后选择“选择”。
选择“分配”，将角色分配给用户。

更新角色

若要更新现有角色，请执行以下步骤：

打开 Microsoft Graph Explorer。
以特权角色管理员身份登录到 Graph 浏览器站点。
使用概述窗格中应用程序的对象 ID，将以下请求中的 <objectID> 替换为它，然后运行查询：

https://graph.microsoft.com/v1.0/servicePrincipals/<objectID>
记录返回的服务主体对象中的 appRoles 属性。
在 Graph 浏览器中，将方法从 GET 更改为 PATCH。
将以前记录的 appRoles 属性复制到 Graph 浏览器的“请求正文”窗格中，更新角色定义，然后选择“运行查询”以执行补丁操作。

删除角色

若要删除现有角色，请执行以下步骤：

打开 Microsoft Graph Explorer。
以特权角色管理员身份登录到 Graph 浏览器站点。
在 Azure 门户中使用概述窗格中应用程序的对象 ID，将以下请求中的 <objectID> 替换为它，然后运行查询：

https://graph.microsoft.com/v1.0/servicePrincipals/<objectID>
记录返回的服务主体对象中的 appRoles 属性。
在 Graph 浏览器中，将方法从 GET 更改为 PATCH。
将之前记录的 appRoles 属性复制到 Graph 浏览器的“请求正文”窗格中，将要删除的角色的 IsEnabled 值设置为 false，然后选择“运行查询”以执行补丁操作。必须先禁用角色，然后才能将其删除。
在禁用角色后，从 appRoles 节删除该角色块。将方法保留为 PATCH，然后再次选择“运行查询”。

后续步骤

若要了解如何自定义声明，请参阅为企业应用程序自定义在 SAML 令牌中发出的声明。

通过