使用 MSAL.js 將用戶端應用程式初始化

2025-05-13

本文說明如何使用使用者代理程式應用程式的執行個體來初始化適用於 JavaScript 的 Microsoft 驗證程式庫 (MSAL.js)。

使用者代理程式應用程式是一種公用用戶端應用程式，其中用戶端程式代碼會在使用者代理程式 (如網頁瀏覽器) 中執行。這類用戶端不會儲存祕密，因為瀏覽器內容可供公開存取。

若要深入了解用戶端應用程式類型和應用程式設定選項，請參閱 MSAL 中的公用和機密用戶端應用程式。

必要條件

在初始化應用程式之前，您必須先為其在 Microsoft Entra 系統管理中心進行註冊 (部分機器翻譯)，並在您的應用程式與 Microsoft 身分識別平台之間建立信任關聯性。

完成應用程式註冊之後，您將需要下列一些或所有的值，這些值可在 Microsoft Entra 系統管理中心中找到。

價值	必要	描述
應用程式 (用戶端) 識別碼	必要	在 Microsoft 身分識別平台中唯一識別您應用程式的唯一識別碼 (GUID)。
權威	選擇性	識別提供者 URL (稱為執行個體)，以及您應用程式的登入對象。當執行個體與登入對象串連時，會構成授權單位。
目錄 (租用戶) 識別碼	選擇性	如果您要組構僅供貴組織使用的企業營運系統應用程式 (通常稱為單一租用戶應用程式)，請指定目錄 (租用戶) 識別碼。
重新導向 URI	選擇性	如果您要組建 Web 應用程式，則 `redirectUri` 會指定身分識別提供者 (Microsoft 身分識別平台) 應傳回其所發出的安全性權杖。

初始化 MSAL.js 2.x 應用程式

藉由具現化含有 [Configuration][msal-js-configuration] 物件的 [PublicClientApplication][msal-js-publicclientapplication]，初始化 MSAL.js 驗證情境。最低要求的設定屬性是應用程式上的 clientID，其在 Azure 入口網站中應用程式註冊的 [總覽] 頁面上顯示為應用程式 (用戶端) 識別碼。

以下為設定物件的範例及PublicClientApplication的實例化：

const msalConfig = {
  auth: {
    clientId: "Enter_the_Application_Id_Here",
    authority: "https://login.microsoftonline.com/Enter_the_Tenant_Info_Here",
    knownAuthorities: [],
    redirectUri: "https://localhost:{port}/redirect",
    postLogoutRedirectUri: "https://localhost:{port}/redirect",
    navigateToLoginRequestUrl: true,
  },
  cache: {
    cacheLocation: "sessionStorage",
    storeAuthStateInCookie: false,
  },
  system: {
    loggerOptions: {
      loggerCallback: (
        level: LogLevel,
        message: string,
        containsPii: boolean
      ): void => {
        if (containsPii) {
          return;
        }
        switch (level) {
          case LogLevel.Error:
            console.error(message);
            return;
          case LogLevel.Info:
            console.info(message);
            return;
          case LogLevel.Verbose:
            console.debug(message);
            return;
          case LogLevel.Warning:
            console.warn(message);
            return;
        }
      },
      piiLoggingEnabled: false,
    },
    windowHashTimeout: 60000,
    iframeHashTimeout: 6000,
    loadFrameTimeout: 0,
  },
};

// Create an instance of PublicClientApplication
const msalInstance = new PublicClientApplication(msalConfig);

// Handle the redirect flows
msalInstance
  .handleRedirectPromise()
  .then((tokenResponse) => {
    // Handle redirect response
  })
  .catch((error) => {
    // Handle redirect error
  });

`handleRedirectPromise`

當應用程式使用重新導向流程時，叫用 [handleRedirectPromise][msal-js-handleredirectpromise]。使用重新導向流程時，應該在每個頁面載入時執行 handleRedirectPromise。

從承諾中可以得到三種結果：

.then 已被叫用且 tokenResponse 為真：應用程式從已成功的重新導向操作返回。
.then 已叫用且 tokenResponse 為 falsy (null)：應用程式不會從重新導向作業傳回。
.catch 正在叫用：應用程式正在從重新導向操作返回，並且發生了錯誤。

初始化 MSAL.js 1.x 應用程式

使用設定物件具現化 UserAgentApplication，以初始化 MSAL 1.x 驗證執行內容。最低要求的設定屬性是您應用程式上的 clientID，其在 Azure 入口網站中應用程式註冊的 [總覽] 頁面上顯示為應用程式 (用戶端) 識別碼。

針對在 MSAL.js 1.2. x 或舊版具有重新導向流程 (loginRedirect 和 acquireTokenRedirect) 的驗證方法，您必須透過 handleRedirectCallback() 方法明確地註冊成功或錯誤的回撥。 MSAL.js 1.2. x 和舊版需要明確的註冊回撥，因為重新導向流程不會像具有快顯體驗的方法一樣傳回 Promise。在 MSAL.js 版本 1.3. x 和更新版本中，回撥註冊是選擇性的。

// Configuration object constructed
const msalConfig = {
  auth: {
    clientId: "Enter_the_Application_Id_Here",
  },
};

// Create UserAgentApplication instance
const msalInstance = new UserAgentApplication(msalConfig);

function authCallback(error, response) {
  // Handle redirect response
}

// Register a redirect callback for Success or Error (when using redirect methods)
// **REQUIRED** in MSAL.js 1.2.x and earlier
// **OPTIONAL** in MSAL.js 1.3.x and later
msalInstance.handleRedirectCallback(authCallback);

單一執行個體和設定

MSAL.js 1.x 和 2.x 都被設計為分別透過 UserAgentApplication 或 PublicClientApplication 的單一實例和配置，來呈現單一驗證執行內容。

不建議多次使用 UserAgentApplication 或 PublicClientApplication，因為這會在瀏覽器中導致快取項目與行為衝突。

後續步驟

GitHub 上的 MSAL.js 2.x 程式碼範例展示如何使用配置物件建立 PublicClientApplication[/javascript/api/@azure/msal-browser/publicclientapplication] 實例

共用方式為