Edit

Share via

Tutorial: Set up an Android app to sign in users by using Microsoft identity platform

Applies to: Green circle with a white check mark symbol. Workforce tenants Green circle with a white check mark symbol. External tenants (learn more)

In this tutorial you how to add Microsoft Authentication Library (MSAL) for Android to your Android app. MSAL enables Android applications to authenticate users with Microsoft Entra.

In this tutorial you'll;

  • Add MSAL dependency
  • Add configuration
  • Create MSAL SDK instance

Prerequisites

  • A workforce tenant. You can use your Default Directory or set up a new tenant.
  • Register a new app in the Microsoft Entra admin center, configured for Accounts in this organizational directory only. Refer to Register an application for more details. Record the following values from the application Overview page for later use:
    • Application (client) ID
    • Directory (tenant) ID
  • An Android project. If you don't have an Android project, create it.

Add a redirect URI

You must configure specific redirect URIs in your app registration to ensure compatibility with the downloaded code sample. These URIs are essential for redirecting users back to the app after they successfully sign in.

  1. Under Manage, select Authentication > Add a platform > Android.

  2. Enter your project's Package Name based on the sample type you downloaded above.

    • Java sample - com.azuresamples.msalandroidapp
    • Kotlin sample - com.azuresamples.msalandroidkotlinapp

  3. In the Signature hash section of the Configure your Android app pane, select Generating a development Signature Hash. and copy the KeyTool command to your command line.

    • KeyTool.exe is installed as part of the Java Development Kit (JDK). You must also install the OpenSSL tool to execute the KeyTool command. For more information, see Android documentation on generating a key for more information.

  4. Enter the Signature hash generated by KeyTool.

  5. Select Configure and save the MSAL Configuration that appears in the Android configuration pane so you can enter it when you configure your app later.

  6. Select Done.

Add MSAL dependency and relevant libraries to your project

To add MSAL dependencies in your Android project, follow these steps:

  1. Open your project in Android Studio or create a new project.

  2. Open your application's build.gradle and add the following dependencies:

    allprojects {
repositories {
    //Needed for com.microsoft.device.display:display-mask library
    maven {
        url 'https://pkgs.dev.azure.com/MicrosoftDeviceSDK/DuoSDK-Public/_packaging/Duo-SDK-Feed/maven/v1'
        name 'Duo-SDK-Feed'
    }
    mavenCentral()
    google()
    }
}
//...

dependencies { 
    implementation 'com.microsoft.identity.client:msal:5.+'
    //...
}

    In the build.gradle configuration, repositories are defined for project dependencies. It includes a Maven repository URL for the com.microsoft.device.display:display-mask library from Azure DevOps. Additionally, it utilizes Maven Central and Google repositories. The dependencies section specifies the implementation of the MSAL version 5 and potentially other dependencies.

  3. In Android Studio, select File > Sync Project with Gradle Files.

Add configuration

You pass the required tenant identifiers, such as the application (client) ID, to the MSAL SDK through a JSON configuration setting.

Use these steps to create configuration file:

  1. In Android Studio's project pane, navigate to app\src\main\res.

  2. Right-click res and choose New > Directory. Enter raw as the new directory name and select OK.

  3. In app > src > main > res > raw, create a new JSON file called auth_config_single_account.json and paste the MSAL Configuration that you saved earlier.

    Below the redirect URI, paste:

      "account_mode" : "SINGLE",

    Your config file should resemble this example:

    {
  "client_id": "00001111-aaaa-bbbb-3333-cccc4444",
  "authorization_user_agent": "WEBVIEW",
  "redirect_uri": "msauth://com.azuresamples.msalandroidapp/00001111%cccc4444%3D",
  "broker_redirect_uri_registered": true,
  "account_mode": "SINGLE",
  "authorities": [
    {
      "type": "AAD",
      "audience": {
        "type": "AzureADandPersonalMicrosoftAccount",
        "tenant_id": "common"
      }
    }
  ]
}

    As this tutorial only demonstrates how to configure an app in Single Account mode, see single vs. multiple account mode and configuring your app for more information

  4. We recommend using 'WEBVIEW'. In case you want to configure "authorization_user_agent" as 'BROWSER' in your app, you need make the following updates. a) Update auth_config_single_account.json with "authorization_user_agent": "Browser". b) Update AndroidManifest.xml. In the app go to app > src > main > AndroidManifest.xml, add the BrowserTabActivity activity as a child of the <application> element. This entry allows Microsoft Entra ID to call back to your application after it completes the authentication:

    <!--Intent filter to capture System Browser or Authenticator calling back to our app after sign-in-->
<activity
    android:name="com.microsoft.identity.client.BrowserTabActivity"
    android:exported="true">
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data android:scheme="msauth"
            android:host="Enter_the_Package_Name"
            android:path="/Enter_the_Signature_Hash" />
    </intent-filter>
</activity>
    • Use the Package name to replace android:host=. value. It should look like com.azuresamples.msalandroidapp.
    • Use the Signature Hash to replace android:path= value. Ensure that there's a leading / at the beginning of your Signature Hash. It should look like /aB1cD2eF3gH4+iJ5kL6-mN7oP8q=.

    You can find these values in the Authentication blade of your app registration as well.

Create MSAL SDK instance

To initialize MSAL SDK instance, use the following code:

PublicClientApplication.createSingleAccountPublicClientApplication(
    getContext(),
    R.raw.auth_config_single_account,
    new IPublicClientApplication.ISingleAccountApplicationCreatedListener() {
        @Override
        public void onCreated(ISingleAccountPublicClientApplication application) {
            // Initialize the single account application instance
            mSingleAccountApp = application;
            loadAccount();
        }

        @Override
        public void onError(MsalException exception) {
            // Handle any errors that occur during initialization
            displayError(exception);
        }
    }
);

This code creates a single account public client application using the configuration file auth_config_single_account.json. When the application is successfully created, it assigns the instance to mSingleAccountApp and calls the loadAccount() method. If an error occurs during the creation, it handles the error by calling the displayError(exception) method.

Make sure you include the import statements. Android Studio should include the import statements for you automatically.

Next steps

Tutorial: Add add sign-in in your Android app.