This library, ADAL for Android, will no longer receive new feature improvements. Instead, use the new library MSAL for Android.

• If you are starting a new project, you can get started with the MSAL for Android docs for details about the scenarios, usage, and relevant concepts.
• If your application is using the previous ADAL for Android library, you can follow this migration guide to update to MSAL for Android.
• Existing applications relying on ADAL for Android will continue to work.

Microsoft Azure Active Directory Authentication Library (ADAL) for Android

ADAL for Android gives you the ability to add support for Work Accounts to your application. This SDK gives your application the full functionality of Microsoft Azure AD, including industry standard protocol support for OAuth2, Web API integration with user level consent, and two-factor authentication support. Best of all, it’s FOSS (Free and Open Source Software) so that you can participate in the development process as we build these libraries.

A Work Account is an identity you use to get work done from your organization or school. Anywhere you need to get access to your work life you'll use a Work Account. The Work Account can be tied to an Active Directory server running in your datacenter or live completely in the cloud like when you use Office 365. A Work Account will be how your users know that they are accessing their important documents and data backed my Microsoft security.

ADAL for Android 3.0.0 Released!

Please note: Production ADAL 2.0.x releases (first released March 2020) are neither API-compatible nor cache-compatible with the following versions:
    - 2.0-alpha (released 2015-07-27)
    - 2.0.1-alpha (released 2015-09-25)
    - 2.0.2-alpha (released 2016-05-27)
    - 2.0.3-alpha (released 2016-06-11)
    - 2.0.4-alpha (released 2017-02-17)

Build status

Branch	Status
dev (Travis)
dev (VSTS)

Note: A corpnet account is required to view the VSTS build.

Versions

Current version - 3.1.2

Minimum recommended version - 1.16.3-hf1

You can find version-to-version differences in the change log.

Features

• Industry standard Oauth2 protocol support.
• Id Token exposure for full access to the token contents.
• Multi-resource refresh token allows for apps registered together to access different APIs without prompting the user.
• Cache with Encryption for easily accessing existing tokens and session state with assurance it wasn't tampered with.
• Support for the Microsoft Azure AD Authenticator plug-in for Android, which will be released soon!
• Dialog and Fragment support

Samples and Documentation

We provide a full suite of sample applications and documentation on GitHub to help you get started with learning the Azure Identity system. This includes tutorials for native clients such as Windows, Windows Phone, iOS, OSX, Android, and Linux. We also provide full walkthroughs for auth flows, the Microsoft Graph API, other Microsoft APIs, and other Azure AD features.

Checkout the ADAL for Android sample app for help getting started.

Looking for Xamarin?

Community Help and Support

We leverage Stack Overflow to work with the community on supporting Azure Active Directory and its SDKs, including this one! We highly recommend you ask your questions on Stack Overflow (we're all on there!) Also browse existing issues to see if someone has had your question before.

Submit Feedback

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

SSO and Conditional Access Support

This library allows your application to support our Enterprise Mobility Suite, including Conditional Access, so businesses can use your application in their secure environment.

To configure your application to support these scenarios, please read this document: How to enable cross-app SSO on Android using ADAL

Security Reporting

If you find a security issue with our libraries or services please report it to [email protected] 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.

Contributing

All code is licensed under the MIT license and we triage actively on GitHub. We enthusiastically welcome contributions and feedback.

For more details about contribution

Quick Start

To build with Gradle,

• Clone this repo in to a directory of your choice
• Setup emulator with SDK 23
• Go to the root folder where you cloned this repo
• To run the sample app, connect the test device and run the command: ./gradlew :userappwithbroker:installDebug
• You should see app 'Fancy ADAL Test App' installed on the test device
• Select an authority, [optionally] enter a login hint and/or query parameters, and click Acquire Token to enter credentials with AAD

Note: The authority, clientId, redirectUri and resource of the test app can be found in Constants.java. These values can be updated as necessary to test different tenants and configurations.

To build with Maven, you can use the pom.xml at top level

• Clone this repo in to a directory of your choice
• Follow the steps at Prerequisites section to setup your maven for android
• Setup emulator with SDK 19
• Go to the root folder where you cloned this repo
• Run the command: mvn clean install
• Change the directory to the Quick Start sample: cd userappwithbroker/
• Run the command: mvn android:deploy android:run
• You should see app launching
• Enter test user credentials to try!

Jar packages will be also submitted beside the aar package.

Download

We've made it easy for you to have multiple options to use this library in your Android project:

• You can use the source code to import this library into Android Studio and link to your application.
• If using Android Studio, you can use aar package format and reference the binaries.

Option 1: Source via Git

To get the source code of the SDK via git:

git clone --recurse-submodules [email protected]:AzureAD/azure-activedirectory-library-for-android.git
cd ./azure-activedirectory-library-for-android/src

Option 2: Binaries via Gradle

You can get the binaries from Maven central repo. AAR package can be included as follows in your project in AndroidStudio:

repositories {
    mavenCentral()
    maven {
        // Surface Duo SDK dependency.
        url 'https://pkgs.dev.azure.com/MicrosoftDeviceSDK/DuoSDK-Public/_packaging/Duo-SDK-Feed%40Local/maven/v1'
    }
}
dependencies {
    // your dependencies here...
    compile('com.microsoft.aad:adal:3.0.1') {
        // if your app includes android support
        // libraries, Gson or Surface Duo SDK 
        // in its dependencies, exclude that 
        // groupId from ADAL's compile task by 
        // un-commenting the appropriate line below

        // exclude group: 'com.android.support'
        // exclude group: 'com.google.code.gson'
        // exclude group: 'com.microsoft.device.display'
    }
}

Option 3: aar via Maven

If you are using the m2e plugin in Eclipse, you can specify the dependency in your pom.xml file:

<dependency>
    <groupId>com.microsoft.aad</groupId>
    <artifactId>adal</artifactId>
    <version>3.0.1</version>
    <type>aar</type>
</dependency>

Option 4: jar package inside libs folder

You can get the jar file from maven the repo and drop into the libs folder in your project. You need to copy the required resources to your project as well since the jar packages don't include them.

Prerequisites

• Maven 3.1.1+
• Git
• Android SDK
• AVD image running (API level 14) or higher.
• Android SDK with ALL packages installed
• You may use any IDE that supports Maven. Eclipse ADT will work fine after you complete prereq step.

How To use this library

1. Follow the Prerequisites

2. Add a reference to your project and specify it as an Android library. If you are uncertain how to do this, click here for more information.

3. Add the project dependency for debugging in to your project settings

4. Update your project's AndroidManifest.xml file to include:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<application
    android:allowBackup="true"
    android:debuggable="true"
    android:icon="@drawable/ic_launcher"
    android:label="@string/app_name"
    android:theme="@style/AppTheme" >

    <activity
        android:name="com.microsoft.aad.adal.AuthenticationActivity"
        android:label="@string/title_login_hello_app" >
    </activity>
....
<application/>

5. Register your WEBAPI service app in Azure Active Directory (AAD). If you're not sure what a tenant is or how you would get one, read What is a Microsoft Azure AD tenant? or Sign up for Microsoft Azure as an organization. These docs should get you started on your way to using Windows Azure AD.

• NOTE: You need to write down the APP ID URI for the next steps

6. Register your client native app at AAD. Select webapis in the list and give permission to previously registered WebAPI. If you need help with this step, see: Register the REST API Service Windows Azure Active Directory

• NOTE: You will need to write down the clientId and redirectUri parameters for the next steps.

7. Create an instance of AuthenticationContext at your main Activity. The details of this call are beyond the scope of this README, but you can get a good start by looking at the Android Native Client Sample. Below is an example:

   // Authority is in the form of https://login.windows.net/yourtenant.onmicrosoft.com
   mContext = new AuthenticationContext(MainActivity.this, authority, true); // This will use SharedPreferences as default cache

• NOTE: mContext is a field in your activity

8. Copy this code block to handle the end of AuthenticationActivity after user enters credentials and receives authorization code:

    @Override
    protected void onActivityResult(int requestCode, int resultCode, Intent data) {
        super.onActivityResult(requestCode, resultCode, data);
        if (mContext != null) {
            mContext.onActivityResult(requestCode, resultCode, data);
        }
    }

9. To ask for a token, you define a callback

   • NOTE: In releases 1.13.2, 1.13.3, and 1.14.0 the onError(Exception) and onSuccess(AuthenticationResult) callbacks may not be invoked on the UI thread. This issue is tracked here.

   private AuthenticationCallback<AuthenticationResult> callback = new AuthenticationCallback<AuthenticationResult>() {
   
           @Override
           public void onError(Exception exc) {
               if (exc instanceof AuthenticationException) {
                   textViewStatus.setText("Cancelled");
                   Log.d(TAG, "Cancelled");
               } else {
                   textViewStatus.setText("Authentication error:" + exc.getMessage());
                   Log.d(TAG, "Authentication error:" + exc.getMessage());
               }
           }
   
           @Override
           public void onSuccess(AuthenticationResult result) {
               mResult = result;
   
               if (result == null || result.getAccessToken() == null
                       || result.getAccessToken().isEmpty()) {
                   textViewStatus.setText("Token is empty");
                   Log.d(TAG, "Token is empty");
               } else {
                   // request is successful
                   Log.d(TAG, "Status:" + result.getStatus() + " Expired:"
                           + result.getExpiresOn().toString());
                   textViewStatus.setText(PASSED);
               }
           }
       };

10. Finally, ask for a token using that callback:

     mContext.acquireToken(MainActivity.this, resource, clientId, redirect, user_loginhint, PromptBehavior.Auto, "",
                    callback);

    If you're implementing your authentication logic in a Fragment, you'll need to wrap it in an IWindowComponent before passing it as a parameter, like this:

mContext.acquireToken(
    wrapFragment(MainFragment.this),
    resource,
    clientId,
    redirect,
    user_loginhint,
    PromptBehavior.Auto,
    "",
    callback);

private IWindowComponent wrapFragment(final Fragment fragment){
    return new IWindowComponent() {
        Fragment refFragment = fragment;
        @Override
        public void startActivityForResult(Intent intent, int requestCode) {
            refFragment.startActivityForResult(intent, requestCode);
        }
    };
}

Explanation of the parameters:

• Resource is required and is the resource you are trying to access.
• Clientid is required and comes from the AzureAD Portal.
• You can setup redirectUri as your packagename. It is not required to be provided for the acquireToken call.
• PromptBehavior helps to ask for credentials to skip cache and cookie.
• Callback will be called after authorization code is exchanged for a token.

Examples can be found at Android Native Client Sample.

The Callback receives an object of type AuthenticationResult which has accesstoken, date expired, and idtoken info.

acquireTokenSilentSync

In order to get token back without prompt, you can call acquireTokenSilentSync which handles caching and token refresh without UI prompt. It provides async version as well. Note: userId required in silent call is the one you get back from the interactive call) as parameter.

mContext.acquireTokenSilentSync(String resource, String clientId, String userId);

or

mContext.acquireTokenSilent(
    String resource,
    String clientId,
    String userId,
    final AuthenticationCallback<AuthenticationResult> callback);

11. Broker:

Microsoft Intune's Company portal App and Azure Authenticator App will provide the broker component. In order to acquire token via broker, the following requirements have to be met (please check samples\userappwithbroker for authentication via broker):

• Starting version 1.1.14, developer has to explicitly specify set to use broker via: AuthenticationSettings.INSTANCE.setUseBroker(true);
• Developer needs to register special redirectUri for broker usage. RedirectUri is in the format of msauth://packagename/Base64UrlencodedSignature. You can get your redirecturi for your app using the script GetBrokerRedirectURI.ps1 on Windows or brokerRedirectPrint.sh on Linux or Mac. You can also use API call mContext.getBrokerRedirectUri. Signature is related to your signing certificates.
• If target version is lower than 23, calling app has to have the following permissions declared in the manifest:
  • GET_ACCOUNTS
  • USE_CREDENTIALS
  • MANAGE_ACCOUNTS
• If target version is 23 or higher, USE_CREDENTIALS and MANAGE_ACCOUNTS are deprecated. But GET_ACCOUNTS is under protection level "dangerous", calling app is responsible for requesting the run-time permission; see Runtime permission request for API 23.
• If you get an exception like "Broker related permissions are missing for GET_ACCOUNTS" with error code "DEVELOPER_BROKER_PERMISSIONS_MISSING" when acquiring token, it means you're using a very old version of ADAL(prior to V1.12.0) or broker app(Microsoft Authenticator or Intune Company Portal), please upgrade to the latest version of ADAL and broker app.
• There must be an account existed and registered via one of the two broker apps.

AuthenticationContext provides API method to get the broker user.

String brokerAccount = mContext.getBrokerUser();

Broker user will be returned if account is valid.

Using this walkthrough, you should have what you need to successfully integrate with Azure Active Directory. For more examples of this working, visit the AzureADSamples/ repository on GitHub.

Important Information

Customization

Library project resources can be overwritten by your application resources. This happens when your app is building. For this reason, you can customize Authentication Activity layout the way you want. You need to make sure to keep the id of the controls that ADAL uses(Webview).

Broker

Broker component will be delivered with Intune's Company portal app. Account will be created in Account Manager. Account type is "com.microsoft.workaccount". It only allows single SSO account. It will create SSO cookie for this user after completing device challenge for one of the apps.

Authority Url and ADFS

ADFS is not recognized as production STS, so you need to turn of instance discovery and pass false at AuthenticationContext constructor.

Authority url needs STS instance and tenant name: https://login.windows.net/yourtenant.onmicrosoft.com

Federated sign-in failure if additional certificate downloads are required

Federated sign-in may fail when attempting to authenticate using the Azure Active Directory Authentication Library (ADAL) for Android. See Using ADAL to authenticate from Android devices fails if additional certificate downloads are required for more information.

Querying cache items

ADAL provides Default cache in SharedPrefrences with some simple cache query methods. You can get the current cache from AuthenticationContext with:

ITokenCacheStore cache = mContext.getCache();

You can also provide your cache implementation, if you want to customize it.

mContext = new AuthenticationContext(MainActivity.this, authority, true, yourCache);

PromptBehavior

ADAL provides option to specify prompt behavior. PromptBehavior.Auto will pop up UI if refresh token is invalid and user credentials are required. PromptBehavior.Always will skip the cache usage and always show UI.

Handle Doze and App Standby

Starting Android 6.0, Android introduces the new battery optimization, which will cause no network access when it's in doze and app standby mode. This wiki page contains details for doze mode and how to handle it with ADAL (https://github.com/AzureAD/azure-activedirectory-library-for-android/wiki/Handle-Doze-and-App-Standby).

Silent token request from cache and refresh

This method does not use UI pop up and not require an activity. It will return token from cache if available. If token is expired, it will try to refresh it. If refresh token is expired or failed, it will return AuthenticationException.

Future<AuthenticationResult> result = mContext.acquireTokenSilent(resource, clientid, userId, callback );

You can also make sync call with this method. You can set null to callback or use acquireTokenSilentSync.

ProGuard

If you are using ProGuard, we suggest disabling shrinking and obfuscation of ADAL classes so that our development team may assist you should issues arise. Additionally, portions of our unit and automation test code rely heavily on reflection and may not execute predictably across different versions of ProGuard.

To disable obfuscation of ADAL classes:

-keep class com.microsoft.** {
  *;
}

Diagnostics

The following are the primary sources of information for diagnosing issues:

• Exceptions
• Logs
• Network traces

Also, note that correlation IDs are central to the diagnostics in the library. You can set your correlation IDs on a per request basis if you want to correlate an ADAL request with other operations in your code. If you don't set a correlations id then ADAL will generate a random one and all log messages and network calls will be stamped with the correlation id. The self generated id changes on each request.

Exceptions

This is obviously the first diagnostic. We try to provide helpful error messages. If you find one that is not helpful please file an issue and let us know. Please also provide device information such as model and SDK#.

Logs

You can configure the library to generate log messages that you can use to help diagnose issues. You configure logging by making the following call to configure a callback that ADAL will use to hand off each log message as it is generated.

Logger.getInstance().setExternalLogger(new ILogger() {
    @Override
    public void Log(String tag, String message, String additionalMessage, LogLevel level, ADALError errorCode) {
     ...
     // You can write this to logfile depending on level or errorcode.
     writeToLogFile(getApplicationContext(), tag +":" + message + "-" + additionalMessage);
    }
}

Messages can be written to a custom log file as seen below. Unfortunately, there is no standard way of getting logs from a device. There are some services that can help you with this. You can also invent your own, such as sending the file to a server.

private syncronized void writeToLogFile(Context ctx, String msg) {
       File directory = ctx.getDir(ctx.getPackageName(), Context.MODE_PRIVATE);
       File logFile = new File(directory, "logfile");
       FileOutputStream outputStream = new FileOutputStream(logFile, true);
       OutputStreamWriter osw = new OutputStreamWriter(outputStream);
       osw.write(msg);
       osw.flush();
       osw.close();
}

Logging Levels

• Error(Exceptions)
• Warn(Warning)
• Info(Information purposes)
• Verbose(More details)

You set the log level like this: Logger.getInstance().setLogLevel(Logger.LogLevel.Verbose);

All log messages are sent to logcat in addition to any custom log callbacks. You can get log to a file form logcat as shown below: adb logcat > "C:\logmsg\logfile.txt"

More examples about adb cmds: https://developer.android.com/tools/debugging/debugging-log.html#startingLogcat

Telemetry

ADAL provides a built-in callback mechanism to supply consuming applications with event data (telemetry) generated during requests. The event data is sanitized of Personally Identifiable Information (PII) and Organizationally Identifiable Information (OII) and is designed to give consumers of the library insight into the performance, reliability, and usage of ADAL.

For detailed guidance on the usage, configuration, and schema of ADAL telemetry, see Wiki:Telemetry

Network Traces

You can use various tools to capture the HTTP traffic that ADAL generates. This is most useful if you are familiar with the OAuth protocol or if you need to provide diagnostic information to Microsoft or other support channels.

Fiddler is the easiest HTTP tracing tool. Use the following links to setup it up to correctly record ADAL network traffic. In order to be useful it is necessary to configure fiddler, or any other tool such as Charles, to record unencrypted SSL traffic. NOTE: Traces generated in this way may contain highly privileged information such as access tokens, usernames and passwords. If you are using production accounts, do not share these traces with 3rd parties. If you need to supply a trace to someone in order to get support, reproduce the issue with a temporary account with usernames and passwords that you don't mind sharing.

• Setting Up Fiddler For Android
• Configure Fiddler Rules For ADAL

Dialog mode

acquireToken method without activity supports dialog prompt.

Encryption

Important! Providing custom secret keys to ADAL is deprecated. Consumers of ADAL are advised to avoid setting their own keys. As no API is currently provided to transition off of custom secret key usage, this API remains available for use only in backwards compatibility scenarios.

ADAL encrypts the tokens and store in SharedPreferences by default. You can look at the StorageHelper class to see the details. ADAL uses AndroidKeyStore for 4.3(API18) and above for secure storage of private keys. If you want to use ADAL for lower SDK versions, you need to provide secret key at AuthenticationSettings.INSTANCE.setSecretKey

Following example is using the password based encryption key(which takes the specified password and salt). And then create the provider-independent secret key with the generated password based encryption key. ADAL requires the key to be 256 bits. You can use other key generation algorithm.

    SecretKeyFactory keyFactory = SecretKeyFactory
        .getInstance("PBEWithSHA256And256BitAES-CBC-BC");
    SecretKey generatedSecretKey = keyFactory.generateSecret(new PBEKeySpec(your_password,
        byte-code-for-your-salt, 100, 256));
    SecretKey secretKey = new SecretKeySpec(generatedSecretKey.getEncoded(), "AES");
    AuthenticationSettings.INSTANCE.setSecretKey(secretKey.getEncoded());

Oauth2 Bearer challenge

AuthenticationParameters class provides functionality to get the authorization_uri from Oauth2 bearer challange.

Session cookies in Webview

Android webview does not clear session cookies after app is closed. You can handle this with sample code below:

CookieSyncManager.createInstance(getApplicationContext());
CookieManager cookieManager = CookieManager.getInstance();
cookieManager.removeSessionCookie();
CookieSyncManager.getInstance().sync();

More about cookies: http://developer.android.com/reference/android/webkit/CookieSyncManager.html

Resource Overrides

The ADAL library includes English strings for the following two ProgressDialog messages.

Your application should overwrite them if localized strings are desired.

<string name="app_loading">Loading...</string>
<string name="broker_processing">Broker is processing</string>
<string name="http_auth_dialog_username">Username</string>
<string name="http_auth_dialog_password">Password</string>
<string name="http_auth_dialog_title">Sign In</string>
<string name="http_auth_dialog_login">Login</string>
<string name="http_auth_dialog_cancel">Cancel</string>

=======

NTLM dialog

ADAL version 1.1.0 supports NTLM dialog that is processed through onReceivedHttpAuthRequest event from WebViewClient. Dialog layout and strings can be customized.

License

Copyright (c) Microsoft Corporation. All rights reserved. This code is licensed under the MIT License.

We Value and Adhere to the Microsoft Open Source Code of Conduct

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.