NXLAuth for Android

NXLAuth for Android is a client SDK for communicating with OAuth 2.0 and OpenID Connect providers. It strives to directly map the requests and responses of those specifications, while following the idiomatic style of the implementation language. In addition to mapping the raw protocol flows, convenience methods are available to assist with common tasks like performing an action with fresh tokens.

The library follows the best practices set out in OAuth 2.0 for Native Apps including using Custom Tabs for the auth request. For this reason, WebView is explicitly not supported due to usability and security reasons.

The library also supports the PKCE extension to OAuth which was created to secure authorization codes in public clients when custom URI scheme redirects are used. The library is friendly to other extensions (standard or otherwise) with the ability to handle additional parameters in all protocol requests and responses.

Download

Please contact your NXLAuth representative for latest SDK.

Requirements

Supported Android Versions

NXLAuth for Android supports Android API 16 (Jellybean) and above. Browsers which provide a custom tabs implementation are preferred by the library, but not required. Both Custom URI Schemes (all supported versions of Android) and App Links (Android M / API 23+) can be used with the library.

When a Custom Tabs implementation is provided by a browser on the device (for example by Chrome), Custom Tabs are used for authorization requests. Otherwise, the default browser is used as a fallback.

Demo App

Prerequisites

The project requires the Android SDK for API level 23 (Marshmallow) to build, though the produced binaries only require API level 16 (Jellybean) to be used.

Configure the Demo App

A demo app is contained in this repository. To try out the demo, just open the project in Android Studio and run 'app'.

Building from the Command line

NXLAuth for Android uses Gradle as its build system. In order to build the library and app binaries, run ./gradlew assemble. The library AAR files are output to library/build/outputs/aar, while the demo app is output to app/build/outputs/apk. In order to run the tests and code analysis, run ./gradlew check.

The build script attempts to guess the location of your SDK by looking at the values of $ANDROID_SDK_HOME and $ANDROID_HOME. If neither of these are defined or are not the SDK you wish to use, you must create a local.properties file in the project root. This file must define a property sdk.dir that points to your SDK root directory. For example:

sdk.dir=/path/to/android-sdk

Building from Android Studio

In AndroidStudio, File -> New -> Import project. Select the root folder (the one with the build.gradle file).

If you get an error like: Error:Could not find com.android.support:customtabs:23.2.0. then be sure you have installed the Android Support Library from the Android SDK Manager. Follow the Android Studio prompts to resolve the dependencies automatically.

Auth Flow Implementation

First, an NXLAuth instance must be created and initialized with client id supplied.

import my.com.nexlife.nxlauth.AuthManager;
import my.com.nexlife.nxlauth.SDKMessages;
import my.com.nexlife.nxlauth.SDKScopes;

...

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    ...
    AuthManager mAuthManager = new AuthManager.Builder("client-id", getApplicationContext())
        .setTag("LOGCAT TAG")
        .setScope(SDKScopes.OPEN_ID, SDKScopes.OFFLINE)
        .build();
    ...
  }

Getting access token

Given a successful authorization (build does not throw exception), a token request can be made and a token response can be retrieved via callback as per example below:

Via lambda expression

  private void getAccessToken() {
    /**
     * This callback needs to be implemented by tenant
     */
    this.mAuthManager.getAccessToken((accessToken, ex) -> {
      if (ex == null) {
        // Do stuffs with the access token retrieved
      } else {
        // Capture or log the exception
      }
    });
  }

Via implementation of interface AuthManager.NXLCallback

  private void getAccessToken() {
    /**
     * This callback needs to be implemented by tenant
     */
    this.mAuthManager.getAccessToken(new AuthManager.NXLCallback() {
      @Override
      public void onComplete(@NonNull String accessToken, @NonNull Exception ex) {
        if (ex == null) {
          // Do stuffs with the access token retrieved
        } else {
          // Capture or log the exception
        }
      }
    });
  }

Getting user info

Given a successful authorization (build does not throw exception), a user info request can be made and a response can be retrieved via callback as per example below:

Via lambda expression

  private void getUserInfo() {
    /**
     * This callback needs to be implemented by tenant
     */
    this.mAuthManager.getUserInfo((response, ex) -> {
      if (ex == null) {
        // Do stuffs with the user info retrieved
      } else {
        // Capture or log the exception
      }
    });
  }

Via implementation of interface AuthManager.NXLCallback

  private void getUserInfo() {
    /**
     * This callback needs to be implemented by tenant
     */
    this.mAuthManager.geUserInfo(new AuthManager.NXLCallback() {
      @Override
      public void onComplete(@NonNull String response, @NonNull Exception ex) {
        if (ex == null) {
          // Do stuffs with the access token retrieved
        } else {
          // Capture or log the exception
        }
      }
    });
  }

API Documentation

Browse the API documentation.