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

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

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

Prerequisites

This document assumes that you already have a Xamarin iOS app that is integrated with the iOS 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 iOS 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)
• 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 iOS, 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(redirectUriOnIos) .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 iOS 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 iOS 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 iOS: 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_ios_broker":"UIViewController is null, so MSAL.NET cannot invoke the iOS broker. See https://aka.ms/msal-net-ios-broker" 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 a URL Scheme

ADAL.NET and MSAL.NET use URLs to invoke the broker and return the broker response back to the app. The URL scheme needs to be registered in the Info.plist file for your app.

Current ADAL code:

MSAL counterpart:

The URL Scheme is unique to your app.

The CFBundleURLSchemes name must include msauth. as a prefix, followed by your CFBundleURLName For example: $"msauth.(BundleId") <key>CFBundleURLTypes</key> <array> <dict> <key>CFBundleTypeRole</key> <string>Editor</string> <key>CFBundleURLName</key> <string>com.yourcompany.xforms</string> <key>CFBundleURLSchemes</key> <array> <string>msauth.com.yourcompany.xforms</string> </array> </dict> </array> Note: This will become part of the RedirectUri used for uniquely identifying the app when receiving the response from broker

Step Five: LSApplicationQueriesSchemes

ADAL.NET and MSAL.NET both use -canOpenURL: to check if the broker is installed on the device. You need to add the correct identifier for the iOS broker to the LSApplicationQueriesSchemes section of the info.plist file.

Current ADAL code:	MSAL counterpart:
Uses msauth <key>LSApplicationQueriesSchemes</key> <array> <string>msauth</string> </array>	Uses msauthv2 <key>LSApplicationQueriesSchemes</key> <array> <string>msauthv2</string> </array>

Step Six: Register you RedirectUri in the portal

ADAL.NET and MSAL.NET both add an extra requirement on the redirectUri when targeting broker, and must be registered with your application in the portal.

Current ADAL code:	MSAL counterpart:
"<app-scheme>://<your.bundle.id>" example: mytestiosapp://com.mycompany.myapp	$"msauth.{BundleId}://auth" example: public static string redirectUriOnIos = "msauth.com.yourcompany.XForms://auth";

For more information on registering the redirectUri in the portal, see this page for more details.

Step Seven: Set the Entitlements.plist

Make sure the Entitlements.plist are set to enable keychain access. More information on enabling keychain access.

 <key>keychain-access-groups</key>
    <array>
      <string>$(AppIdentifierPrefix)com.microsoft.adalcache</string>
    </array>