設定角色宣告

發行項
11/23/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 總管 [要求本文] 窗格的 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 總管的 [要求本文] 窗格，新增更新角色定義，然後選取 [執行查詢] 來執行修補作業。

刪除角色

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

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

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

下一步

如需自訂宣告的相關資訊，請參閱自訂企業應用程式 SAML 權杖中發出的宣告 (部分機器翻譯)。

共用方式為