使用 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 在设计上分别采用 UserAgentApplication
或 PublicClientApplication
的单个实例和配置,用于表示单个身份验证上下文。
不建议使用 UserAgentApplication
或 PublicClientApplication
的多个实例,因为它们可能会导致浏览器中的缓存项和行为发生冲突。
后续步骤
GitHub 上的 MSAL.js 2.x 代码示例演示了具有 Configuration 对象的 PublicClientApplication 实例化: