Migrating from MSAL.Android 0.1.n to 0.2.0

MSAL.Android 0.2.0

MSAL 0.2.0 culminates the goals of the Microsoft identity platform and providing a seamless upgrade path for all existing apps on ADAL.

We're excited to announce several improvements and new features:

✅ Seamless-migration from ADAL 1.15.*+ for /common users. All users migration coming in a future iteration.

✅ Support for all major browsers on Android

✅ In-app WebViews for highly custom experiences

✅ Dozens of under-the-covers changes

This article focuses the steps you'll need to take to adopt the MSAL 0.2.0 and any major changes you and your users may experience. For a complete list of changes, see our changelog

Summary of changes

For MSAL 0.2.0, we focused on building an easy upgrade experience from ADAL, our highest requested and most important features, and improving the SDK internals. This amounted to a few breaking changes. We'll walk through each of them and what your app needs to do to migrate.

• User -> Account
• Code Structure & Exceptions
• End-user SSO state

User -> Account

MSAL can be used to access several different account types including Azure AD, Microsoft accounts, and Azure AD B2C (Social & Local) accounts. To more closely align to the identity your app is accessing, we've changed all uses of User to Account. This more accurately represents the entity that's being authorized to your app. A single user may have multiple accounts, and the library makes this easy through Account.

This change manifests in some SDK changes, specifically:

• Users has been deleted and replaced with IAccount

• acquireToken and acquireToken silent now accept IAccount.

• PublicClientApplication method getUsers() has been deleted and replaced with getAccount().

• PublicClientApplication method remove(Users) has been deleted and replaced with removeAccount(IAccount).

• getName() has been replaced with getUsername().

Code Structure & Exceptions

MSAL 0.2.n has cleaned up the internal code structure. As a result, there are a few small changes in your app.

• Apps will need to add the following import:

  import com.microsoft.identity.client.exception.*;

• MSALClientException is no longer generated from acquireTokenSilent, acquireToken, removeAccount, or getAccount calls. All errors now occur at runtime and are generated in the error callback.

End-user SSO state

When migrating to 0.2.0 from previous versions of MSAL, apps may see some users being asked to Sign in again. There was a change in the underlying token cache format that will require all users to get new tokens. Some of your users may have a valid cookie inside their web browser, and will see a select account prompt while others may need to enter their password again.

Additionally, we've introduced support for more browsers. Users that signed into Chrome or Chrome custom tabs may be forced to sign in again to the new browser MSAL chooses to launch. We base this decision off what the user has indicated as their default browser. If the user has already signed into that browsers, then they will see a select account screen without needing to enter their password.