search

AzureAD / microsoft-authentication-library-for-android

Microsoft Authentication Library (MSAL) for Android
http://aka.ms/aadv2
MIT License
216 stars 125 forks source link
android azure-active-directory identity microsoft msal

readme

Microsoft Authentication Library (MSAL) for Android

📚Documentation 🚀 Getting Started 💻 Sample Code 📖 Library Reference 🛠️ Support 🌐 Docs Site

Introduction

The Microsoft Authentication Library (MSAL) for Android enables developers to acquire security tokens from the Microsoft identity platform to authenticate users and access secured web APIs for their Android based applications. The MSAL library for Android gives your app the ability to use the Microsoft Cloud by supporting Microsoft Azure Active Directory and Microsoft Personal Accounts using industry standard OAuth2 and OpenID Connect. The library also supports Azure AD B2C.

Version Badge

:exclamation: Migrating from ADAL

ADAL Android was deprecated on June 2023. We do not support ADAL. See the ADAL to MSAL migration guide for Android

Using MSAL

Requirements

Step 1: Declare dependency on MSAL

Add to your app's build.gradle:

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

Please also add the following lines to your repositories section in your gradle script:

maven { 
    url 'https://pkgs.dev.azure.com/MicrosoftDeviceSDK/DuoSDK-Public/_packaging/Duo-SDK-Feed/maven/v1' 
}

Step 2: Create your MSAL configuration file

Configuration Documentation

It's simplest to create your configuration file as a "raw" resource file in your project resources. You'll be able to refer to this using the generated resource identifier when constructing an instance of PublicClientApplication. If you are registering your app in the portal for the first time, you will also be provided with this config JSON.

{
  "client_id" : "<YOUR_CLIENT_ID>",
  "redirect_uri" : "msauth://<YOUR_PACKAGE_NAME>/<YOUR_BASE64_URL_ENCODED_PACKAGE_SIGNATURE>",
  "broker_redirect_uri_registered": true,
}

NOTE: In the redirect_uri, the part <YOUR_PACKAGE_NAME> refers to the package name returned by the context.getPackageName() method. This package name is the same as the application_id defined in your build.gradle file.

NOTE: This is the minimum required configuration. MSAL relies on the defaults that ship with the library for all other settings. Please refer to the configuration file documentation to understand the library defaults.

Step 3: Configure the AndroidManifest.xml

  1. Request the following permissions via the Android Manifest
    <uses-permission android:name="android.permission.INTERNET"/>
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
  1. Configure an intent filter in the Android Manifest, using your redirect URI

NOTE: Failure to include an intent filter matching the redirect URI you specify via configuration will result in a failed interactive token request. Please double check this!

    <!--Intent filter to capture authorization code response from the default browser on the device calling back to our app after interactive sign in -->
    <activity
        android:name="com.microsoft.identity.client.BrowserTabActivity">
        <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="<YOUR_PACKAGE_NAME>"
                android:path="/<YOUR_BASE64_ENCODED_PACKAGE_SIGNATURE>" />
        </intent-filter>
    </activity>

NOTE: Please refer to this FAQ for more information on common redirect uri issues.

Step 4: Create an MSAL PublicClientApplication

NOTE: In this example we are creating an instance of MultipleAccountPublicClientApplication, which is designed to work with apps that allow multiple accounts to be used within the same application. If you would like to use SingleAccount mode, refer to the single vs. multi account documentation. You can also check out the quickstart for examples of how this is used.

  1. Create a new MultipleAccountPublicClientApplication instance.

String[] scopes = {"User.Read"};
IMultipleAccountPublicClientApplication mMultipleAccountApp = null;
IAccount mFirstAccount = null;

PublicClientApplication.createMultipleAccountPublicClientApplication(getContext(),
    R.raw.msal_config,
    new IPublicClientApplication.IMultipleAccountApplicationCreatedListener() {
        @Override
        public void onCreated(IMultipleAccountPublicClientApplication application) {
            mMultipleAccountApp = application;
        }

        @Override
        public void onError(MsalException exception) {
            //Log Exception Here
        }
    });
  1. Acquire a token interactively

mMultipleAccountApp.acquireToken(this, SCOPES, getAuthInteractiveCallback());

private AuthenticationCallback getAuthInteractiveCallback() {
    return new AuthenticationCallback() {
        @Override
        public void onSuccess(IAuthenticationResult authenticationResult) {
            /* Successfully got a token, use it to call a protected resource */
            String accessToken = authenticationResult.getAccessToken();
            // Record account used to acquire token
            mFirstAccount = authenticationResult.getAccount();
        }
        @Override
        public void onError(MsalException exception) {
            if (exception instanceof MsalClientException) {
                //And exception from the client (MSAL)
            } else if (exception instanceof MsalServiceException) {
                //An exception from the server
            }
        }
        @Override
        public void onCancel() {
            /* User canceled the authentication */
        }
    };
}
  1. Acquire a token silently

/*
    Before getting a token silently for the account used to previously acquire a token interactively, we recommend that you verify that the account is still present in the local cache or on the device in case of brokered auth

    Let's use the synchronous methods here which can only be invoked from a Worker thread
*/

//On a worker thread
IAccount account = mMultipleAccountApp.getAccount(mFirstAccount.getId());

if(account != null){
    //Now that we know the account is still present in the local cache or not the device (broker authentication)

    //Request token silently
    String[] newScopes = {"Calendars.Read"};

    String authority = mMultipleAccountApp.getConfiguration().getDefaultAuthority().getAuthorityURL().toString();

    //Use default authority to request token from pass null
    IAuthenticationResult result = mMultipleAccountApp.acquireTokenSilent(newScopes, account, authority);
}

ProGuard

MSAL uses reflection and generic type information stored in .class files at runtime to support various persistence and serialization related functionalities. Accordingly, library support for minification and obfuscation is limited. A default configuration is shipped with this library; please file an issue if you find any issues.

Community Help and Support

We use StackOverflow with the community to provide support. You should browse existing issues to see if someone has asked about your issue before. If there are workable solutions to your issue then try out those solutions. If not, ask your question and let the community help you out. We're part of the community too and watch for new questions. We help with answers when the community cannot give you a solution.

If you find and bug or have a feature request, please raise the issue on GitHub Issues.

Submit Feedback

We'd like your thoughts on this library. Please complete this short survey.

Contribute

We enthusiastically welcome contributions and feedback. You should clone the repo and start contributing now.

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.

Android Studio Build Requirement

Please note that this project uses Lombok internally and while using Android Studio you will need to install Lombmok Plugin to get the project to build successfully within Android Studio.

Recommendation

MSAL is a security library. It controls how users sign-in and access services. We recommend you always take the latest version of our library in your app when you can. We use semantic versioning so you can control the risk of updating your app. For example, always downloading the latest minor version number (e.g. x.y.x) ensures you get the latest security and feature enhanements with the assurance that our API surface area has not changed. You can always see the latest version and release notes under the Releases tab of GitHub.

Security Reporting

If you find a security issue with our libraries or services, please report the issue to secure@microsoft.com with as much detail as you can provide. 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 after receiving your issue report. We encourage you to get new security incident notifications by visiting Microsoft technical security notifications to subscribe to Security Advisory Alerts.

Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT License (the "License");