Edit

Migrate iOS applications that use Microsoft Authenticator from ADAL.NET to MSAL.NET

  • Article

You've been using the Azure Active Directory Authentication Library for .NET (ADAL.NET) and the iOS broker. Now it's time to migrate to the Microsoft Authentication Library for .NET (MSAL.NET), which supports the broker on iOS from release 4.3 onward.

Where should you start? This article helps you migrate your Xamarin iOS app from ADAL to MSAL.

Prerequisites

This article assumes that you already have a Xamarin iOS app that's integrated with the iOS broker. If you don't, move directly to MSAL.NET and begin the broker implementation there. For information on how to invoke the iOS broker in MSAL.NET with a new application, see this documentation.

Background

What are brokers?

Brokers are applications provided by Microsoft on Android and iOS. (See the Microsoft Authenticator app on iOS and Android, and the Intune Company Portal app on Android.)

They enable:

Migrate from ADAL to MSAL

Step 1: Enable the broker

Current ADAL code:MSAL counterpart:
In ADAL.NET, broker support was enabled on a per-authentication context basis. It's disabled by default. You had to set a

useBroker flag to true in the PlatformParameters constructor to call the 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-PublicClientApplication basis. It's disabled by default. To enable it, use the

WithBroker() parameter (set to true by default) in order to call the 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 2: Set a UIViewController()

In ADAL.NET, you passed in a UIViewController as part of PlatformParameters. (See the example in Step 1.) In MSAL.NET, to give developers more flexibility, an object window is used, but it's not required in regular iOS usage. To use the broker, set the object window in order to send and receive responses from the broker.

Current ADAL code:MSAL counterpart:
A UIViewController is passed into

PlatformParameters in the iOS-specific platform.

page.BrokerParameters = new PlatformParameters(
          this,
          true,
          PromptBehavior.SelectAccount);
In MSAL.NET, you do two things to set the object window for iOS:
  1. In AppDelegate.cs, set App.RootViewController to a new UIViewController(). This assignment ensures that there's a UIViewController with the call to the broker. If it isn't set correctly, you might 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"
  2. On the AcquireTokenInteractive call, use .WithParentActivityOrWindow(App.RootViewController), and pass in the reference to the object window you'll 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 3: Update AppDelegate to handle the callback

Both ADAL and MSAL call the broker, and the broker in turn calls back to your application through the OpenUrl method of the AppDelegate class. For more information, see this documentation.

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

Step 4: Register a URL scheme

ADAL.NET and MSAL.NET use URLs to invoke the broker and return the broker response back to the app. Register the URL scheme in the Info.plist file for your app as follows:

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 URL scheme becomes part of the redirect URI that's used to uniquely identify the app when it receives the response from the broker.

Step 5: Add the broker identifier to the LSApplicationQueriesSchemes section

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

Current ADAL code:MSAL counterpart:
Uses

msauth

<key>LSApplicationQueriesSchemes</key>
<array>
     <string>msauth</string>
</array>
Uses

msauthv2

<key>LSApplicationQueriesSchemes</key>
<array>
     <string>msauthv2</string>
     <string>msauthv3</string>
</array>

Step 6: Register your redirect URI in the Azure portal

ADAL.NET and MSAL.NET both add an extra requirement on the redirect URI when it targets the broker. Register the redirect URI with your application in the Azure 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 about how to register the redirect URI in the Azure portal, see Step 7: Add a redirect URI to your app registration.

Step 7: Set the Entitlements.plist

Enable keychain access in the Entitlements.plist file:

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

For more information about enabling keychain access, see Enable keychain access.

Next steps

Learn about Xamarin iOS-specific considerations with MSAL.NET.