How to migrate from using Android Broker on ADAL.NET to MSAL.NET

You've been using ADAL.NET and Android broker, and it's finally time to migrate to use the next generation Microsoft authentication library, MSAL.NET, which, as of release 4.9, supports the broker on Android.

Where to start? This document will help you migrate your Xamarin Android app from ADAL to MSAL.

Prerequisites

This document assumes that you already have a Xamarin Android app that is integrated with the Android broker. If you do not, it would be best to move directly to MSAL.NET and begin the broker implementation there. See this documentation for details on invoking the Android broker in MSAL.NET with a new application.

Background

What are brokers?

Brokers are applications, provided by Microsoft, on Android and iOS (Microsoft Authenticator on iOS and Android, InTune Company Portal on Android).

They enable:

• Single-Sign-On,
• Device identification, which is required by some conditional access policies (See Device management)
• Mobile device management which is often required for enterprise scenarios (See Mobile Device Management)
• Application identification verification, also required in some enterprise scenarios (See for instance Intune mobile application management, or MAM)

Migrate from ADAL to MSAL

Step One: Enable the Broker

Current ADAL code:

MSAL counterpart:

In ADAL.NET, broker support was enabled on a per-authentication context basis, it is disabled by default. You had to set a useBroker flag to true in the PlatformParameters constructor in order to call broker: public PlatformParameters( UIViewController callerViewController, bool useBroker) Also, in the platform specific code, in this example, in the page renderer for Android, set the useBroker flag to true: page.BrokerParameters = new PlatformParameters( this, true, PromptBehavior.SelectAccount); Then, include the parameters in the acquire token call: AuthenticationResult result = await AuthContext.AcquireTokenAsync( Resource, ClientId, new Uri(RedirectURI), platformParameters) .ConfigureAwait(false);

In MSAL.NET, broker support is enabled on a per-Public Client Application basis. It is disabled by default. You must use the WithBroker() parameter (set to true by default) in order to call broker: var app = PublicClientApplicationBuilder .Create(ClientId) .WithBroker() .WithReplyUri(redirectUriOnAndroid) .Build(); In the Acquire Token call: result = await app.AcquireTokenInteractive(scopes) .WithParentActivityOrWindow(App.RootViewController) .ExecuteAsync();

Step Two: Set a UIViewController()

In ADAL.NET, you passed in the UIViewController as part of the PlatformParameters (see example in Step One). However, in MSAL.NET, to give the developer more flexibility, an object window is used, but not required in regular Android usage. However, in order to use the broker, you will need to set the object window in order to send and receive responses from broker.

Current ADAL code:

MSAL counterpart:

The UIViewController is passed into the PlatformParamters in the Android specific platform. page.BrokerParameters = new PlatformParameters( this, true, PromptBehavior.SelectAccount);

In MSAL.NET, you will need to do two things to set the object window for Android: In AppDelegate.cs , set the App.RootViewController to a new UIViewController(). This will make sure there is a UIViewController with the call to the broker. If it is not set correctly, you may get this error: "uiviewcontroller_required_for_android_broker":"UIViewController is null, so MSAL.NET cannot invoke the Android broker. See https://aka.ms/Brokered-Authentication-for-Android" On the AcquireTokenInteractive call, use the .WithParentActivityOrWindow(App.RootViewController) and pass in the reference to the object window you will use. For example: In App.cs: public static object RootViewController { get; set; } In AppDelegate.cs: LoadApplication(new App()); App.RootViewController = new UIViewController(); In the Acquire Token call: result = await app.AcquireTokenInteractive(scopes) .WithParentActivityOrWindow(App.RootViewController) .ExecuteAsync();

Step Three: Update AppDelegate to handle the callback

Both ADAL and MSAL will call the broker, and broker will, in turn, call back to your application through the OpenUrl method of the AppDelegate class. More information available here

✔️There are no changes here between ADAL.NET and MSAL.NET

Step Four: Register your RedirectUri in the application portal

ADAL.NET and MSAL.NET use URLs to invoke the broker and return the broker response back to the app. Fortunatly, the URL schemes are the same for ADAL and MSAL so you will not need to make any changes here.

✔️There are no changes here between ADAL.NET and MSAL.NET