設定角色宣告

文章
06/27/2024

您可以在授權應用程式之後所收到的存取令牌中自定義角色宣告。如果您的應用程式需要令牌中的自訂角色，請使用此功能。您可以視需要建立盡可能多的角色。

必要條件

具有已設定租使用者的Microsoft Entra 訂用帳戶。如需詳細資訊，請參閱快速入門：設定租用戶。
已新增至租用戶的企業應用程式。如需詳細資訊，請參閱快速入門：新增企業應用程式。
針對應用程式設定的單一登錄（SSO）。如需詳細資訊，請參閱啟用企業應用程式的單一登錄。
指派給角色的用戶帳戶。如需詳細資訊，請參閱快速入門：建立和指派用戶帳戶。

注意

本文說明如何使用 API 在服務主體上建立、更新或刪除應用程式角色。若要使用應用程式角色的新使用者介面，請參閱將應用程式角色新增至您的應用程式，並在令牌中接收它們。

找出企業應用程式

提示

根據您開始的入口網站，本文中的步驟可能略有不同。

使用下列步驟來尋找企業應用程式：

以至少雲端應用程式系統管理員的身分登入 Microsoft Entra 系統管理中心。
瀏覽至 [身分識別]>[應用程式]>[企業應用程式]>[所有應用程式]。
在搜尋方塊中輸入現有應用程式的名稱，然後從搜尋結果中選取應用程式。
選取應用程式之後，請從 [概觀] 窗格複製物件識別符。

新增角色

使用 Microsoft Graph 總管，將角色新增至企業應用程式。

在另一個視窗中開啟 Microsoft Graph 總管，並使用租用戶的系統管理員認證登入。

注意

在此案例中，雲端應用程式管理員和應用程式管理員角色將無法運作，請使用特殊許可權角色管理員。
選取 [修改許可權]，選取 [同意 ] Application.ReadWrite.All 和 Directory.ReadWrite.All 列表中的許可權。
將下列要求中的取代 <objectID> 為先前記錄的物件識別碼，然後執行查詢：

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。
複製先前記錄到 Graph Explorer 的 [要求本文 ] 窗格中的 appRoles 屬性，新增角色定義，然後選取 [ 執行查詢 ] 以執行修補作業。成功訊息會確認角色的建立。下列範例顯示新增 管理員 角色：
```
{
  "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 回應中的宣告值的形式傳送。若要產生新角色識別碼的 GUID 值，請使用 Web 工具，例如在線 GUID / UUID 產生器。回應中的 appRoles 屬性包含查詢要求主體中的內容。

編輯屬性

更新屬性，以定義令牌中包含的角色宣告。

在 Microsoft Entra 系統管理中心找到應用程式，然後在左側功能表中選取 [ 單一登錄 ]。
在 [ 屬性與宣告] 區段中，選取 [ 編輯]。
選取 [新增宣告]。
在 [ 名稱] 方塊中，輸入屬性名稱。此範例使用 角色名稱 做為宣告名稱。
將 [ 命名空間] 方塊保留空白。
從 [ 來源屬性] 列表中，選取 user.assignedroles。
選取 [儲存]。新的 角色名稱 屬性現在應該會出現在 [屬性和宣告 ] 區段中。登入應用程式時，宣告現在應該包含在存取令牌中。

指派角色

使用更多角色修補服務主體之後，您可以將使用者指派給個別角色。

找出在 Microsoft Entra 系統管理中心新增角色的應用程式。
選取 左側功能表中的 [使用者和群組 ]，然後選取您要指派新角色的使用者。
選取 窗格頂端的 [編輯指派 ] 以變更角色。
選取 [ 無選取]，從列表中選取角色，然後選取 [ 選取]。
選取 [ 指派 ] 將角色指派給使用者。

更新角色

若要更新現有的角色，請執行下列步驟：

開啟 Microsoft Graph 總管。
以特殊許可權角色管理員身分登入 Graph 總管網站。
使用概觀窗格中應用程式的物件識別碼，以 <objectID> 取代下列要求，然後執行查詢：

https://graph.microsoft.com/v1.0/servicePrincipals/<objectID>
從傳回的服務主體對象記錄 appRoles 屬性。
在 Graph 總管中，將方法從 GET 變更為 PATCH。
將先前記錄的 appRoles 屬性複製到 Graph Explorer 的 [要求本文 ] 窗格中，新增更新角色定義，然後選取 [ 執行查詢 ] 以執行修補作業。

刪除角色

若要刪除現有的角色，請執行下列步驟：

開啟 Microsoft Graph 總管。
以特殊許可權角色管理員身分登入 Graph 總管網站。
使用 Azure 入口網站概觀窗格中應用程式的物件識別碼，以<objectID>取代下列要求，然後執行查詢：

https://graph.microsoft.com/v1.0/servicePrincipals/<objectID>
從傳回的服務主體對象記錄 appRoles 屬性。
在 Graph 總管中，將方法從 GET 變更為 PATCH。
將先前記錄到 Graph Explorer 的 [要求本文] 窗格中的 appRoles 屬性，針對您要刪除的角色將 IsEnabled 值設定為 false，然後選取 [執行查詢] 以執行修補作業。必須先停用角色，才能刪除角色。
停用角色之後，請從 appRoles 區段刪除該角色區塊。將方法保留為 PATCH，然後再次選取 [ 執行查詢 ]。

下一步

如需自定義宣告的相關信息，請參閱自定義企業應用程式的 SAML 令牌中發出的宣告。

分享方式：