Quickstart: Sign in users in a sample mobile app

In this quickstart, you download and run a code sample that demonstrates how an Android application can sign in users and get an access token to call the Microsoft Graph API.

Applications must be represented by an app object in Microsoft Entra ID so that the Microsoft identity platform can provide tokens to your application.

In this quickstart, you download and run a code sample that demonstrates how a native iOS or macOS application can sign in users and get an access token to call the Microsoft Graph API.

The quickstart applies to both iOS and macOS apps. Some steps are needed only for iOS apps and will be indicated as such.

• Register a new app in the Microsoft Entra admin center, configured for Accounts in any organizational directory. 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
• Android Studio
• Android 16+

• 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
• XCode 10+
• iOS 10+
• macOS 10.12+

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.

1. Under Manage, select Authentication > Add Platform > iOS.
2. Enter the Bundle Identifier for your application. The bundle identifier is a unique string that uniquely identifies your application, for example com.<yourname>.identitysample.MSALMacOS. Make a note of the value you use. Note that the iOS configuration is also applicable to macOS applications.
3. Select Configure and save the MSAL Configuration details for later in this quickstart.
4. Select Done.

• Java: Download the code.
• Kotlin: Download the code.

Download the sample project

• Download the code sample for iOS
• Download the code sample for macOS

Install dependencies

1. Extract the zip file.
2. In a terminal window, navigate to the folder with the downloaded code sample and run pod install to install the latest MSAL library.

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, go to 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": false,
     "account_mode": "SINGLE",
     "authorities": [
       {
         "type": "AAD",
         "audience": {
           "type": "AzureADMultipleOrgs",
           "tenant_id": "common"
         }
       }
     ]
   }
   

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

5. Find the placeholder:

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

   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

Run the sample app

Select your emulator, or physical device, from Android Studio's available devices dropdown and run the app.

The sample app starts on the Single Account Mode screen. A default scope, user.read, is provided by default, which is used when reading your own profile data during the Microsoft Graph API call. The URL for the Microsoft Graph API call is provided by default. You can change both of these if you wish.

Use the app menu to change between single and multiple account modes.

In single account mode, sign in using a work or home account:

1. Select Get graph data interactively to prompt the user for their credentials. You'll see the output from the call to the Microsoft Graph API in the bottom of the screen.
2. Once signed in, select Get graph data silently to make a call to the Microsoft Graph API without prompting the user for credentials again. You'll see the output from the call to the Microsoft Graph API in the bottom of the screen.

In multiple account mode, you can repeat the same steps. Additionally, you can remove the signed-in account, which also removes the cached tokens for that account.

If you selected Option 1 above, you can skip these steps.

1. Open the project in XCode.

2. Edit ViewController.swift and replace the line starting with 'let kClientID' with the following code snippet. Remember to update the value for kClientID with the clientID that you saved when you registered your app earlier in this quickstart:

   let kClientID = "Enter_the_Application_Id_Here"
   

3. If you're building an app for Microsoft Entra national clouds, replace the line starting with 'let kGraphEndpoint' and 'let kAuthority' with correct endpoints. For Microsoft Azure operated by 21Vianet access, use values:

   let kGraphEndpoint = "https://microsoftgraph.chinacloudapi.cn/"
   let kAuthority = "https://login.partner.microsoftonline.cn/common"
   

4. Other endpoints are documented here.

5. Open the project settings. In the Identity section, enter the Bundle Identifier.

6. Right-click Info.plist and select Open As > Source Code.

7. Under the dict root node, replace Enter_the_bundle_Id_Here with the Bundle Id that you used in the portal. Notice the msauth. prefix in the string.

   <key>CFBundleURLTypes</key>
   <array>
      <dict>
         <key>CFBundleURLSchemes</key>
         <array>
            <string>msauth.Enter_the_Bundle_Id_Here</string>
         </array>
      </dict>
   </array>
   

8. Build and run the app!

The code is organized into fragments that show how to write a single and multiple accounts MSAL app. The code files are organized as follows:

We'll now look at these files in more detail and call out the MSAL-specific code in each.

Move on to the Android tutorial in which you build an Android app that gets an access token from the Microsoft identity platform and uses it to call the Microsoft Graph API.

Move on to the step-by-step tutorial in which you build an iOS or macOS app that gets an access token from the Microsoft identity platform and uses it to call the Microsoft Graph API.