使用 MSAL4J 搭配 Azure Active Directory B2C 啟用 Java WebSphere 應用程式的登入

本文示範一個 Java Servlet 應用程式，說明如何使用 適用於 Java 的 Microsoft Authentication Library (MSAL4J)，根據 Azure Active Directory B2C (Azure AD B2C) 驗證使用者。

注意

自 2025 年 5 月 1 日起，Azure Active Directory B2C 不再對新客戶開放購買。 現有客戶仍可繼續使用 Azure AD B2C，支援至少持續至 2030 年 5 月。 對於新的客戶身份與存取管理（CIAM）專案，請改用 Microsoft Entra 外部 ID。

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

顯示應用程式拓撲的圖表。

應用程式會使用 MSAL4J 讓使用者登入，並從 Azure AD B2C 取得 識別碼權杖。 ID 憑證證明使用者是針對 Azure AD B2C 租戶進行認證的。

必要條件

  • JDK 版本 8 或更新版本
  • Maven 3
  • Azure AD B2C 租用戶。 如需更多資訊，請參閱 教學課程：建立 Azure Active Directory B2C 租用戶
  • 您 Azure AD B2C 租用戶中的使用者帳戶。
  • WebSphere
  • 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/1-Authentication/sign-in-b2c

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

重要

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

在您的 Azure AD B2C 租用戶中註冊範例應用程式

此範例隨附預先註冊的應用程式以供測試之用。 如果您想要使用自己的 Azure AD B2C 租使用者和應用程式，請遵循下列各節中的步驟，在 Azure 入口網站 中註冊和設定應用程式。 否則，請繼續執行 執行範例 中的步驟。

選擇您想要在其中建立應用程式的 Azure AD B2C 租用戶

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

  1. 登入 Azure 入口網站。

  2. 如果您的帳戶位於一個以上的 Azure AD B2C 租用戶中，請在 Azure 入口網站的角落選取您的個人資料，然後選取 切換目錄，將您的工作階段切換到所需的 Azure AD B2C 租用戶。

建立使用者流程和自定義原則

若要建立常見的使用者流程，例如註冊、登入、編輯設定檔和重設密碼，請參閱 教學課程：在 Azure Active Directory B2C 中建立使用者流程。

您也應考慮建立 Azure Active Directory B2C 中的自訂原則，不過，這超出了本教學的範圍。

新增外部識別提供者

請參閱 教學課程：在 Azure Active Directory B2C 中將識別提供者新增至您的應用程式。

註冊應用程式（ms-identity-b2c-java-servlet-webapp-authentication）

若要註冊應用程式，請使用下列步驟：

  1. 瀏覽至 Azure 入口網站，然後選取 Azure AD B2C。

  2. 在瀏覽窗格中選取 [應用程式註冊 ]，然後選取 [ 新增註冊]。

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

    • 在 名稱 區段中，輸入有意義的應用程式名稱，供應用程式使用者查看，例如 。
    • 在 支援的帳戶類型 下，選取 任何組織目錄中的帳戶及個人 Microsoft 帳戶（例如 Skype、Xbox、Outlook.com）。
    • 在 重新導向 URI（選用） 區段中，於下拉式方塊中選取 Web，然後輸入下列重新導向 URI：。

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

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

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

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

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

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

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

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

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

設定應用程式 (ms-identity-b2c-java-servlet-webapp-authentication) 以使用您的應用程式註冊資料

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

注意

在以下步驟中， 與 或 相同。

  1. 在 IDE 中開啟專案。

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

  3. 找出 屬性，並將現有值取代為 Azure 入口網站中 應用程式的應用程式識別碼或 。

  4. 找出 屬性，並將現有值替換為您先前在 Azure 入口網站中建立 應用程式時儲存的值。

  5. 找到 屬性，並將現有的應用程式 clientId 替換為您在本節步驟 1 中填入 的值。

  6. 找出 屬性，並將第一個 取代為您在 Azure 入口網站中建立 應用程式時所使用的 Azure AD B2C 租用戶名稱。

  7. 找出 屬性，然後將第二個 出現處取代為您在 Azure 入口網站中建立 應用程式所在的 Azure AD B2C 租用戶名稱。

  8. 找出 aad.signInPolicy 屬性，並將其取代為您在 Azure 入口網站中建立 ms-identity-b2c-java-servlet-webapp-authentication 應用程式時所使用之 Azure AD B2C 租用戶中建立的註冊/登入使用者流程原則名稱。

  9. 找出 屬性，並將其替換為您在 Azure 入口網站中建立 應用程式所在的 Azure AD B2C 租用戶中所建立的密碼重設使用者流程原則名稱。

  10. 找出 屬性，並將其取代為您在 Azure 入口網站中建立 應用程式的 Azure AD B2C 租用戶內所建立之編輯設定檔使用者流程原則名稱。

建置範例

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

mvn clean package

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

執行範例

這些指示假設您已安裝 WebSphere 並設定伺服器。 您可以使用 在 Azure 虛擬機器上部署 WebSphere Application Server（傳統）叢集 中的指引，來進行基本的伺服器設定。

在部署至 WebSphere 之前，請使用下列步驟在範例本身進行一些組態變更，然後建置或重建套件：

  1. 前往應用程式的 authentication.properties 檔案，並將 的值變更為您計畫使用的伺服器 URL 和埠號碼，如下列範例所示：

    # 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://<server-url>:<port-number>/msal4j-servlet-auth/

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

    mvn clean package

  3. 程式代碼完成建置之後，請將 .war 檔案複製到目標伺服器的文件系統。

您也需要在 Azure 應用程式註冊中進行相同的變更，您可以在 Azure 入口網站 中將它設定為 [驗證] 索引標籤上的 [重新導向 URI] 值。

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

  2. 使用搜尋方塊搜尋您的應用程式註冊，例如 。

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

  4. 從選單中選擇 驗證。

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

  6. 填入您的應用程式 URI，並在後面加上 /auth/redirect；例如：。

  7. 選取 儲存。

使用下列步驟，使用 WebSphere 的整合式解決方案控制台來部署範例：

  1. 在 [應用程式] 索引標籤上，選取 [新增應用程式]，然後選取 [新增企業應用程式]。

  2. 選擇您建置的 .war 檔案，然後選取 下一步，直到您進入 對應 Web 模組的內容根目錄 安裝步驟。 其他預設設定應該沒問題。

  3. 對於內容根，請將其設為與您在範例組態/Azure 應用程式註冊中設定的「重新導向 URI」內埠號後面的值相同。 也就是說，如果重新導向 URI 是 ，則內容根應為 。

  4. 選取 完成。

  5. 應用程式完成安裝之後，請移至 [應用程式] 索引標籤的 [WebSphere 企業應用程式] 區段。

  6. 從應用程式清單中選取您安裝的 .war 檔案，然後選取 [開始部署]。

  7. 部署完成後，瀏覽至 ，您應該就能看到該應用程式。

探索範例

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

  1. 請注意畫面中央顯示的已登入或註銷狀態。
  2. 選取角落的情境相關按鈕。 當您第一次開啟應用程式時，此按鈕會顯示為 登入。
  3. 在下一個頁面上，遵循指示，並使用所選身分識別提供者的帳戶登入。
  4. 請注意，上下文相關按鈕現在會顯示 [註銷 ] 並顯示您的用戶名稱。
  5. 選取ID 權杖詳細資料即可查看 ID 權杖部分已解碼的宣告。
  6. 您也可以選擇編輯個人資料。 選取連結以編輯詳細數據，例如您的顯示名稱、居住地和職業。
  7. 使用角落的按鈕登出。
  8. 登出後，請前往下列 URL 以查看權杖詳細資料頁面：。 在這裡，您可以看到應用程式顯示的是 錯誤，而不是 ID 權杖宣告。

關於程式碼

此範例示範如何使用 MSAL4J 讓使用者登入您的 Azure AD B2C 租用戶。

目錄

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

檔案/資料夾 描述
AuthHelper.java 用於身分驗證的輔助函式。
Config.java 在啟動時執行，並設定屬性讀取器和記錄器。
authentication.properties Microsoft Entra 識別碼和程序設定。
AuthenticationFilter.java 將對受保護資源的未經驗證請求重新導向至 401 頁面。
MsalAuthSession 以 建立執行個體。 將所有 MSAL 相關的工作階段屬性儲存在工作階段屬性中。
*Servlet.java 所有可用的端點都定義在 Java 類別中，名稱結尾為 Servlet.。
CHANGELOG.md 範例的變更清單。
CONTRIBUTING.md 參與範例的指導方針。
許可證 範例的授權條款。

ConfidentialClientApplication

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

IClientSecret secret = ClientCredentialFactory.createFromSecret(SECRET);
confClientInstance = ConfidentialClientApplication
                     .builder(CLIENT_ID, secret)
                     .b2cAuthority(AUTHORITY + policy)
                     .build();

下列參數用於具現化：

  • 應用程式的用戶端識別碼。
  • 客戶端密碼，這是機密用戶端應用程式的需求。
  • 將 Azure AD B2C Authority 與適當的 串接，用於註冊、登入、設定檔編輯或密碼重設。

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

逐步解說

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

  1. 登入程序的第一個步驟，是將要求傳送到您 Azure Active Directory B2C 租用戶的 端點。 MSAL4J 執行個體可用來建構授權要求 URL，而應用程式會將瀏覽器重新導向到此 URL，如下列範例所示：

    final ConfidentialClientApplication client = getConfidentialClientInstance(policy);
final AuthorizationRequestUrlParameters parameters = AuthorizationRequestUrlParameters
    .builder(REDIRECT_URI, Collections.singleton(SCOPES)).responseMode(ResponseMode.QUERY)
    .prompt(Prompt.SELECT_ACCOUNT).state(state).nonce(nonce).build();

final String redirectUrl = client.getAuthorizationRequestUrl(parameters).toString();
Config.logger.log(Level.INFO, "Redirecting user to {0}", redirectUrl);
resp.setStatus(302);
resp.sendRedirect(redirectUrl);

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

    • ：為了建置 AuthorizationRequestUrl 而必須設定的參數。

    • ：Azure AD B2C 在收集使用者認證後，會將瀏覽器連同授權碼重新導向至的位置。

    • ：範圍是應用程式要求的權限。

      一般來說，這三個範圍 就足以接收 ID 權杖回應。 不過，MSAL4J 要求來自 Azure AD B2C 的所有回應也包含存取令牌。

      為了讓 Azure AD B2C 分配存取令牌和標識碼令牌，要求必須包含額外的資源範圍。 因為此應用程式實際上不需要外部資源範圍，所以它會將自己的用戶端標識元新增為第四個範圍，以接收存取令牌。

      您可以在 authentication.properties 檔案中找到應用程式所要求的範圍完整清單。

    • ：Azure AD B2C 可以在 HTTP POST 請求中以表單參數的形式傳回回應，或在 HTTP GET 請求中以查詢字串參數的形式傳回回應。

    • ：Azure AD B2C 應要求使用者選取他們打算用來進行驗證的帳戶。

    • ：應用程式在每次權杖要求時設定到工作階段中的唯一變數，並在收到對應的 Azure AD B2C 重新導向回呼後刪除。 狀態變數可確保 Azure AD B2C 對 的請求，確實來自此應用程式和此工作階段所發起的 Azure AD B2C 授權要求，從而防止 CSRF 攻擊。 這會在 AADRedirectServlet.java 檔案中完成。

    • ：應用程式在每次權杖請求時設定到工作階段中的唯一變數，並會在收到對應的權杖後刪除。 此 nonce 會寫入 Azure AD B2C 發出的結果權杖中，從而確保不會發生權杖重放攻擊。

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

  3. 接著， 執行個體會將此授權碼向 Azure Active Directory B2C 交換為識別碼權杖和存取權杖，如下列範例所示：

    final AuthorizationCodeParameters authParams = AuthorizationCodeParameters
                    .builder(authCode, new URI(REDIRECT_URI))
                    .scopes(Collections.singleton(SCOPES)).build();

final ConfidentialClientApplication client = AuthHelper
        .getConfidentialClientInstance(policy);
final Future<IAuthenticationResult> future = client.acquireToken(authParams);
final IAuthenticationResult result = future.get();

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

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

  4. 如果 acquireToken 成功，則會擷取令牌宣告，且 nonce 宣告會針對儲存在會話中的 nonce 進行驗證，如下列範例所示：

    parseJWTClaimsSetAndStoreResultInSession(msalAuth, result, serializedTokenCache);
validateNonce(msalAuth)
processSuccessfulAuthentication(msalAuth);

  5. 如果 nonce 驗證成功，驗證狀態會存入伺服器端工作階段，並利用 類別所公開的方法，如下列範例所示：

    msalAuth.setAuthenticated(true);
msalAuth.setUsername(msalAuth.getIdTokenClaims().get("name"));

其他相關資訊

  • 什麼是 Azure Active Directory B2C？
  • 可在 Active Directory B2C 中使用的應用程式類型
  • Azure Active Directory B2C 的建議與最佳做法
  • Azure AD B2C 工作階段
  • 適用於 Java 的 Microsoft 驗證程式庫 (MSAL)

如需了解 OAuth 2.0 通訊協定如何在此案例及其他案例中運作的詳細資訊，請參閱 Microsoft Entra ID 的驗證案例。

後續步驟

將 Java WebSphere 應用程式部署至 Azure 虛擬機器上的 Traditional WebSphere

  • Last updated on