Share via

使用 Microsoft Entra ID 啟用 Java Tomcat 應用程式的登入

  • 發行項

本文示範 Java Tomcat 應用程式，其會使用適用於 Java 的 Microsoft 驗證連結庫 （MSAL） 將使用者登入 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 帳戶。

建議

設定範例

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

複製或下載範例存放庫

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

git clone https://github.com/Azure-Samples/ms-identity-java-servlet-webapp-authentication.git
cd 1-Authentication/sign-in

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

重要

若要避免 Windows 上的檔案路徑長度限制，請將存放庫複製到硬碟根目錄附近的目錄中。

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

此範例中有一個專案。 若要在 Azure 入口網站 註冊應用程式，您可以遵循手動設定步驟或使用 PowerShell 腳本。 文稿會執行下列工作：

  • 建立 Microsoft Entra ID 應用程式和相關物件，例如密碼、許可權和相依性。
  • 修改專案組態檔。
  • 根據預設，設定只使用組織目錄中帳戶的應用程式。

使用下列步驟來執行 PowerShell 腳稿：

  1. 在 Windows 上，開啟 PowerShell 並瀏覽至複製目錄的根目錄。

  2. 使用下列命令來設定 PowerShell 的執行原則：

    Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process -Force

  3. 使用下列命令來執行組態文稿：

    cd .\AppCreationScripts\
.\Configure.ps1

    注意

    應用程式建立腳本會說明執行腳本的其他方式。 這些腳本也提供自動化應用程式註冊、設定和移除指南，可協助您進行 CI/CD 案例。

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

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

注意

在下列步驟中，ClientID與 或 AppId相同Application ID。

  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 檔案。

執行範例

下列各節將示範如何將範例部署至 Azure App 服務。

必要條件

設定 Maven 外掛程式

當您部署至 Azure App 服務 時，部署會自動使用 Azure CLI 中的 Azure 認證。 如果未在本機安裝 Azure CLI，Maven 外掛程式會向 OAuth 或裝置登入進行驗證。 如需詳細資訊，請參閱 使用 Maven 外掛程式進行驗證。

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

  1. 執行下列命令來設定部署。 此命令可協助您設定 Azure App 服務 操作系統、Java 版本和 Tomcat 版本。

    mvn com.microsoft.azure:azure-webapp-maven-plugin:2.12.0:config

  2. 針對 [ 建立新的執行組態]，按 Y，然後按 Enter。

  3. 針對 [定義 OS 的值]，針對 Windows 按 1，或針對 Linux 按 2，然後按 Enter。

  4. 針對 [ 定義 javaVersion 的值]，按 2 for Java 11，然後按 Enter。

  5. 針對 [ 定義 webContainer 的值]，按 4 for Tomcat 9.0，然後按 Enter。

  6. 針對 [ 定義 pricingTier 的值]，按 Enter 以選取預設 P1v2 層。

  7. 針對 [確認]，按 Y，然後按 Enter。

下列範例顯示部署程式的輸出：

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] ------------------------------------------------------------------------

確認您的選擇之後，外掛程式會將必要的外掛程式元素和設定新增至專案的pom.xml檔案，以將您的應用程式設定為在 Azure App 服務 中執行。

pom.xml檔案的相關部分看起來應該類似下列範例：

<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>

您可以直接在pom.xml中修改 App Service 的設定。 下表列出一些常見的組態：

屬性 必要 描述
subscriptionId false 訂用帳戶標識碼。
resourceGroup true 應用程式的 Azure 資源群組。
appName true 應用程式的名稱。
region false 裝載您應用程式的區域。 預設值是 centralus。 如需有效的區域，請參閱 支援的區域。
pricingTier false 應用程式的定價層。 預設值是 P1v2 生產工作負載。 Java 開發和測試的建議最小值為 B2。 如需詳細資訊，請參閱 App Service定價。
runtime false 運行時間環境組態。 如需詳細資訊，請參閱 設定詳細數據。
deployment false 部署組態。 如需詳細資訊，請參閱 設定詳細數據。

如需設定的完整清單，請參閱外掛程式參考文件。 所有 Azure Maven 外掛程式都會共用一組常見的組態。 如需這些組態，請參閱 一般組態。 如需 Azure App 服務 特定的設定，請參閱 Azure 應用程式：設定詳細數據。

請務必保留 appName 和 resourceGroup 值，以供日後使用。

準備應用程式以進行部署

當您將應用程式部署至 App Service 時，重新導向 URL 會變更為已部署應用程式實例的重新導向 URL。 使用下列步驟來變更屬性檔案中的這些設定：

  1. 流覽至應用程式的 authentication.properties 檔案，並將 的值 app.homePage 變更為已部署應用程式的功能變數名稱，如下列範例所示。 例如，如果您在上一個步驟中為應用程式名稱選擇 example-domain ，您現在 https://example-domain.azurewebsites.net 必須使用 此值 app.homePage 。 請確定您也已將通訊協定從 http 變更為 https。

    # app.homePage is by default set to dev server address and app context path on the server
# for apps deployed to azure, use https://your-sub-domain.azurewebsites.net
app.homePage=https://<your-app-name>.azurewebsites.net

  2. 儲存此檔案之後，請使用下列命令重建您的應用程式：

    mvn clean package

重要

在這個相同的 authentication.properties 檔案中，您有 一個 設定。aad.secret 將此值部署至 App Service 不是很好的做法。 在程序代碼中保留此值並可能將其推送至 Git 存放庫，這兩者都不是很好的做法。 若要從程式代碼中移除此秘密值，您可以在部署至 App Service - 移除秘密一節中找到更詳細的指引。 本指南會新增額外的步驟，以將秘密值推送至 金鑰保存庫，並使用 金鑰保存庫 參考。

更新您的 Microsoft Entra ID 應用程式註冊

因為已部署應用程式的重新導向 URI 會變更為 Azure App 服務，因此您也需要變更 Microsoft Entra ID 應用程式註冊中的重新導向 URI。 請使用下列步驟來進行此變更：

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

  2. 使用搜尋方塊來搜尋您的應用程式註冊 ，例如 java-servlet-webapp-authentication。

  3. 選取應用程式名稱以開啟您的應用程式註冊。

  4. 從選單中選擇 驗證。

  5. 在 [Web - 重新導向 URI] 區段中，選取 [新增 URI]。

  6. 填寫應用程式的 URI，並附加 /auth/redirect -例如 https://<your-app-name>.azurewebsites.net/auth/redirect。

  7. 選取 [儲存]。

部署應用程式

您現在已準備好將應用程式部署至 Azure App 服務。 使用下列命令，確定您已登入 Azure 環境以執行部署：

az login

在pom.xml檔案中備妥所有組態後，您現在可以使用下列命令將 Java 應用程式部署至 Azure：

mvn package azure-webapp:deploy

部署完成之後，您的應用程式即可在 就緒 http://<your-app-name>.azurewebsites.net/。 使用本機網頁瀏覽器開啟 URL，您應該會在其中看到應用程式的起始頁面 msal4j-servlet-auth 。

探索範例

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

  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 檔案。 這些類別和檔案包含一般程式代碼，您可以在各種應用程式中使用。 您也可以複製範例的其餘部分，但會特別建置其他類別和檔案，以解決此範例的目標。

目錄

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

檔案/資料夾 描述
AppCreationScripts/ 自動設定 Microsoft Entra ID 應用程式註冊的腳本。
src/main/java/com/microsoft/azuresamples/msal4j/authwebapp/ 此目錄包含定義應用程式後端商業規則的類別。
src/main/java/com/microsoft/azuresamples/msal4j/authservlets/ 此目錄包含用於登入和註銷端點的類別。
____Servlet.java 所有可用的端點都定義於以 ____Servlet.java 結尾的類別.java類別中。
src/main/java/com/microsoft/azuresamples/msal4j/helpers/ 驗證的協助程序類別。
AuthenticationFilter.java 將未經驗證的要求重新導向至受保護的端點至 401 頁面。
src/main/resources/authentication.properties Microsoft Entra ID 和程序設定。
src/main/webapp/ 此目錄包含 UI - JSP 範本
CHANGELOG.md 範例的變更清單。
CONTRIBUTING.md 參與範例的指導方針。
許可證 範例的授權。

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 ID Authority，其中包含您的 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 會交換此標識碼作為標識符令牌，並從 Microsoft Entra 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();

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

    • 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 提供。

其他相關資訊