使用 Microsoft Entra 識別碼啟用 Java Tomcat 應用程式的登入

本文示範使用適用於 Java 的 Microsoft 驗證連結庫 （MSAL） 登入使用者的 Java Tomcat 應用程式，以登入您的 Microsoft Entra ID 租使用者。

下圖顯示應用程式的拓撲：

用戶端應用程式會使用 MSAL for Java （MSAL4J） 將使用者登入自己的Microsoft Entra ID 租使用者，並從 Microsoft Entra ID 取得標識符 令牌 。 標識元令牌會證明使用者已使用此租用戶進行驗證。 應用程式會根據使用者的驗證狀態保護其路由。

必要條件

• JDK 第 8 版或更高版本
• Maven 3
• Microsoft Entra ID 租用戶。 如需詳細資訊，請參閱 如何取得Microsoft Entra ID 租使用者。
• 如果您想要只使用組織目錄中的帳戶，則您自己Microsoft Entra ID 租使用者的用戶帳戶，也就是在單一租使用者模式中。 如果您尚未在 Microsoft Entra ID 租使用者中建立使用者帳戶，您應該先這樣做，再繼續。 如需詳細資訊，請參閱 如何建立、邀請和刪除使用者。
• 如果您想要在任何組織目錄中使用任何組織目錄中的帳戶，則為任何組織的 Microsoft Entra ID 租使用者中的用戶帳戶，也就是在多租使用者模式中。 您必須修改此範例，才能使用個人Microsoft帳戶。 如果您尚未在Microsoft Entra ID 租使用者中建立用戶帳戶，您應該先這樣做，再繼續。 如需詳細資訊，請參閱 如何建立、邀請和刪除使用者。
• 如果您想要使用個人Microsoft帳戶，例如 Xbox、Hotmail、Live 等個人Microsoft帳戶。

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

建議

• 一些熟悉 Java/Jakarta Servlets。
• 一些熟悉 Linux/OSX 終端機。
• jwt.ms 檢查令牌。
• Fiddler 用於監視您的網路活動和疑難解答。
• 請遵循Microsoft Entra ID 部落格，隨時掌握最新的發展。

設定範例

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

複製或下載範例存放庫

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

git clone https://github.com/Azure-Samples/ms-identity-msal-java-samples.git
cd 3-java-servlet-web-app/1-Authentication/sign-in

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

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

此範例中有一個專案。 本節說明如何註冊應用程式。

首先，依照快速入門：向 Microsoft 身分識別平台 註冊應用程式，以在 Azure 入口網站 中註冊應用程式。

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

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

2. 選取新增註冊。

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

   • 在 [ 名稱] 區段中，輸入有意義的應用程式名稱，以顯示給應用程式的使用者 ，例如 java-servlet-webapp-authentication。

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

     • 只有在您要建置應用程式以供租使用者中的使用者使用時，才選取此組織目錄中的 [帳戶]，也就是單一租用戶應用程式。
     • 如果您想要任何Microsoft Entra ID 租使用者中的用戶能夠使用您的應用程式，請選取 [任何組織目錄中的帳戶]，也就是多租用戶應用程式。
     • 針對最廣泛的客戶，選取 任何組織目錄中的帳戶和個人Microsoft帳戶 ，也就是同時支援Microsoft個人帳戶的多租用戶應用程式。
     • 選取 [個人Microsoft帳戶]，僅供個人Microsoft帳戶 的使用者使用 -- 例如 Hotmail、Live、Skype 和 Xbox 帳戶。

   • 在 [ 重新導向 URI] 區段中，選取 下拉式方塊中的 [Web ]，然後輸入下列重新導向 URI： http://localhost:8080/msal4j-servlet-auth/auth/redirect。

4. 選取 [暫存器] 以建立應用程式。

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

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

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

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

9. 選取其中一個可用的持續時間： 在1年、 2年內或 永不過期。

10. 選取 [新增]。 產生的值隨即顯示。

11. 複製並儲存產生的值，以供後續步驟使用。 您需要此值才能用於程式代碼的組態檔。 此值不會再次顯示，而且您無法透過任何其他方式加以擷取。 因此，請務必先從 Azure 入口網站 儲存它，再流覽至任何其他畫面或窗格。

設定應用程式以使用您的應用程式註冊

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

1. 在 IDE 中開啟專案。

2. 開啟 ./src/main/resources/authentication.properties 檔案。

3. 尋找字串 {enter-your-tenant-id-here}。 以下欄其中一個值取代現有的值：

   • 如果您僅向 此組織目錄中 的帳戶註冊應用程式，則Microsoft Entra ID 租使用者標識碼。
   • 如果您在任何組織目錄選項的 [帳戶] 中註冊應用程式，則為這個字organizations。
   • 如果您使用任何組織目錄中的帳戶和個人Microsoft帳戶選項註冊應用程式，則為這個字common。
   • 如果您使用 [個人Microsoft帳戶] 選項註冊應用程式，則為這個字consumers。

4. 尋找字串{enter-your-client-id-here}，並將現有的值取代為從 Azure 入口網站 複製的應用程式識別碼或clientIdjava-servlet-webapp-authentication應用程式。

5. 尋找字串{enter-your-client-secret-here}，並將現有的值取代為您在java-servlet-webapp-authentication建立應用程式期間儲存的值，並在 Azure 入口網站 中。

建置範例

若要使用 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. 選取 [ 標識符令牌詳細數據 ]，以查看一些標識符令牌已譯碼的宣告。
7. 使用角落中的按鈕註銷。
8. 註銷之後，選取 [ 標識符令牌詳細數據 ]，觀察應用程式在使用者未獲授權時顯示 401: unauthorized 錯誤，而不是標識符令牌宣告。

關於程式碼

此範例示範如何使用 MSAL for Java （MSAL4J） 將使用者登入您的 Microsoft Entra ID 租使用者。 如果您想要在自己的應用程式中使用 MSAL4J，您必須使用 Maven 將它新增至專案。

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

目錄

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

ConfidentialClientApplication

ConfidentialClientApplication實例會在 AuthHelper.java 檔案中建立，如下列範例所示。 此對象有助於製作Microsoft Entra ID 授權 URL，也有助於交換存取令牌的驗證令牌。

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

下列參數用於具現化：

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

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

逐步解說

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

1. 登入程式的第一個步驟是將要求傳送至 /authorize 您Microsoft Entra ID 租使用者的端點。 MSAL4J ConfidentialClientApplication 實例可用來建構授權要求 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);
   

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

   • AuthorizationRequestUrlParameters：必須設定的參數，才能建置 AuthorizationRequestUrl。

   • REDIRECT_URI：其中Microsoft Entra ID 會在收集使用者認證之後重新導向瀏覽器，以及驗證碼。 它必須符合 Azure 入口網站 中Microsoft Entra ID 應用程式註冊中的重新導向 URI。

   • SCOPES： 範圍 是應用程式要求的許可權。 一般而言，三個範圍 openid profile offline_access 足以接收標識符令牌回應。

     您可以在 authentication.properties 檔案中找到應用程式所要求的範圍完整清單。 您可以新增更多範圍，例如 User.Read。

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

3. 然後，實例 ConfidentialClientApplication 會針對標識符令牌交換此授權碼，並從 entra ID Microsoft存取令牌。

   // 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();
   

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

   • AuthorizationCodeParameters：必須設定的參數，才能交換標識符和/或存取令牌的授權碼。
   • authCode：在重新導向端點收到的授權碼。
   • REDIRECT_URI：必須再次傳遞上一個步驟中使用的重新導向 URI。
   • SCOPES：必須再次傳遞上一個步驟中使用的範圍。

4. 如果 acquireToken 成功，則會擷取權杖宣告。 如果 nonce 檢查通過，結果會放在 context - 實例 IdentityContextData 中，並儲存至會話。 然後，應用程式可以透過 IdentityContextAdapterServlet 實例從會話具現化IdentityContextData，只要需要存取它，如下列程式代碼所示：

   // 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 檔案中app.protect.authenticated，屬性包含只有已驗證使用者可以存取的逗號分隔路由，如下列範例所示：

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

範圍

範圍會告訴Microsoft Entra標識符應用程式所要求的存取層級。

根據要求的範圍，Microsoft Entra ID 會在登入時向用戶顯示同意對話。 如果使用者同意一或多個範圍並取得令牌，則 scopes-consented-to 會編碼為產生的 access_token。

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

其他相關資訊

• 適用於 Java 的 Microsoft 驗證程式庫 (MSAL)
• MSAL Java 參考檔
• Microsoft 身分識別平台 （適用於開發人員的Microsoft Entra ID）
• 快速入門：使用 Microsoft 身分識別平台來註冊應用程式
• 瞭解Microsoft Entra ID 應用程式同意體驗
• 瞭解使用者和系統管理員同意
• MSAL 程式代碼範例