Guardian for Android

The Guardian for Android Software Development Kit allows developers to create Android apps with Guardian functionality, providing easy and secure access to multifactor authentication with push notifications. For example, this toolkit gives you the power to build a 'white label' version of the Guardian application for your users, using your own look-and-feel.

More information can be found on Guardian here. For general multifactor discussion, read more here.

Get started using Guardian for Android below, or, if you're looking for a specific document, try the listing of additional documents related to Guardian for Android.

Requirements

Android API level 15+ is required in order to use the Guardian Android SDK.

Installation

Guardian is available both in Maven Central and JCenter. To start using Guardian add these lines to your build.gradle dependencies file:

compile 'com.auth0.android:guardian-sdk:0.1.0'

You can check for the latest version on the repository Releases tab, in Maven, or in JCenter.

After adding your Gradle dependency, make sure to remember to sync your project with Gradle files.

Dashboard Settings

To enable Guardian Push Notifications for your users, go to the Multifactor Auth section of the dashboard. Then toggle the Push Notification slider to enable it.

SNS configuration

For your native application to receive push notifications from Guardian, you will need to override the default SNS settings. Follow the instructions here.

Using the SDK

Guardian is the core of the SDK. You'll need to create an instance of this class for your specific tenant/url.

Uri url = Uri.parse("https://tenant.guardian.auth0.com/");

Guardian guardian = new Guardian.Builder()
        .url(url)
        .build();

or

String domain = "tenant.guardian.auth0.com";

Guardian guardian = new Guardian.Builder()
        .domain(domain)
        .build();

Enroll

The link between the second factor (an instance of your app on a device) and an Auth0 account is referred to as an enrollment.

You can create an enrollment using the Guardian.enroll function, but first you'll have to create a new pair of RSA keys for it. The private key will be used to sign the requests to allow or reject a login. The public key will be sent during the enroll process so the server can later verify the request's signature.

KeyPairGenerator keyPairGenerator = KeyPairGenerator.getInstance("RSA");
keyPairGenerator.initialize(2048); // you MUST use at least 2048 bit keys
KeyPair keyPair = keyPairGenerator.generateKeyPair();

Next, obtain the enrollment information by scanning the Guardian QR code, and use it to enroll the account:

Uri enrollmentUriFromQr = ...; // the URI obtained from a Guardian QR code

CurrentDevice device = new CurrentDevice(context, "gcmToken", "deviceName");

Enrollment enrollment = guardian
        .enroll(enrollmentUriFromQr, device, keyPair)
        .execute();

Alternatively, you can execute the request in a background thread:

guardian
        .enroll(enrollmentUriFromQr, device, keyPair)
        .start(new Callback<Enrollment> {
            @Override
            void onSuccess(Enrollment enrollment) {
               // we have the enrollment data
            }

            @Override
            void onFailure(Throwable exception) {
               // something failed
            }
        });

The deviceName and gcmToken are data that you must provide:

  • The deviceName is the name that you want for the enrollment. It will be displayed to the user when the second factor is required.
  • The gcmToken is the token for Google's GCM push notification service. See the docs for more information about the GCM token.

Unenroll

To disable multifactor authentication you can delete the enrollment:

guardian
        .delete(enrollment)
        .execute(); // or start(new Callback<> ...)

Allow a login request

Once you have the enrollment in place, you will receive a GCM push notification every time the user needs multifactor authentication.

Guardian provides a method to parse the Bundle received from GCM and return a Notification instance ready to be used.

// at the GCM listener you receive a Bundle
@Override
public void onMessageReceived(String from, Bundle data) {
    Notification notification = Guardian.parseNotification(data);
    if (notification != null) {
        // you received a Guardian notification, handle it
        handleGuardianNotification(notification);
        return;
    }

    /* handle other push notifications you might be using ... */
}

Once you have the notification instance, you can easily approve the authentication request by using the allow method. You'll also need the enrollment that you obtained previously. If there are multiple enrollments, be sure to use the one that has the same id as the notification (the enrollmentId property).

guardian
        .allow(notification, enrollment)
        .execute(); // or start(new Callback<> ...)

Reject a login request

To deny an authentication request, use reject instead. You can optionally add a reason for the rejection, which will be available in the guardian logs.

guardian
        .reject(notification, enrollment) // or reject(notification, enrollment, reason)
        .execute(); // or start(new Callback<> ...)

Additional Documents