MSAL JS 与 ADAL JS 的差异Differences between MSAL JS and ADAL JS

适用于 JavaScript 的 Microsoft 身份验证库 (MSAL.js) 与适用于 JavaScript 的 Azure AD 身份验证库 (ADAL.js) 用于对 Azure AD 实体进行身份验证,以及从 Azure AD 请求令牌。Both Microsoft Authentication Library for JavaScript (MSAL.js) and Azure AD Authentication Library for JavaScript (ADAL.js) are used to authenticate Azure AD entities and request tokens from Azure AD. 截止目前,大多数开发人员都是通过 ADAL 来请求令牌,使用面向开发人员的 Azure AD (v1.0) 来对 Azure AD 标识(工作和学校帐户)进行身份验证。Up until now, most developers have worked with Azure AD for developers (v1.0) to authenticate Azure AD identities (work and school accounts) by requesting tokens using ADAL. 现在,使用 MSAL.js 可以通过 Microsoft 标识平台 (v2.0) 对更广泛的 Microsoft 标识(Azure AD 标识以及通过 Azure AD B2C 使用的社交和本地帐户)进行身份验证。Now, using MSAL.js, you can authenticate a broader set of Microsoft identities (Azure AD identities and social and local accounts through Azure AD B2C) through Microsoft identity platform (v2.0).

本文介绍如何在适用于 JavaScript 的 Microsoft 身份验证库 (MSAL.js) 与适用于 JavaScript 的 Azure AD 身份验证库 (ADAL.js) 之间进行选择,并对这两个库做了比较。This article describes how to choose between the Microsoft Authentication Library for JavaScript (MSAL.js) and Azure AD Authentication Library for JavaScript (ADAL.js) and compares the two libraries.

在 ADAL.js 与 MSAL.js 之间做出选择Choosing between ADAL.js and MSAL.js

在大多数情况下都可以使用 Microsoft 标识平台和 MSAL.js,这是最新一代的 Microsoft 身份验证库。In most cases you want to use the Microsoft identity platform and MSAL.js, which is the latest generation of Microsoft authentication libraries. 使用 MSAL.js 可以获取通过 Azure AD(工作和学校帐户)或 Azure AD B2C 登录到应用程序的用户的令牌。Using MSAL.js, you acquire tokens for users signing in to your application with Azure AD (work and school accounts) or Azure AD B2C.

如果你已熟悉 v1.0 终结点(和 ADAL.js),请阅读 v2.0 终结点有何不同?If you are already familiar with the v1.0 endpoint (and ADAL.js), you might want to read What's different about the v2.0 endpoint?.

但是,如果应用程序需要使用早期版本的 Active Directory 联合身份验证服务 (ADFS) 将用户登录,则你仍然需要使用 ADAL.js。However, you still need to use ADAL.js if your application needs to sign in users with earlier versions of Active Directory Federation Services (ADFS).

使用 MSAL.js 进行身份验证的重要差异Key differences in authentication with MSAL.js

核心 APICore API

  • ADAL.js 使用 AuthenticationContext 来表示应用程序实例通过颁发机构 URL 来与授权服务器或标识提供者建立的连接。ADAL.js uses AuthenticationContext as the representation of an instance of your application's connection to the authorization server or identity provider through an authority URL. 相比之下,MSAL.js API 是围绕用户代理客户端应用程序(某种形式的公共客户端应用程序,其中的客户端代码在 Web 浏览器等用户代理中执行)设计的。On the contrary, MSAL.js API is designed around user agent client application(a form of public client application in which the client code is executed in a user-agent such as a web browser). 它提供 UserAgentApplication 类来表示应用程序实例在授权服务器上的身份验证上下文。It provides the UserAgentApplication class to represent an instance of the application's authentication context with the authorization server. 有关更多详细信息,请参阅使用 MSAL.js 初始化For more details, see Initialize using MSAL.js.

  • 在 ADAL.js 中,用于获取令牌的方法与 AuthenticationContext 中设置的单个颁发机构相关联。In ADAL.js, the methods to acquire tokens are associated with a single authority set in the AuthenticationContext. 在 MSAL.js 中,获取令牌请求可以采用其他颁发机构值,而不采用 UserAgentApplication 中设置的值。In MSAL.js, the acquire token requests can take different authority values than what is set in the UserAgentApplication. 这样,MSAL.js 便可以单独获取和缓存同一应用程序中多个租户和用户帐户的令牌。This allows MSAL.js to acquire and cache tokens separately for multiple tenants and user accounts in the same application.

  • 在不提示用户的情况下以静默方式获取和续订令牌的方法在 ADAL.js 中名为 acquireTokenThe method to acquire and renew tokens silently without prompting users is named acquireToken in ADAL.js. 在 MSAL.js 中,此方法名为 acquireTokenSilent,它更好地描述了其功能。In MSAL.js, this method is named acquireTokenSilent to be more descriptive of this functionality.

颁发机构值 commonAuthority value common

在 v1.0 中,使用 https://login.partner.microsoftonline.cn/common 颁发机构可让用户使用任何 Azure AD 帐户(适用于任何组织)登录。In v1.0, using the https://login.partner.microsoftonline.cn/common authority will allow users to sign in with any Azure AD account (for any organization).

在 v2.0 中,使用 https://login.partner.microsoftonline.cn/common 颁发机构可让用户使用任何 Azure AD 组织帐户登录。In v2.0, using the https://login.partner.microsoftonline.cn/common authority, will allow users to sign in with any Azure AD organization account. 若要限制为只能登录到 Azure AD 帐户(与 ADAL.js 中的行为类似),需要使用 https://login.partner.microsoftonline.cn/organizationsTo restrict the sign in to only Azure AD accounts (same behavior as with ADAL.js), you need to use https://login.partner.microsoftonline.cn/organizations. 有关详细信息,请参阅使用 MSAL.js 初始化中的 authority 配置选项。For details, see the authority config option in Initialize using MSAL.js.

用于获取令牌的范围Scopes for acquiring tokens

  • 身份验证请求中用于获取令牌的范围而不是资源参数Scope instead of resource parameter in authentication requests to acquire tokens

    v2.0 协议在请求中使用范围而不是资源。v2.0 protocol uses scopes instead of resource in the requests. 换而言之,当应用程序需要使用某个资源(例如 MS Graph)的权限请求令牌时,传递给库方法的值的差异如下:In other words, when your application needs to request tokens with permissions for a resource such as MS Graph, the difference in values passed to the library methods is as follows:

    v1.0:resource = https://microsoftgraph.chinacloudapi.cnv1.0: resource = https://microsoftgraph.chinacloudapi.cn

    v2.0:scope = https://microsoftgraph.chinacloudapi.cn/User.Readv2.0: scope = https://microsoftgraph.chinacloudapi.cn/User.Read

    可以使用 API 的 URI 按“应用 ID URI/范围”格式请求任何资源 API 的范围。例如:https://mytenant.partner.onmschina.cn/myapi/api.readYou can request scopes for any resource API using the URI of the API in this format: appidURI/scope For example: https://mytenant.partner.onmschina.cn/myapi/api.read

    仅对于 MS Graph API,范围值 user.read 映射到 https://microsoftgraph.chinacloudapi.cn/User.Read,并且可互换使用。Only for the MS Graph API, a scope value user.read maps to https://microsoftgraph.chinacloudapi.cn/User.Read and can be used interchangeably.

    var request = {
        scopes = ["https://microsoftgraph.chinacloudapi.cn/User.Read"];
    };
    
    acquireTokenPopup(request);   
    
  • 增量许可的动态范围。Dynamic scopes for incremental consent.

    使用 v1.0 生成应用程序时,需要注册应用程序所需的完整权限集(静态范围),让用户在登录时许可这些权限。When building applications using v1.0, you needed to register the full set of permissions(static scopes) required by the application for the user to consent to at the time of login. 在 v2.0 中,可以随时按需使用范围参数来请求权限。In v2.0, you can use the scope parameter to request the permissions at the time you want them. 这些范围称为动态范围。These are called dynamic scopes. 这样,用户便可以提供对范围的增量许可。This allows the user to provide incremental consent to scopes. 因此,如果你最初只是希望用户登录到你的应用程序,而不需要任何类型的访问权限,则可以这样做。So if at the beginning you just want the user to sign in to your application and you don’t need any kind of access, you can do so. 如果后来需要读取用户的日历,则可以在 acquireToken 方法中请求日历范围,并获取用户的许可。If later you need the ability to read the calendar of the user, you can then request the calendar scope in the acquireToken methods and get the user's consent. 例如:For example:

    var request = {
        scopes = ["https://microsoftgraph.chinacloudapi.cn/User.Read", "https://microsoftgraph.chinacloudapi.cn/Calendar.Read"];
    };
    
    acquireTokenPopup(request);   
    
  • V1.0 API 的范围Scopes for V1.0 APIs

    使用 MSAL.js 获取 V1.0 API 的令牌时,可以通过将 .default 作为范围追加到 API 的应用 ID URI,来请求该 API 中注册的所有静态范围。When getting tokens for V1.0 APIs using MSAL.js, you can request all the static scopes registered on the API by appending .default to the App ID URI of the API as scope. 例如:For example:

    var request = {
        scopes = [ appidURI + "/.default"];
    };
    
    acquireTokenPopup(request);
    

后续步骤Next steps

有关详细信息,请阅读 v1.0 与 v2.0 的比较For more information, refer to v1.0 and v2.0 comparison.