將應用程式角色新增至您的應用程式，並在權杖中接收這些角色

角色型存取控制 (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 強制執行。 如需這些限制的相關信息，請參閱 entra 應用程式指令清單參考Microsoft的指令清單限制一節。

應用程式角色 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 時，這些令牌可以是存取令牌。 如果設定為停用，它就會變成非使用中且無法再指派。 任何先前的被指派者仍會將應用程式角色包含在其令牌中，但它不會有任何作用，因為它不再主動可指派。

指派應用程式擁有者

如果您尚未這麼做，則必須將自己指派為應用程式擁有者。

1. 在您的應用程式註冊中，於 [管理] 底下選取 [擁有者]，然後再選取 [新增擁有者]。
2. 在新的視窗中，尋找並選取您要指派給應用程式的擁有者。 選取的擁有者會出現在右面板中。 完成後，請透過 [選取] 進行確認。 應用程式擁有者現在將出現在擁有者的清單中。

注意

請確定您想要將權限新增至的 API 應用程式和應用程式兩者都有擁有者，否則要求 API 權限時，系統不會列出 API。

將應用程式角色指派給應用程式

在應用程式中新增應用程式角色之後，您可以使用 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：驗證範圍和應用程式角色。

應用程式角色與群組

雖然您可以使用應用程式角色或群組來進行授權，但它們之間的主要差異可能會影響您決定要用於您的案例的項目。

應用程式角色	群組
這些角色專屬應用程式，並在應用程式註冊中定義。 其會隨著應用程式移動。	它們並非專屬於應用程式，而是Microsoft Entra 租使用者。
移除應用程式的應用程式註冊時，會移除應用程式角色。	即使移除應用程式，群組仍保持不變。
在宣告中 roles 提供。	在 groups 宣告中提供。

開發人員可以使用應用程式角色，以控制使用者是否可登入應用程式，或應用程式是否可取得 Web API 的存取權杖。 若要將此安全性控制延伸至群組，開發人員和管理員也可以將安全性群組指派給應用程式角色。

開發人員若想要自行在應用程式中描述並控制授權的參數，則更偏好使用應用程式角色。 例如，使用群組進行授權的應用程式將在下一個租用戶故障，因為群組識別碼和名稱可能不同。 使用應用程式角色的應用程式會保持安全無虞。 事實上，將群組指派給應用程式角色是 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 應用程式資訊清單
• 影片：使用 Microsoft 身分識別平台在您的應用程式中實作授權 (1:01:15)