使用角色和角色宣告資訊來保護 Java Tomcat 應用程式

本文示範一個使用 OpenID Connect 讓使用者登入，並使用 Microsoft Entra ID Application Roles (app roles) 進行授權的 Java Tomcat 應用程式。

此應用程式會使用Microsoft Entra ID 的應用程式角色和角色宣告功能，實作角色型訪問控制 （RBAC）。 另一種方法是使用 Microsoft Entra ID 群組和群組宣告。 Microsoft Entra 標識符群組和應用程式角色並非互斥。 您可以同時使用兩者來提供細微的存取控制。

您也可以使用 RBAC 搭配應用程式角色和角色宣告，安全地強制執行授權原則。

若要觀看涵蓋此情境和此範例的影片，請參閱 使用應用程式角色、安全性群組、範圍和目錄角色，在您的應用程式中實作授權。

如需有關這些通訊協定在此案例和其他案例中如何運作的詳細資訊，請參閱 驗證與授權。

此應用程式使用 MSAL for Java (MSAL4J) 讓使用者登入，並從 Microsoft Entra ID 取得 ID 權杖。

此範例會先使用 MSAL for Java （MSAL4J） 來登入使用者。 首頁會顯示一個選項，讓使用者檢視其 ID 權杖中的聲明。 此應用程式也可讓用戶檢視特殊許可權系統管理員頁面或一般用戶頁面，視他們獲指派的應用程式角色而定。 其概念是提供一個範例，說明應用程式內特定功能或頁面的存取權受限於用戶子集，視使用者所屬的角色而定。

這種授權是使用 RBAC 實作。 使用 RBAC 時，系統管理員會將許可權授與角色，而不是授與個別使用者或群組的許可權。 系統管理員接著可以將角色指派給不同的使用者和群組，以控制誰可以存取特定內容和功能。

這個範例應用程式會定義下列兩 個應用程式角色：

• ：已獲授權可存取 僅限管理員 和 一般使用者 頁面。
• ：已獲授權存取 一般使用者 頁面。

這些應用程式角色是在 Azure 入口網站中的應用程式註冊資訊清單內定義的。 當使用者登入應用程式時，Microsoft Entra ID 會針對以角色成員資格形式個別授與給使用者的每個角色發出角色宣告。

您可以透過 Azure 入口網站 將使用者和群組指派給角色。

必要條件

• JDK 版本 8 或更新版本
• Maven 3
• Microsoft Entra ID 租用戶。 如需更多資訊，請參閱 如何取得 Microsoft Entra ID 租用戶。
• 如果您想要僅使用組織目錄中的帳戶，也就是單一租用戶模式，則需使用您自己的 Microsoft Entra ID 租用戶中的使用者帳戶。 如果您尚未在您的租用戶中建立使用者帳戶，請先建立帳戶，再繼續操作。 如需更多資訊，請參閱 如何建立、邀請和刪除使用者。

• Tomcat 9
• Visual Studio Code
• 適用於 Visual Studio Code 的 Azure 工具

建議

• 對 Java / Jakarta Servlets 有一些基本了解。
• 對 Linux/OSX 終端機操作有基本了解。
• jwt.ms 用於檢查您的權杖。
• Fiddler 用於監控您的網路活動及進行疑難排解。
• 關注 Microsoft Entra 部落格，隨時掌握最新發展。

設定範例

下列各節說明如何設定範例應用程式。

複製或下載範例存放庫

若要複製範例，請開啟Bash視窗，並使用下列命令：

git clone https://github.com/Azure-Samples/ms-identity-msal-java-samples.git
cd 3-java-servlet-web-app/3-Authorization-II/roles

或者，瀏覽至 ms-identity-msal-java-samples 存放庫，然後將其下載為 .zip 檔案，並解壓縮到您的硬碟。

在 Microsoft Entra ID 租用戶中註冊範例應用程式

此範例中有一個專案。 下列各節說明如何使用 Azure 入口網站 註冊應用程式。

選擇您要在其中建立應用程式的 Microsoft Entra ID 租用戶

若要選擇您的租使用者，請使用下列步驟：

1. 登入 Azure 入口網站。

2. 如果您的帳戶存在於一個以上的 Microsoft Entra ID 租用戶中，請在 Azure 入口網站右上角選取您的個人檔案，然後選取 切換目錄，將您的工作階段切換至所需的 Microsoft Entra ID 租用戶。

註冊應用程式 （java-servlet-webapp-roles）

首先，請依照 快速入門：使用 Microsoft 身分識別平台註冊應用程式 中的指示，在 Azure 入口網站 中註冊新應用程式。

然後，使用下列步驟來完成註冊：

1. 瀏覽至 Microsoft 身分識別平台開發人員適用的 應用程式註冊 頁面。

2. 選取 新增註冊。

3. 在出現的 [ 註冊應用程式] 頁面中 ，輸入下列應用程式註冊資訊：

   • 在名稱區段中，輸入一個具意義的應用程式名稱，供應用程式使用者查看，例如 。

   • 在 [支持的帳戶類型] 底下，選取下列其中一個選項：

     • 如果您正在建置的應用程式僅供您租用戶中的使用者使用，請選取 僅此組織目錄中的帳戶；也就是說，這是 單一租用戶 應用程式。

   • 在 重新導向 URI 區段中，於下拉式方塊選取 Web，然後輸入下列重新導向 URI：。

4. 選取 註冊 以建立應用程式。

5. 在應用程式的註冊頁面上，尋找並複製 應用程式 （用戶端） 識別碼 值，以供稍後使用。 您會在應用程式的組態檔或檔案中使用此值。

6. 選取儲存以儲存變更。

7. 在應用程式的註冊頁面上，選取 瀏覽窗格中的 [憑證和秘密 ]，以開啟您可以產生秘密並上傳憑證的頁面。

8. 在用戶端密碼區段底下，選取新增用戶端密碼。

9. 輸入描述 - 例如， 應用程式秘密。

10. 選取祕密的到期日，或指定自訂存留期。 用戶端機密的有效期限限制為 24 個月，Microsoft 建議有效期少於 12 個月。 對於生產應用程式，建議使用憑證或聯邦身份憑證，而非用戶端秘密。

11. 選取新增。 產生的值隨即顯示。

12. 複製並儲存產生的值，以供後續步驟使用。 您需要此值用於您的程式碼設定檔。 此值不會再次顯示，而且您無法透過任何其他方式加以擷取。 因此，請務必先在 Azure 入口網站中將其儲存，再切換到任何其他畫面或窗格。

定義應用程式角色

若要定義應用程式角色，請使用下列步驟：

1. 在同一個應用程式註冊中，於導覽窗格選取 應用程式角色。

2. 選取 [ 建立應用程式角色]，然後輸入下列值：

   • 針對 [ 顯示名稱]，輸入適當的名稱，例如 PrivilegedAdmin。
   • 針對 [ 允許的成員類型]，選擇 [ 使用者]。
   • 在值中輸入PrivilegedAdmin。
   • 在 Description 中，輸入 可檢視管理頁面的 PrivilegedAdmins。

3. 選取 [ 建立應用程式角色]，然後輸入下列值：

   • 針對 [ 顯示名稱]，輸入適當的名稱，例如 RegularUser。
   • 針對 [ 允許的成員類型]，選擇 [ 使用者]。
   • 在 值 中，輸入 RegularUser。
   • 在描述中，輸入可檢視使用者頁面的 RegularUsers。

4. 選取 [套用] 以儲存變更。

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

若要將使用者新增至稍早定義的應用程式角色，請參閱這裡的指引：將使用者和群組指派給角色。

設定應用程式 （java-servlet-webapp-roles） 以使用您的應用程式註冊

使用下列步驟來設定應用程式：

1. 在 IDE 中開啟專案。

2. 開啟 authentication.properties 檔案。

3. 找出字串 。 以您的 Microsoft Entra ID 租使用者識別碼取代現有的值。

4. 尋找字串 ，並將現有的值取代為從 Azure 入口網站複製的 應用程式的應用程式識別碼或 。

5. 尋找字串 ，然後將現有值替換為您先前在 Azure 入口網站中建立 應用程式時所儲存的值。

6. 找出 屬性，並確認其值設為 ，或替換成您特定角色的名稱。

建置範例

若要使用 Maven 建置範例，請流覽至包含 範例pom.xml 檔案的目錄，然後執行下列命令：

mvn clean package

此命令會產生 您可以在各種應用程式伺服器上執行的 .war 檔案。

執行範例

Please confirm webapp properties
AppName : msal4j-servlet-auth-1707209552268
ResourceGroup : msal4j-servlet-auth-1707209552268-rg
Region : centralus
PricingTier : P1v2
OS : Linux
Java Version: Java 11
Web server stack: Tomcat 9.0
Deploy to slot : false
Confirm (Y/N) [Y]: [INFO] Saving configuration to pom.
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  37.112 s
[INFO] Finished at: 2024-02-06T08:53:02Z
[INFO] ------------------------------------------------------------------------

<build>
    <plugins>
        <plugin>
            <groupId>com.microsoft.azure</groupId>
            <artifactId>>azure-webapp-maven-plugin</artifactId>
            <version>x.xx.x</version>
            <configuration>
                <schemaVersion>v2</schemaVersion>
                <resourceGroup>your-resourcegroup-name</resourceGroup>
                <appName>your-app-name</appName>
            ...
            </configuration>
        </plugin>
    </plugins>
</build>

az login

mvn package azure-webapp:deploy

探索範例

使用下列步驟來探索範例：

1. 請注意畫面中央顯示的已登入或註銷狀態。
2. 選取角落中的上下文相關按鈕。 當您第一次執行應用程式時，此按鈕會顯示為登入。
3. 在下一個頁面上，遵循指示，並使用 Microsoft Entra ID 租使用者中的帳戶登入。
4. 在同意畫面上，請注意所要求的範圍。
5. 請注意，上下文相關按鈕現在會顯示 [註銷 ] 並顯示您的用戶名稱。
6. 選取ID 權杖詳細資料即可查看 ID 權杖部分已解碼的宣告。
7. 選取僅限管理員以檢視頁面。 只有具有應用程式角色 的使用者才能檢視此頁面。 否則，會顯示授權失敗訊息。
8. 選取一般使用者以檢視頁面。 只有具有應用程式角色 或 的使用者才能檢視此頁面。 否則，會顯示授權失敗訊息。
9. 使用角落的按鈕登出。

關於程式碼

此範例使用 MSAL for Java (MSAL4J) 讓使用者登入，並取得可能包含角色宣告的 ID 權杖。 根據目前具備的角色宣告，已登入的使用者可以存取兩個受保護頁面 `` 和 `` 中的都不能、其中一個或兩者。

如果您想要重現此範例的行為，可以複製 pom.xml 檔案，以及 src/main/java/com/microsoft/azuresamples/msal4j 資料夾中的 helpers 和 authservlets 資料夾內容。 您也需要 authentication.properties 檔案。 這些類別和檔案包含一般程式代碼，您可以在各種應用程式中使用。 您也可以複製範例的其餘部分，但會特別建置其他類別和檔案，以解決此範例的目標。

目錄

下表顯示範例項目資料夾的內容：

在 ID 權杖中處理角色宣告

令牌的角色宣告包含已登入使用者指派的角色名稱，如下列範例所示：

{
  ...
  "roles": [
    "Role1",
    "Role2",]
  ...
}

ConfidentialClientApplication

系統會在 AuthHelper.java 檔案中建立 執行個體，如下列範例所示。 此物件有助於產生 Microsoft Entra 授權 URL，也有助於將驗證權杖交換為存取權杖。

// getConfidentialClientInstance method
IClientSecret secret = ClientCredentialFactory.createFromSecret(SECRET);
confClientInstance = ConfidentialClientApplication
                     .builder(CLIENT_ID, secret)
                     .authority(AUTHORITY)
                     .build();

下列參數用於具現化：

• 應用程式的用戶端識別碼。
• 客戶端密碼，這是機密用戶端應用程式的需求。
• Microsoft Entra ID 授權單位，其中包含您的 Microsoft Entra 租用戶 ID。

在此範例中，這些值會使用 Config.java 檔案中的屬性讀取器，從 authentication.properties 檔案中讀取。

逐步解說

下列步驟提供應用程式的功能的逐步解說：

1. 登入程序的第一個步驟，是向您 Microsoft Entra ID 租用戶上的 端點傳送要求。 MSAL4J 實例用於建構授權請求 URL。 應用程式會將瀏覽器重新導向至此 URL，也就是使用者登入的位置。

   final ConfidentialClientApplication client = getConfidentialClientInstance();
   AuthorizationRequestUrlParameters parameters = AuthorizationRequestUrlParameters.builder(Config.REDIRECT_URI, Collections.singleton(Config.SCOPES))
           .responseMode(ResponseMode.QUERY).prompt(Prompt.SELECT_ACCOUNT).state(state).nonce(nonce).build();
   
   final String authorizeUrl = client.getAuthorizationRequestUrl(parameters).toString();
   contextAdapter.redirectUser(authorizeUrl);
   

   下列清單描述此程式碼的功能：

   • ：為了建置 AuthorizationRequestUrl 而必須設定的參數。
   • ：Microsoft Entra ID 在收集使用者認證後，將瀏覽器連同授權碼重新導向到的位置。 它必須與 Azure 入口網站 中 Microsoft Entra ID 應用程式註冊內的重新導向 URI 相符。
   • ：範圍是應用程式要求的權限。
     • 一般而言，三個範圍 即足以接收 ID 權杖回應。
     • 您可以在 authentication.properties 檔案中找到應用程式所要求的完整範圍清單。 您可以新增更多範圍，例如 。

2. 使用者會看到 Microsoft Entra ID 發出的登入提示。 如果登入嘗試成功，則會將使用者的瀏覽器重新導向至應用程式的重新導向端點。 對此端點的有效請求包含授權碼。

3. 接著， 執行個體會使用此授權碼，向 Microsoft Entra ID 換取 ID 權杖和存取權杖。

   // First, validate the state, then parse any error codes in response, then extract the authCode. Then:
   // build the auth code params:
   final AuthorizationCodeParameters authParams = AuthorizationCodeParameters
           .builder(authCode, new URI(Config.REDIRECT_URI)).scopes(Collections.singleton(Config.SCOPES)).build();
   
   // Get a client instance and leverage it to acquire the token:
   final ConfidentialClientApplication client = AuthHelper.getConfidentialClientInstance();
   final IAuthenticationResult result = client.acquireToken(authParams).get();
   

   下列清單描述此程式碼的功能：

   • ：為了將授權碼交換為 ID 權杖和/或存取權杖而必須設定的參數。
   • ：重新導向端點所接收的授權碼。
   • ：必須再次傳入上一步中使用的重新導向 URI。
   • ：必須再次傳入前一步驟中使用的範圍。

4. 如果 成功，則會擷取權杖宣告。 如果 nonce 檢查通過，結果會放入 （即 的一個執行個體）中，並儲存至工作階段。 然後，應用程式可以在每當需要存取它時，透過 的執行個體從工作階段中建立 的執行個體，如下列程式碼所示：

   // parse IdToken claims from the IAuthenticationResult:
   // (the next step - validateNonce - requires parsed claims)
   context.setIdTokenClaims(result.idToken());
   
   // if nonce is invalid, stop immediately! this could be a token replay!
   // if validation fails, throws exception and cancels auth:
   validateNonce(context);
   
   // set user to authenticated:
   context.setAuthResult(result, client.tokenCache().serialize());
   

保護路由

如需範例應用程式如何篩選路由存取的資訊，請參閱 AuthenticationFilter.java。 在 authentication.properties 檔案中， 屬性包含以逗號分隔的路由，只有已驗證的使用者可以存取這些路由，如下列範例所示：

# for example, /token_details requires any user to be signed in and does not require special roles claim(s)
app.protect.authenticated=/token_details

在 下方以逗號分隔的規則集中所列出的任何路由，也都禁止未經驗證的使用者存取，如下例所示。 不過，這些路由也包含以空格分隔的應用程式角色成員資格清單：只有至少有一個對應角色的使用者可以在驗證之後存取這些路由。

# local short names for app roles - for example, sets admin to mean PrivilegedAdmin (useful for long rule sets defined in the next key, app.protect.roles)
app.roles=admin PrivilegedAdmin, user RegularUser

# A route and its corresponding <space-separated> role(s) that can access it; the start of the next route & its role(s) is delimited by a <comma-and-space-separator>
# this says: /admins_only can be accessed by PrivilegedAdmin, /regular_user can be accessed by PrivilegedAdmin role and the RegularUser role
app.protect.roles=/admin_only admin, /regular_user admin user

範圍

範圍會告知 Microsoft Entra ID 應用程式所要求的存取權層級。

根據要求的範圍，Microsoft Entra ID 會在登入時向用戶顯示同意對話。 如果使用者同意一個或多個範圍並取得權杖，則已同意的範圍會編碼到產生的 中。

如需應用程式要求的範圍，請參閱 authentication.properties。 MSAL 會要求這三個範圍，且預設會由 Microsoft Entra ID 提供。

其他相關資訊

• 適用於 Java 的 Microsoft 驗證程式庫 (MSAL)
• Microsoft 身分識別平台
• 快速入門：在 Microsoft 身分識別平台中註冊應用程式
• 瞭解 Microsoft Entra ID 應用程式同意體驗
• 瞭解使用者和系統管理員同意
• MSAL 程式碼範例
• 操作說明：將應用程式角色新增至您的應用程式，並在權杖中接收這些角色
• 在 Microsoft Entra ID 中管理應用程式的使用者指派