使用 MSAL.js 初始化客户端应用程序

项目
03/02/2024

本文介绍如何使用用户代理应用程序的实例初始化适用于 JavaScript 的 Microsoft 身份验证库 (MSAL.js)。

该用户代理应用程序是某种形式的公共客户端应用程序，其中的客户端代码在 Web 浏览器等用户代理中执行。这些客户端不存储机密，因为浏览器上下文可公开访问。

若要详细了解客户端应用程序类型和应用程序配置选项，请参阅 MSAL 中的公共和机密客户端应用。

先决条件

在初始化应用程序之前，首先需要在 Microsoft Entra 管理中心中注册该应用程序，从而在应用程序和 Microsoft 标识平台之间建立信任关系。

注册应用后，你需要位于 Microsoft Entra 管理中心中的以下部分值或所有值。

值	必选	说明
应用程序（客户端）ID	必选	在 Microsoft 标识平台中唯一标识你的应用程序的 GUID。
颁发机构	可选	标识提供者 URL（实例）和应用程序的登录受众。实例和登录受众连接起来后就组成了颁发机构。
目录（租户）ID	可选	如果要仅为组织构建业务线应用程序（通常称为单租户应用程序），请指定目录（租户）ID。
重定向 URI	可选	如果要构建 Web 应用，`redirectUri` 指定标识提供者（Microsoft 标识平台）应在何处返回其已颁发的安全令牌。

初始化 MSAL.js 2.x 应用

通过实例化具有 Configuration 对象的 PublicClientApplication 来初始化 MSAL.js 身份验证上下文。所需的最低配置属性是应用程序的 clientID，在 Microsoft Entra 管理中心中应用注册的“概述”页上显示为“应用程序（客户端）ID”。

下面是一个示例配置对象和 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 为假 (null)：应用程序未从重定向操作返回。
.catch 被调用：应用程序从重定向操作返回，但出现错误。

初始化 MSAL.js 1.x 应用

通过使用配置对象实例化 UserAgentApplication 来初始化 MSAL 1.x 身份验证上下文。所需的最低配置属性是应用程序的 clientID，在 Microsoft Entra 管理中心中应用注册的“概述”页上显示为“应用程序（客户端）ID”。

对于 MSAL.js 1.2.x 或更早版本中具有重定向流（loginRedirect 和 acquireTokenRedirect）的身份验证方法，必须通过 handleRedirectCallback() 方法显式注册回调以成功或出错。 MSAL.js 1.2.x 及更早版本需要显式注册回调，因为重定向流不会像具有弹出项体验的方法那样返回承诺。在 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 代码示例演示了具有 Configuration 对象的 PublicClientApplication 实例化：