您现在访问的是微软AZURE全球版技术文档网站,若需要访问由世纪互联运营的MICROSOFT AZURE中国区技术文档网站,请访问 https://docs.azure.cn.

适用于 Java 的 ADAL 到 MSAL 迁移指南ADAL to MSAL migration guide for Java

本文重点介绍需要做出哪些更改,才能迁移使用 Azure Active Directory 身份验证库 (ADAL) 的应用,使之使用 Microsoft 身份验证库 (MSAL)。This article highlights changes you need to make to migrate an app that uses the Azure Active Directory Authentication Library (ADAL) to use the Microsoft Authentication Library (MSAL).

适用于 java 的 Microsoft 身份验证库 (MSAL4J) 和 Java 的 Azure AD 身份验证库 (ADAL4J) 用于对 Azure AD 的实体进行身份验证并请求 Azure AD 中的令牌。Both the Microsoft Authentication Library for Java (MSAL4J) and Azure AD Authentication Library for Java (ADAL4J) are used to authenticate Azure AD entities and request tokens from Azure AD. 截止目前,大多数开发人员都是通过 Azure AD 身份验证库 (ADAL) 来请求令牌,使用面向开发人员的 Azure AD 平台 (v1.0) 来对 Azure AD 标识(工作和学校帐户)进行身份验证。Until now, most developers have worked with Azure AD for developers platform (v1.0) to authenticate Azure AD identities (work and school accounts) by requesting tokens using Azure AD Authentication Library (ADAL).

MSAL 提供以下优势:MSAL offers the following benefits:

  • 由于它使用较新的 Microsoft 标识平台,因此你可以通过 Azure AD Business to 消费品 (B2C) ,对一组更广泛的 Microsoft 标识进行身份验证,例如 Azure AD 标识、Microsoft 帐户和社交和本地帐户。Because it uses the newer Microsoft identity platform, you can authenticate a broader set of Microsoft identities such as Azure AD identities, Microsoft accounts, and social and local accounts through Azure AD Business to Consumer (B2C).
  • 用户将获得最佳单一登录体验。Your users will get the best single-sign-on experience.
  • 应用程序可以启用增量许可,更轻松地为条件访问提供支持。Your application can enable incremental consent, and supporting conditional access is easier.

MSAL for Java 是我们建议用于 Microsoft 标识平台的身份验证库。MSAL for Java is the auth library we recommend you use with the Microsoft identity platform. 我们不会对 ADAL4J 实现任何新的功能。No new features will be implemented on ADAL4J. 今后我们的所有努力都重在改进 MSAL。All efforts going forward are focused on improving MSAL.

差异Differences

如果你使用的是 Azure AD for 开发人员 (v1.0) endpoint (和 ADAL4J) ,你可能需要阅读 Microsoft 标识平台的不同之处?If you have been working with the Azure AD for developers (v1.0) endpoint (and ADAL4J), you might want to read What's different about the Microsoft identity platform?.

范围不是资源Scopes not resources

ADAL4J 获取资源的令牌,而 MSAL for Java 则是获取范围的令牌。ADAL4J acquires tokens for resources whereas MSAL for Java acquires tokens for scopes. 许多 MSAL for Java 类需要 scopes 参数。A number of MSAL for Java classes require a scopes parameter. 此参数是一个字符串列表,这些字符串声明所需的权限和请求的资源。This parameter is a list of strings that declare the desired permissions and resources that are requested. 请参阅 Microsoft Graph 的范围查看示例范围。See Microsoft Graph's scopes to see example scopes.

可以将 /.default 范围后缀添加到资源,帮助将应用从 ADAL 迁移到 MSAL。You can add the /.default scope suffix to the resource to help migrate your apps from the ADAL to MSAL. 例如,对于 https://graph.microsoft.com 的资源值,等效的作用域值为 https://graph.microsoft.com/.defaultFor example, for the resource value of https://graph.microsoft.com, the equivalent scope value is https://graph.microsoft.com/.default. 如果资源未采用 URL 形式,但资源 ID 采用 XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX 形式,则仍可以使用作用域值 XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX/.defaultIf the resource is not in the URL form, but a resource ID of the form XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX, you can still use the scope value as XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX/.default.

有关不同类型作用域的更多详细信息,请参阅 Microsoft 标识平台中的权限和许可以及接受 v1.0 令牌的 Web API 的作用域两篇文章。For more details about the different types of scopes, refer Permissions and consent in the Microsoft identity platform and the Scopes for a Web API accepting v1.0 tokens articles.

核心类Core classes

在 ADAL4J 中,AuthenticationContext 类代表通过颁发机构与安全令牌服务 (STS) 或授权服务器建立的连接。In ADAL4J, the AuthenticationContext class represents your connection to the Security Token Service (STS), or authorization server, through an Authority. 但是,MSAL for Java 是围绕客户端应用程序设计的。However, MSAL for Java is designed around client applications. 它提供两个不同的类(PublicClientApplicationConfidentialClientApplication)来代表客户端应用程序。It provides two separate classes: PublicClientApplication and ConfidentialClientApplication to represent client applications. 后者 (ConfidentialClientApplication) 代表的应用程序旨在安全维护机密,例如守护程序应用的应用程序标识符。The latter, ConfidentialClientApplication, represents an application that is designed to securely maintain a secret such as an application identifier for a daemon app.

下表显示了 ADAL4J 函数到新 MSAL for Java 函数的映射:The following table shows how ADAL4J functions map to the new MSAL for Java functions:

ADAL4J 方法ADAL4J method MSAL4J 方法MSAL4J method
acquireToken(String resource, ClientCredential credential, AuthenticationCallback callback)acquireToken(String resource, ClientCredential credential, AuthenticationCallback callback) acquireToken(ClientCredentialParameters)acquireToken(ClientCredentialParameters)
acquireToken(String resource, ClientAssertion assertion, AuthenticationCallback callback)acquireToken(String resource, ClientAssertion assertion, AuthenticationCallback callback) acquireToken(ClientCredentialParameters)acquireToken(ClientCredentialParameters)
acquireToken(String resource, AsymmetricKeyCredential credential, AuthenticationCallback callback)acquireToken(String resource, AsymmetricKeyCredential credential, AuthenticationCallback callback) acquireToken(ClientCredentialParameters)acquireToken(ClientCredentialParameters)
acquireToken(String resource, String clientId, String username, String password, AuthenticationCallback callback)acquireToken(String resource, String clientId, String username, String password, AuthenticationCallback callback) acquireToken(UsernamePasswordParameters)acquireToken(UsernamePasswordParameters)
acquireToken(String resource, String clientId, String username, String password=null, AuthenticationCallback callback)acquireToken(String resource, String clientId, String username, String password=null, AuthenticationCallback callback) acquireToken(IntegratedWindowsAuthenticationParameters)acquireToken(IntegratedWindowsAuthenticationParameters)
acquireToken(String resource, UserAssertion userAssertion, ClientCredential credential, AuthenticationCallback callback)acquireToken(String resource, UserAssertion userAssertion, ClientCredential credential, AuthenticationCallback callback) acquireToken(OnBehalfOfParameters)acquireToken(OnBehalfOfParameters)
acquireTokenByAuthorizationCode()acquireTokenByAuthorizationCode() acquireToken(AuthorizationCodeParameters)acquireToken(AuthorizationCodeParameters)
acquireDeviceCode() and acquireTokenByDeviceCode()acquireDeviceCode() and acquireTokenByDeviceCode() acquireToken(DeviceCodeParameters)acquireToken(DeviceCodeParameters)
acquireTokenByRefreshToken()acquireTokenByRefreshToken() acquireTokenSilently(SilentParameters)acquireTokenSilently(SilentParameters)

IAccount 而不是 IUserIAccount instead of IUser

ADAL4J 操控用户。ADAL4J manipulated users. 尽管用户代表单个个人或软件代理,但用户可以在 Microsoft 标识系统中有一个或多个帐户。Although a user represents a single human or software agent, it can have one or more accounts in the Microsoft identity system. 例如,用户可能有多个 Azure AD、Azure AD B2C 或 Microsoft 个人帐户。For example, a user may have several Azure AD, Azure AD B2C, or Microsoft personal accounts.

MSAL for Java 通过 IAccount 接口定义帐户的概念。MSAL for Java defines the concept of Account via the IAccount interface. 这是 ADAL4J 中的一项中断性变更,但这项变更是积极性的,因为它捕获到这样一个事实:同一用户可以有多个帐户,甚至是不同 Azure AD 目录中的帐户。This is a breaking change from ADAL4J, but it is a good one because it captures the fact that the same user can have several accounts, and perhaps even in different Azure AD directories. 由于系统会提供主帐户信息,MSAL for Java 可以在来宾方案中提供更有用的信息。MSAL for Java provides better information in guest scenarios because home account information is provided.

缓存持久性Cache persistence

ADAL4J 不支持令牌缓存。ADAL4J did not have support for token cache. MSAL for Java 添加了令牌缓存,在可能的情况下,它会自动刷新已过期的令牌,并防止不必要地提示用户提供凭据,以此简化令牌生存期的管理。MSAL for Java adds a token cache to simplify managing token lifetimes by automatically refreshing expired tokens when possible and preventing unnecessary prompts for the user to provide credentials when possible.

通用颁发机构Common Authority

在 v1.0 中,如果你使用 https://login.microsoftonline.com/common 颁发机构,则用户可以使用任何 Azure Active Directory (AAD) 帐户(适用于任何组织)登录。In v1.0, if you use the https://login.microsoftonline.com/common authority, users can sign in with any Azure Active Directory (AAD) account (for any organization).

如果你使用的是 v2.0 https://login.microsoftonline.com/common 中的权限,则用户可以使用任何 AAD 组织,甚至 Microsoft 个人帐户 (MSA) 登录。If you use the https://login.microsoftonline.com/common authority in v2.0, users can sign in with any AAD organization, or even a Microsoft personal account (MSA). 在适用于 Java 的 MSAL 中,如果要将登录限制为任何 AAD 帐户,请使用 https://login.microsoftonline.com/organizations 与 ADAL4J) 相同的行为 (。In MSAL for Java, if you want to restrict login to any AAD account, use the https://login.microsoftonline.com/organizations authority (which is the same behavior as with ADAL4J). 若要指定颁发机构,请在创建 PublicClientApplication 类时,在 PublicClientApplication.Builder 方法中设置 authority 参数。To specify an authority, set the authority parameter in the PublicClientApplication.Builder method when you create your PublicClientApplication class.

v1.0 和 v2.0 令牌v1.0 and v2.0 tokens

v1.0 终结点(由 ADAL 使用)只发出 v1.0 令牌。The v1.0 endpoint (used by ADAL) only emits v1.0 tokens.

v2.0 终结点(由 MSAL 使用)可以发出 v1.0 和 v2.0 令牌。The v2.0 endpoint (used by MSAL) can emit v1.0 and v2.0 tokens. 开发人员可以使用 Web API 应用程序清单的属性来选择接受的令牌版本。A property of the application manifest of the web API enables developers to choose which version of token is accepted. 请参阅应用程序清单参考文档中的 accessTokenAcceptedVersionSee accessTokenAcceptedVersion in the application manifest reference documentation.

有关 v1.0 和 v2.0 令牌的详细信息,请参阅 Azure Active Directory 访问令牌For more information about v1.0 and v2.0 tokens, see Azure Active Directory access tokens.

ADAL 到 MSAL 的迁移ADAL to MSAL migration

在 ADAL4J 中会公开刷新令牌 -- 允许开发人员缓存这些令牌。In ADAL4J, the refresh tokens were exposed--which allowed developers to cache them. 然后,开发人员可使用 AcquireTokenByRefreshToken() 来实现各种解决方案,例如,实现长时间运行的服务,以便在用户不再保持连接时,代表用户刷新仪表板。They would then use AcquireTokenByRefreshToken() to enable solutions such as implementing long-running services that refresh dashboards on behalf of the user when the user is no longer connected.

出于安全原因,MSAL for Java 不公开刷新令牌。MSAL for Java does not expose refresh tokens for security reasons. 而是由 MSAL 代你处理令牌刷新。Instead, MSAL handles refreshing tokens for you.

使用 MSAL for Java 提供的 acquireToken(RefreshTokenParameters) API,可将通过 ADAL4j 获取的刷新令牌迁移到 ClientApplication 中。MSAL for Java has an API that allows you to migrate refresh tokens you acquired with ADAL4j into the ClientApplication: acquireToken(RefreshTokenParameters). 使用此方法可以结合所需的任何范围(资源)提供以前用过的刷新令牌。With this method, you can provide the previously used refresh token along with any scopes (resources) you desire. 该刷新令牌将交换一个新令牌,并缓存供应用程序使用。The refresh token will be exchanged for a new one and cached for use by your application.

以下代码片段演示了机密客户端应用程序中的一些迁移代码:The following code snippet shows some migration code in a confidential client application:

String rt = GetCachedRefreshTokenForSignedInUser(); // Get refresh token from where you have them stored
Set<String> scopes = Collections.singleton("SCOPE_FOR_REFRESH_TOKEN");

RefreshTokenParameters parameters = RefreshTokenParameters.builder(scopes, rt).build();

PublicClientApplication app = PublicClientApplication.builder(CLIENT_ID) // ClientId for your application
                .authority(AUTHORITY)  //plug in your authority
                .build();

IAuthenticationResult result = app.acquireToken(parameters);

IAuthenticationResult 返回访问令牌和 ID 令牌,新的刷新令牌将存储在缓存中。The IAuthenticationResult returns an access token and ID token, while your new refresh token is stored in the cache. 应用程序现在还包含一个 IAccount:The application will also now contain an IAccount:

Set<IAccount> accounts =  app.getAccounts().join();

若要使用现已进入缓存中的令牌,请调用:To use the tokens that are now in the cache, call:

SilentParameters parameters = SilentParameters.builder(scope, accounts.iterator().next()).build();
IAuthenticationResult result = app.acquireToken(parameters);