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

發行項
06/20/2024

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

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

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

必要條件

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

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

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

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

使用設定物件具現化 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 (英文)。使用重新導向流程時，應該在每個頁面載入時執行 handleRedirectPromise。

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

.then 已叫用且 tokenResponse 為 truthy：應用程式從成功的重新導向作業傳回。
.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 與設定物件的具現化：

共用方式為