Configure a mobile app that calls web APIs

Article
10/23/2023

After you create your application, you'll learn how to configure the code by using the app registration parameters. Mobile applications present some complexities related to fitting into their creation framework.

Microsoft libraries supporting mobile apps

The following Microsoft libraries support mobile apps:

Platform	Project on GitHub	Package	Getting started	Generally available (GA) or Public preview¹
Android (Java)	MSAL Android	MSAL	Quickstart	GA
Android (Kotlin)	MSAL Android	MSAL	—	GA
iOS (Swift/Obj-C)	MSAL for iOS and macOS	MSAL	Tutorial	GA
Xamarin (.NET)	MSAL.NET	Microsoft.Identity.Client	—	GA

¹ Universal License Terms for Online Services apply to libraries in Public preview.

Instantiate the application

Android

Mobile applications use the PublicClientApplication class. Here's how to instantiate it:

PublicClientApplication sampleApp = new PublicClientApplication(
                    this.getApplicationContext(),
                    R.raw.auth_config);

iOS

Mobile applications on iOS need to instantiate the MSALPublicClientApplication class. To instantiate the class, use the following code.

NSError *msalError = nil;

MSALPublicClientApplicationConfig *config = [[MSALPublicClientApplicationConfig alloc] initWithClientId:@"<your-client-id-here>"];
MSALPublicClientApplication *application = [[MSALPublicClientApplication alloc] initWithConfiguration:config error:&msalError];

let config = MSALPublicClientApplicationConfig(clientId: "<your-client-id-here>")
if let application = try? MSALPublicClientApplication(configuration: config){ /* Use application */}

Additional MSALPublicClientApplicationConfig properties can override the default authority, specify a redirect URI, or change the behavior of MSAL token caching.

Xamarin or UWP

This section explains how to instantiate the application for Xamarin.iOS, Xamarin.Android, and UWP apps.

Instantiate the application

In Xamarin or UWP, the simplest way to instantiate the application is by using the following code. In this code, ClientId is the GUID of your registered app.

var app = PublicClientApplicationBuilder.Create(clientId)
                                        .Build();

Additional With<Parameter> methods set the UI parent, override the default authority, specify a client name and version for telemetry, specify a redirect URI, and specify the HTTP factory to use. The HTTP factory might be used, for instance, to handle proxies and to specify telemetry and logging.

The following sections provide more information about instantiating the application.

Specify the parent UI, window, or activity

On Android, pass the parent activity before you do the interactive authentication. On iOS, when you use a broker, pass-in ViewController. In the same way on UWP, you might want to pass-in the parent window. You pass it in when you acquire the token. But when you're creating the app, you can also specify a callback as a delegate that returns UIParent.

IPublicClientApplication application = PublicClientApplicationBuilder.Create(clientId)
  .ParentActivityOrWindowFunc(() => parentUi)
  .Build();

On Android, we recommend that you use CurrentActivityPlugin. The resulting PublicClientApplication builder code looks like this example:

// Requires MSAL.NET 4.2 or above
var pca = PublicClientApplicationBuilder
  .Create("<your-client-id-here>")
  .WithParentActivityOrWindow(() => CrossCurrentActivity.Current)
  .Build();

Find more app-building parameters

For a list of all methods that are available on PublicClientApplicationBuilder, see the Methods list.

For a description of all options that are exposed in PublicClientApplicationOptions, see the reference documentation.

Tasks for Xamarin iOS

If you use MSAL.NET on Xamarin iOS, do the following tasks.

For more information, see Xamarin iOS considerations.

Tasks for MSAL for iOS and macOS

These tasks are necessary when you use MSAL for iOS and macOS:

Tasks for Xamarin.Android

If you use Xamarin.Android, do the following tasks:

For more information, see Xamarin.Android considerations.

For considerations about the browsers on Android, see Xamarin.Android-specific considerations with MSAL.NET.

Tasks for UWP

On UWP, you can use corporate networks. The following sections explain the tasks that you should complete in the corporate scenario.

For more information, see UWP-specific considerations with MSAL.NET.

Configure the application to use the broker

On Android and iOS, brokers enable:

Single sign-on (SSO): You can use SSO for devices that are registered with Microsoft Entra ID. When you use SSO, your users don't need to sign in to each application.
Device identification: This setting enables conditional-access policies that are related to Microsoft Entra devices. The authentication process uses the device certificate that was created when the device was joined to the workplace.
Application identification verification: When an application calls the broker, it passes its redirect URL. Then the broker verifies it.

Enable the broker on Xamarin

To enable the broker on Xamarin, use the WithBroker() parameter when you call the PublicClientApplicationBuilder.CreateApplication method. By default, .WithBroker() is set to true.

To enable brokered authentication for Xamarin.iOS, follow the steps in the Xamarin.iOS section in this article.

Enable the broker for MSAL for Android

For information about enabling a broker on Android, see Brokered authentication on Android.

Enable the broker for MSAL for iOS and macOS

Brokered authentication is enabled by default for Microsoft Entra scenarios in MSAL for iOS and macOS.

The following sections provide instructions to configure your application for brokered authentication support for either MSAL for Xamarin.iOS or MSAL for iOS and macOS. In the two sets of instructions, some of the steps differ.

Enable brokered authentication for Xamarin iOS

Follow the steps in this section to enable your Xamarin.iOS app to talk with the Microsoft Authenticator app.

Step 1: Enable broker support

Broker support is disabled by default. You enable it for an individual PublicClientApplication class. Use the WithBroker() parameter when you create the PublicClientApplication class through PublicClientApplicationBuilder. The WithBroker() parameter is set to true by default.

var app = PublicClientApplicationBuilder
                .Create(ClientId)
                .WithBroker()
                .WithReplyUri(redirectUriOnIos) // $"msauth.{Bundle.Id}://auth" (see step 6 below)
                .Build();

Step 2: Update AppDelegate to handle the callback

When MSAL.NET calls the broker, the broker then calls back to your application. It calls back by using the AppDelegate.OpenUrl method. Because MSAL waits for the response from the broker, your application needs to cooperate to call MSAL.NET back. You set up this behavior by updating the AppDelegate.cs file to override the method, as the following code shows.

public override bool OpenUrl(UIApplication app, NSUrl url,
                             string sourceApplication,
                             NSObject annotation)
{
 if (AuthenticationContinuationHelper.IsBrokerResponse(sourceApplication))
 {
  AuthenticationContinuationHelper.SetBrokerContinuationEventArgs(url);
  return true;
 }
 else if (!AuthenticationContinuationHelper.SetAuthenticationContinuationEventArgs(url))
 {
  return false;
 }
 return true;
}

This method is invoked every time the application is launched. It's an opportunity to process the response from the broker and to complete the authentication process that MSAL.NET started.

Step 3: Set a UIViewController()

For Xamarin iOS, you don't normally need to set an object window. But in this case you should set it so that you can send and receive responses from a broker. To set an object window, in AppDelegate.cs, you set a ViewController.

To set the object window, follow these steps:

In AppDelegate.cs, set the App.RootViewController to a new UIViewController(). This setting ensures that the call to the broker includes UIViewController. 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."

On the AcquireTokenInteractive call, use .WithParentActivityOrWindow(App.RootViewController). Pass in the reference to the object window that you'll use. Here's an example:

In App.cs:

   public static object RootViewController { get; set; }

In AppDelegate.cs:

   LoadApplication(new App());
   App.RootViewController = new UIViewController();

In the AcquireToken call:

result = await app.AcquireTokenInteractive(scopes)
             .WithParentActivityOrWindow(App.RootViewController)
             .ExecuteAsync();

Step 4: Register a URL scheme

MSAL.NET uses URLs to invoke the broker and then return the broker response back to your app. To finish the round trip, register your app's URL scheme in the Info.plist file.

To register your app's URL scheme, follow these steps:

Prefix CFBundleURLSchemes with msauth.

Add CFBundleURLName to the end. Follow this pattern:

$"msauth.(BundleId)"

Here, BundleId uniquely identifies your device. For example, if BundleId is yourcompany.xforms, your URL scheme is msauth.com.yourcompany.xforms.

This URL scheme will become part of the redirect URI that uniquely identifies your app when it receives the broker's response.

 <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>

Step 5: Add to the LSApplicationQueriesSchemes section

MSAL uses –canOpenURL: to check if the broker is installed on the device. In iOS 9, Apple locked down the schemes that an application can query for.

Add msauthv2 to the LSApplicationQueriesSchemes section of the Info.plist file, as in the following code example:

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

Brokered authentication for MSAL for iOS and macOS

Brokered authentication is enabled by default for Microsoft Entra scenarios.

Step 1: Update AppDelegate to handle the callback

When MSAL for iOS and macOS calls the broker, the broker calls back to your application by using the openURL method. Because MSAL waits for the response from the broker, your application needs to cooperate to call back MSAL. Set up this capability by updating the AppDelegate.m file to override the method, as the following code examples show.

- (BOOL)application:(UIApplication *)app
            openURL:(NSURL *)url
            options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options
{
    return [MSALPublicClientApplication handleMSALResponse:url
                                         sourceApplication:options[UIApplicationOpenURLOptionsSourceApplicationKey]];
}

    func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {

        guard let sourceApplication = options[UIApplication.OpenURLOptionsKey.sourceApplication] as? String else {
            return false
        }

        return MSALPublicClientApplication.handleMSALResponse(url, sourceApplication: sourceApplication)
    }

If you adopted UISceneDelegate on iOS 13 or later, then place the MSAL callback into the scene:openURLContexts: of UISceneDelegate instead. MSAL handleMSALResponse:sourceApplication: must be called only once for each URL.

For more information, see the Apple documentation.

Step 2: Register a URL scheme

MSAL for iOS and macOS uses URLs to invoke the broker and then return the broker response to your app. To finish the round trip, register a URL scheme for your app in the Info.plist file.

To register a scheme for your app:

Prefix your custom URL scheme with msauth.
Add your bundle identifier to the end of your scheme. Follow this pattern:

$"msauth.(BundleId)"

Here, BundleId uniquely identifies your device. For example, if BundleId is yourcompany.xforms, your URL scheme is msauth.com.yourcompany.xforms.

This URL scheme will become part of the redirect URI that uniquely identifies your app when it receives the broker's response. Make sure that the redirect URI in the format msauth.(BundleId)://auth is registered for your application.
```
<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>msauth.[BUNDLE_ID]</string>
        </array>
    </dict>
</array>
```

Step 3: Add LSApplicationQueriesSchemes

Add LSApplicationQueriesSchemes to allow calls to the Microsoft Authenticator app, if it's installed.

Note

The msauthv3 scheme is needed when your app is compiled by using Xcode 11 and later.

Here's an example of how to add LSApplicationQueriesSchemes:

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

Brokered authentication for Xamarin.Android

For information about enabling a broker on Android, see Brokered authentication on Xamarin.Android.

Next steps

Move on to the next article in this scenario, Acquiring a token.

Configure a mobile app that calls web APIs

Microsoft libraries supporting mobile apps

Instantiate the application

Android

iOS

Xamarin or UWP

Instantiate the application

Specify the parent UI, window, or activity

Find more app-building parameters

Tasks for Xamarin iOS

Tasks for MSAL for iOS and macOS

Tasks for Xamarin.Android

Tasks for UWP

Configure the application to use the broker

Enable the broker on Xamarin

Enable the broker for MSAL for Android

Enable the broker for MSAL for iOS and macOS

Enable brokered authentication for Xamarin iOS

Step 1: Enable broker support

Step 2: Update AppDelegate to handle the callback

Step 3: Set a UIViewController()

Step 4: Register a URL scheme

Step 5: Add to the LSApplicationQueriesSchemes section

Brokered authentication for MSAL for iOS and macOS

Step 1: Update AppDelegate to handle the callback

Step 2: Register a URL scheme

Step 3: Add LSApplicationQueriesSchemes

Brokered authentication for Xamarin.Android

Next steps

Feedback

Additional resources