languages:
Getting Started | Library | API Reference | Support |
---|
The MSAL Android library gives your app the ability to begin using the Microsoft identity platform by supporting Microsoft Entra ID and Microsoft Accounts in a converged experience using industry standard OAuth2 and OpenID Connect protocols.
This sample walks you through the process of integrating authentication with Microsoft Identity Platform (formerly Microsoft Entra ID for developers) in your android application. In this sample we'd walk you through the code you need to write in the various lifecycle events of your app to achieve the following objectives.
This sample app is a multi-tenant app, which means that it can sign-in users from any Microsoft Entra tenant and Microsoft Accounts. It also demonstrates how a developer can build apps to connect with enterprise users and access their Azure + O365 data via Microsoft Graph. During the auth flow, the users will be required to sign-in first, if it is their first time signing-in to the app, the user would be asked to consent to the permissions required by the application.
The majority of the logic in this sample shows how to sign-in an end user and make a call to the Microsoft Graph to get basic information about the signed-in user.
Microsoft provides applications for every mobile platform that allow for the bridging credentials across applications from different vendors and for enhanced features that require a single secure place from where to validate credentials. These applications are called Brokers. The brokers available for Android are Microsoft Authenticator and Company Portal. Learn more about Brokers here.
The MSAL for Android will automatically use the broker if they are present on the device.
Note: If you have older versions of Microsoft Authenticator or Company Portal App installed in the device where this sample application will be run, then the user might not be able to test the scenarios presented here. Please make sure that you have installed the latest version of Microsoft Authenticator or Company Portal on your device.
In the Single Account
Mode, only one user can sign into the application at a time. If the app wants to support just one signed-in user, it is recommended to use the Single Account
Mode.
The following code snippet from SingleAccountModeFragment class shows how the application is set to the Single Account
Mode in the code:
PublicClientApplication.createSingleAccountPublicClientApplication(
getContext(),
R.raw.auth_config_single_account);
In the auth_config_single_account.json file, the account_mode
is set as following:
"account_mode" : "SINGLE",
Shared Device
Mode will allow you to configure Android devices to be shared by multiple employees, while providing Microsoft Identity backed management of the device. Employees will be able to sign-in to their devices and access customer information quickly. When they are finished with their shift or task, they will be able to globally Sign-Out of the device and it will be immediately ready for the next employee to use.
[!NOTE] Applications that run on Shared Devices must be in Single Account Mode. Applications that only support Multiple Account Mode will not run on a Shared Device.
In the code, you can use the isSharedDevice()
flag to determine if an application is in the Shared Device Mode. Your app can use this flag to modify UX accordingly.
Code snippet from SingleAccountModeFragment class showing usage of the isSharedDevice()
flag:
deviceModeTextView.setText(mSingleAccountApp.isSharedDevice() ? "Shared" : "Non-Shared");
[!NOTE] You can only put a device in to Shared Mode using the Authenticator app and with a user who is in the Cloud Device Administrator role. You can configure the membership of your Organizational Roles by going to the Microsoft Entra admin center and selecting:
Microsoft Entra ID -> Roles and Administrators -> Cloud Device Administrator
In the Multiple Account
Mode, the application supports multiple accounts and can switch between user accounts and get data from that user's account.
Code snippet from MultipleAccountModeFragment class shows how the application is set in the Multiple Account
Mode in the code:
PublicClientApplication.createMultipleAccountPublicClientApplication(getContext(),
R.raw.auth_config_multiple_account);
To run this sample, you'll need:
This sample ships with a default
redirect_uri
configured in theAndroidManifest.xml
. In order for the defaultredirect_uri
to work, this project must be built with thedebug.keystore
located in thegradle/
directory. To configure signing in Android Studio, see Sign Your App.
From your shell or command line:
git clone https://github.com/Azure-Samples/ms-identity-android-kotlin.git
The following steps have been carried out for android studio, but you can choose and work with any editor of your choice.
Open Android Studio, and select open an existing Android Studio project. Find the cloned project and open it.
From menu, select Run > Run 'app'. Once the app launches,
Click on the hamburger icon
Single Account: Select this to explore Single Account Mode
Multiple Account: Select this to explore Multiple Account Mode.
Click on sign-in, it takes you to add account
page.
Add one or more accounts as per the device mode, and sign in with your test account.
Once successfully signed-in, basic user details will be displayed.
To explore more about the application, follow on screen options.
This sample application is configured to run out-of-the-box. To register your own application and run the sample with those settings, follow below steps.
To begin registering your app, start at the Microsoft Entra admin center
To create an app registration,
Click New Registration
.
Name your app, select the audience you're targeting, and click Register
.
In the Overview
> Sign in users in 5 minutes
> Android
.
Make this changes for me
.Hit the Make updates
button. Note the MSAL Configuration as it is used later in AndroidManifest.xml
and auth_config.json
.
Configure the sample application with your app registration by replacing the sample code in auth_config.json
and AndroidManifest.xml
Copy and paste the MSAL Configuration JSON from the Microsoft Entra admin center into auth_config.json
.
Inside the AndroidManifest.xml
, replace android:host
and android:path
with the same info saved in above step.
auth_config.json
contains this information as a reference inside the redirect_uri
field.AndroidManifest.xml
.
Refer Microsoft Entra ID Android Quickstart for more detailsFrom menu, select Build > Clean Project and Run > Run 'app'.
The following code fragments walk through features that MSAL can implement.
Contains code showing how the Single Account
Mode is implemented. The includes authentication, obtaining the token, and making a Graph API call using the obtained token.
The following steps give you more details.
Create a SingleAccount PublicClientApplication:
PublicClientApplication.createSingleAccountPublicClientApplication(
context as Context,
R.raw.auth_config_single_account,
object : IPublicClientApplication.ISingleAccountApplicationCreatedListener {
override fun onCreated(application: ISingleAccountPublicClientApplication) {
}
override fun onError(exception: MsalException) {
}
})
Signing in a user:
mSingleAccountApp!!.signIn(activity as Activity, "", getScopes(), getAuthInteractiveCallback())
Acquiring token:
Interactive:
mSingleAccountApp!!.acquireToken(activity!!, getScopes(), getAuthInteractiveCallback())
Silent:
mSingleAccountApp!!.acquireTokenSilentAsync(getScopes(), AUTHORITY, getAuthSilentCallback())
Calling Graph API to get basic user details and displaying data:
private fun callGraphAPI(authenticationResult: IAuthenticationResult) {
MSGraphRequestWrapper.callGraphAPIWithVolley(
context as Context,
msgraph_url.text.toString(),
authenticationResult.accessToken,
Response.Listener<JSONObject> { response ->
/* Successfully called graph, process data and send to UI */
Log.d(TAG, "Response: $response")
displayGraphResult(response)
},
Response.ErrorListener { error ->
Log.d(TAG, "Error: $error")
displayError(error)
})
}
Sign-out:
mSingleAccountApp!!.signOut(object : ISingleAccountPublicClientApplication.SignOutCallback {
override fun onSignOut() {
}
override fun onError(exception: MsalException) {
}
});
When sign-out is performed it removes the signed-in account and cached tokens from this app.
Contains code showing how the Multiple Account
Mode is implemented. The includes authentication, obtaining the token, and making a Graph API call using the obtained token.
Create a MultipleAccount PublicClientApplication:
PublicClientApplication.createMultipleAccountPublicClientApplication(
context as Context,
R.raw.auth_config_multiple_account,
object : IPublicClientApplication.IMultipleAccountApplicationCreatedListener {
override fun onCreated(application: IMultipleAccountPublicClientApplication) {
mMultipleAccountApp = application
}
override fun onError(error: MsalException){
}
});
Acquiring token:
Interactive:
mMultipleAccountApp!!.acquireToken(activity as Activity, getScopes(), getAuthInteractiveCallback())
Silent:
mMultipleAccountApp.acquireTokenSilentAsync(getScopes(),
accountList.get(accountListSpinner.getSelectedItemPosition()),
AUTHORITY,
getAuthSilentCallback());
Get Accounts:
mMultipleAccountApp!!.acquireTokenSilentAsync(
getScopes(),
accountList!![account_list.selectedItemPosition],
AUTHORITY,
getAuthSilentCallback()
)
Remove account:
mMultipleAccountApp!!.removeAccount(
accountList!![account_list.selectedItemPosition],
object : IMultipleAccountPublicClientApplication.RemoveAccountCallback {
override fun onRemoved() {
}
override fun onError(exception: MsalException) {
}
})
We use Stack Overflow with the community to provide support. We highly recommend you ask your questions on Stack Overflow first and browse existing issues to see if someone has asked your question before.
If you find and bug or have a feature request, please raise the issue on GitHub Issues.
To provide a recommendation, visit our User Voice page.
We enthusiastically welcome contributions and feedback. You can clone the repo and start contributing now. Read our Contribution Guide for more information.
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.
This library controls how users sign-in and access services. We recommend you always take the latest version of our library in your app when possible. We use semantic versioning so you can control the risk associated with updating your app. As an example, always downloading the latest minor version number (e.g. x.y.x) ensures you get the latest security and feature enhancements but our API surface remains the same. You can always see the latest version and release notes under the Releases tab of GitHub.
If you find a security issue with our libraries or services please report it to secure@microsoft.com with as much detail as possible. Your submission may be eligible for a bounty through the Microsoft Bounty program. Please do not post security issues to GitHub Issues or any other public site. We will contact you shortly upon receiving the information. We encourage you to get notifications of when security incidents occur by visiting this page and subscribing to Security Advisory Alerts.
The documentation for the Microsoft identity platform is available from Microsoft identity platform (v2.0) overview.
Other samples for the Microsoft identity platform are available from Microsoft identity platform code samples.
The conceptual documentation for MSAL Android is available from Microsoft authentication library for android conceptual documentation.