MSAL migration guide 0.3.2 1.0.0
There are a number of changes introduced by MSAL 1.0. Including:
- New factory methods
- New sub-types of PublicClientApplication
- Synchronous methods callable from worker threads
- UIBehavior Enum - Renamed to "Prompt"
- Reduction in overloads (replaced by parameters objects to methods)
- Additional Configuration
- New Exception Types
Single account and multiple account public client applications were introduced in MSAL 1.0. This allows you as the developer to tell us whether you app is designed to allow a single account to be in use at a time or multiple accounts at a time.
Users migrating from 0.3 can use the default type which is MultipleAccountPublicClientApplication. The interface for this sub-type is the same (currently) as PublicClientApplication in MSAL 0.3.
See: https://docs.microsoft.com/en-us/azure/active-directory/develop/single-multi-account
MSAL 1.0 adds support for synchronous methods that can be called from worker threads. For an example you can refer to getAccount: Sync Method
In general whatever used to be returned via a callback is now the return value and exceptions are thrown rather than returned from onError callback.
The code will throw an exception if you attempt to invoke these methods on the UI/Main thread.
The UIBehavior enum was renamed to "prompt" to more accurately associated the parameter with its equivalent in the OpenId Connect 1.0 spec. The value Prompt.WhenRequired was added to support not sending a prompt parameter to the authorization endpoint at all. When this value is used the service will use what it believes is the current account to complete the request. If a prompt is required (consent, policy, etc...) then it will be shown. Otherwise the request may automatically complete.
Parameter objects with builders have been added to simplify the use of acquireToken, acquireTokenSilent. These methods allow many parameters and we've chosen to require the usage of parameter objects rather than simply continuing adding additional overloads to existing methods.
A complete reference for the MSAL configuration json is found here: MSAL Android Configuration
MSAL 1.0 introduced a few new important exceptions including: MsalDeclinedScopeException - Returned when you requested a scope but did not receive it for the current account. For example: This can happen when requesting an "organizational" scope from Microsoft Graph when using a Microsoft account (live id).
For a complete list of MsalException please refer to: MSAL Android Exceptions
A new type of MsalClientException was also introduced in MSAL 1.0 to provide an indication when communication with the authentication broker on the device is currently failing. MsalClientException.BROKER_BIND_FAILURE. More information on this specific error code can be found here.