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

本文介绍如何使用用户代理应用程序的实例初始化适用于 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.partner.microsoftonline.cn/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 在设计上分别采用 UserAgentApplicationPublicClientApplication 的单个实例和配置,用于表示单个身份验证上下文。

不建议使用 UserAgentApplicationPublicClientApplication 的多个实例,因为它们可能会导致浏览器中的缓存项和行为发生冲突。

后续步骤

GitHub 上的 MSAL.js 2.x 代码示例演示了具有 Configuration 对象的 PublicClientApplication 实例化: