Edit

Share via

Sign in users and call a protected web API in sample Android (Kotlin) app

  • Article

This guide demonstrates how to configure a sample Android mobile application to sign in users, and call an ASP.NET Core web API.

In this article, you do the following tasks:

  • Register an application in the Microsoft Entra admin center.
  • Add a platform redirect URL.
  • Enable public client flows.
  • Update the Android configuration code sample file to use your own Microsoft Entra External ID for customer tenant details.
  • Run and test the sample Android mobile application.
  • Call a protected web API.

Prerequisites

  • Android Studio.

  • An external tenant. If you don't already have one, sign up for a free trial.

  • An API registration that exposes at least one scope (delegated permissions) and one app role (application permission) such as ToDoList.Read. If you haven't already, follow the instructions for call an API in a sample Android mobile app to have a functional protected ASP.NET Core web API. Make sure you complete the following steps:

    • Register a web API application
    • Configure API scopes
    • Configure app roles
    • Configure optional claims
    • Clone or download sample web API
    • Configure and run sample web API

Register an application

To enable your application to sign in users with Microsoft Entra, Microsoft Entra External ID must be made aware of the application you create. The app registration establishes a trust relationship between the app and Microsoft Entra. When you register an application, External ID generates a unique identifier known as an Application (client) ID, a value used to identify your app when creating authentication requests.

The following steps show you how to register your app in the Microsoft Entra admin center:

  1. Sign in to the Microsoft Entra admin center as at least an Application Developer.

  2. If you have access to multiple tenants, use the Settings icon in the top menu to switch to your external tenant from the Directories + subscriptions menu.

  3. Browse to Identity >Applications > App registrations.

  4. Select + New registration.

  5. In the Register an application page that appears;

    1. Enter a meaningful application Name that is displayed to users of the app, for example ciam-client-app.
    2. Under Supported account types, select Accounts in this organizational directory only.

  6. Select Register.

  7. The application's Overview pane displays upon successful registration. Record the Application (client) ID to be used in your application source code.

Add a platform redirect URL

To specify your app type to your app registration, follow these steps:

  1. Under Manage, select Authentication.
  2. On the Platform configurations page, select Add a platform, and then select Android option.
  3. Enter your project's Package Name. If you downloaded the sample code, this value is com.azuresamples.msaldelegatedandroidkotlinsampleapp.
  4. In the Signature hash section of the Configure your Android app pane, select Generating a development Signature Hash. This will change for each development environment. Copy and run the KeyTool command for your operating system in your Terminal.
  5. Enter the Signature hash generated by KeyTool.
  6. Select Configure.
  7. Copy the MSAL Configuration from the Android configuration pane and save it for later app configuration.
  8. Select Done.

Enable public client flow

To identify your app as a public client, follow these steps:

  1. Under Manage, select Authentication.

  2. Under Advanced settings, for Allow public client flows, select Yes.

  3. Select Save to save your changes.

  1. From the App registrations page, select the application that you created (such as ciam-client-app) to open its Overview page.

  2. Under Manage, select API permissions. From the Configured permissions list, your application has been assigned the User.Read permission. However, since the tenant is an external tenant, the consumer users themselves can't consent to this permission. You as the admin must consent to this permission on behalf of all the users in the tenant:

    1. Select Grant admin consent for <your tenant name>, then select Yes.
    2. Select Refresh, then verify that Granted for <your tenant name> appears under Status for both scopes.

Grant web API permissions to the Android sample app

Once you've registered both your client app and web API and you've exposed the API by creating scopes, you can configure the client's permissions to the API by following these steps:

  1. From the App registrations page, select the application that you created (such as ciam-client-app) to open its Overview page.

  2. Under Manage, select API permissions.

  3. Under Configured permissions, select Add a permission.

  4. Select the APIs my organization uses tab.

  5. In the list of APIs, select the API such as ciam-ToDoList-api.

  6. Select Delegated permissions option.

  7. From the permissions list, select ToDoList.Read, ToDoList.ReadWrite (use the search box if necessary).

  8. Select the Add permissions button.

  9. At this point, you've assigned the permissions correctly. However, since the tenant is a customer's tenant, the consumer users themselves can't consent to these permissions. To address this, you as the admin must consent to these permissions on behalf of all the users in the tenant:

    1. Select Grant admin consent for <your tenant name>, then select Yes.

    2. Select Refresh, then verify that Granted for <your tenant name> appears under Status for both permissions.

  10. From the Configured permissions list, select the ToDoList.Read and ToDoList.ReadWrite permissions, one at a time, and then copy the permission's full URI for later use. The full permission URI looks something similar to api://{clientId}/{ToDoList.Read} or api://{clientId}/{ToDoList.ReadWrite}.

Clone sample Android mobile application

To obtain the sample application, you can either clone it from GitHub or download it as a .zip file.

  • To clone the sample, open a command prompt and navigate to where you wish to create the project, and enter the following command:

    git clone https://github.com/Azure-Samples/ms-identity-ciam-browser-delegated-android-sample

Configure the sample Android mobile application

To enable authentication and access to web API resources, configure the sample by following these steps:

  1. In Android Studio, open the project that you cloned.

  2. Open /app/src/main/res/raw/auth_config_ciam.json file.

  3. Find the placeholder:

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

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

  5. Find the placeholder:

    • ENTER_YOUR_SIGNATURE_HASH_HERE and replace it with the Signature Hash that you generated earlier when you added the platform redirect URL.

  6. Open /app/src/main/java/com/azuresamples/msaldelegatedandroidkotlinsampleapp/MainActivity.kt file.

  7. Find property named WEB_API_BASE_URL and set the URL to your web API.

  8. Find property named scopes and set the scopes recorded in Grant web API permissions to the Android sample app.

    private const val scopes = "" // Developers should set the respective scopes of their web API here. For example, private const val scopes = "api://{clientId}/{ToDoList.Read} api://{clientId}/{ToDoList.ReadWrite}"

You've configured the app and it's ready to run.

Run and test the sample Android mobile application

To build and run your app, follow these steps:

  1. In the toolbar, select your app from the run configurations menu.

  2. In the target device menu, select the device that you want to run your app on.

    If you don't have any devices configured, you need to either create an Android Virtual Device to use the Android Emulator or connect a physical Android device.

  3. Select the Run button.

  4. Select Acquire Token Interactively to request an access token.

  5. Select API - Perform GET to call the previously set up ASP.NET Core web API. A successful call to the web API returns HTTP 200, while HTTP 403 signifies unauthorized access.

Related content