ערוך

שתף באמצעות

Tutorial: Prepare your Android (Kotlin) app for authentication

  • מאמר

This is the second tutorial in the tutorial series that demonstrates how to add Microsoft Authentication Library (MSAL) for Android to your Android (Kotlin) app. MSAL enables Android applications to authenticate users with Microsoft Entra.

In this tutorial, you'll:

  • Add MSAL dependencies.
  • Add Configuration.

Prerequisites

Add MSAL dependencies

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 select 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_ciam_auth.json.

  4. In the auth_config_ciam_auth.json file, add the following MSAL configurations:

    {
  "client_id" : "Enter_the_Application_Id_Here",
  "authorization_user_agent" : "DEFAULT",
  "redirect_uri" : "Enter_the_Redirect_Uri_Here",
  "account_mode" : "SINGLE",
  "authorities" : [
    {
      "type": "CIAM",
      "authority_url": "https://Enter_the_Tenant_Subdomain_Here.ciamlogin.com/Enter_the_Tenant_Subdomain_Here.onmicrosoft.com/"
    }
  ]
}

    The JSON configuration file specifies various settings for an Android application. It includes the client ID, authorization user agent, redirect URI, and account mode. Additionally, it defines an authority for authentication, specifying the type and authority URL.

    Replace the following placeholders with your tenant values that you obtained from the Microsoft Entra admin center:

    • Enter_the_Application_Id_Here and replace it with the Application (client) ID of the app you registered earlier.
    • Enter_the_Redirect_Uri_Here and replace it with the value of redirect_uri in the Microsoft Authentication Library (MSAL) configuration file you downloaded earlier when you added the platform redirect URL.
    • Enter_the_Tenant_Subdomain_Here and replace it with the Directory (tenant) subdomain. For example, if your tenant primary domain is contoso.onmicrosoft.com, use contoso. If you don't know your tenant subdomain, learn how to read your tenant details.

  5. Open /app/src/main/AndroidManifest.xml file.

  6. In AndroidManifest.xml, add the following data specification to an intent filter:

    <data
    android:host="ENTER_YOUR_PROJECT_PACKAGE_NAME_HERE"
    android:path="/ENTER_YOUR_SIGNATURE_HASH_HERE"
    android:scheme="msauth" />

    Find the placeholder:

    • ENTER_YOUR_PROJECT_PACKAGE_NAME_HERE and replace it with your Android's project package name.
    • ENTER_YOUR_SIGNATURE_HASH_HERE and replace it with the Signature Hash that you generated earlier when you added the platform redirect URL.

Use custom URL domain (Optional)

Use a custom domain to fully brand the authentication URL. From a user perspective, users remain on your domain during the authentication process, rather than being redirected to ciamlogin.com domain name.

Use the following steps to use a custom domain:

  1. Use the steps in Enable custom URL domains for apps in external tenants to enable custom URL domain for your external tenant.

  2. Open auth_config_ciam_auth.json file:

    1. Update the value of the authority_url property to https://Enter_the_Custom_Domain_Here/Enter_the_Tenant_ID_Here. Replace Enter_the_Custom_Domain_Here with your custom URL domain and Enter_the_Tenant_ID_Here with your tenant ID. If you don't have your tenant ID, learn how to read your tenant details.
    2. Add knownAuthorities property with a value [Enter_the_Custom_Domain_Here].

After you make the changes to your auth_config_ciam_auth.json file, if your custom URL domain is login.contoso.com, and your tenant ID is aaaabbbb-0000-cccc-1111-dddd2222eeee, then your file should look similar to the following snippet:

{
    "client_id" : "Enter_the_Application_Id_Here",
    "authorization_user_agent" : "DEFAULT",
    "redirect_uri" : "Enter_the_Redirect_Uri_Here",
    "account_mode" : "SINGLE",
    "authorities" : [
    {
        "type": "CIAM",
        "authority_url": "https://login.contoso.com/aaaabbbb-0000-cccc-1111-dddd2222eeee",
        "knownAuthorities": ["login.contoso.com"]
    }
    ]
}

Create MSAL SDK instance

To initialize MSAL SDK instance, use the following code:

private suspend fun initClient(): ISingleAccountPublicClientApplication = withContext(Dispatchers.IO) {
    return@withContext PublicClientApplication.createSingleAccountPublicClientApplication(
        this@MainActivity,
        R.raw.auth_config_ciam_auth
    )
}

The code initializes a single account public client application asynchronously. It uses the provided authentication configuration file and runs on the I/O dispatcher.

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

Next steps

Tutorial: Sign in users in Android (Kotlin) mobile app