Migrate iOS applications that use Microsoft Authenticator from ADAL.NET to MSAL.NET
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.
Note
MSAL.NET versions 4.61.0 and above do not provide support for Universal Windows Platform (UWP), Xamarin Android, and Xamarin iOS. We recommend you migrate your Xamarin applications to modern frameworks like MAUI. Read more about the deprecation in Announcing the Upcoming Deprecation of MSAL.NET for Xamarin and UWP.
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:
- Single sign-on.
- Device identification, which is required by some Conditional Access policies. For more information, see Device management.
- Application identification verification, which is also required in some enterprise scenarios. For more information, see Intune mobile application management (MAM).
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
Also, in the platform-specific code, in this example, in the page renderer for iOS, set the
Then, include the parameters in the acquire token call:
|
In MSAL.NET, broker support is enabled on a per-PublicClientApplication basis. It's disabled by default. To enable it, use the
In the acquire token call:
|
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
|
In MSAL.NET, you do two things to set the object window for iOS:
For example: In
In
In the acquire token call:
|
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
as a prefix, followed by your
For example:
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
|
Uses
|
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: |
Example:
|
Example:
|
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.
Feedback
https://aka.ms/ContentUserFeedback.
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see:Submit and view feedback for