Configure a mobile app that calls web APIs

Applies to: Workforce tenants External tenants (learn more)

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	Sign in users	Access web APIs	Generally available (GA) or Public preview1
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

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

UWP

This section explains how to instantiate the application for UWP apps.

Instantiate the application

In 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 MSAL for iOS and macOS

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

• Implement the openURL callback
• Enable keychain access groups
• Customize browsers and WebViews

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 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 iOS and macOS. In the two sets of instructions, some of the steps differ.

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:

1. Prefix your custom URL scheme with msauth.

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

Next steps

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