Guardian SDK for Android

Guardian is Auth0's multi-factor authentication (MFA) service that provides a simple, safe way for you to implement MFA.

Auth0 is an authentication broker that supports social identity providers as well as enterprise identity providers such as Active Directory, LDAP, Google Apps and Salesforce.

This SDK allows you to integrate Auth0's Guardian multi-factor service in your own app, transforming it in the second factor itself. Your users will get all the benefits of our frictionless multi-factor authentication from your app.

Requirements

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

Before getting started

To use this SDK you have to configure your tenant's Guardian service with your own push notification credentials, otherwise you would not receive any push notifications. Please read the docs about how to accomplish that.

Install

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

implementation 'com.auth0.android:guardian:0.8.0'

Usage

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://<AUTH0_TENANT_DOMAIN>/appliance-mfa");

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

alternatively you can use the custom domain if you configured one

Uri url = Uri.parse("https://<CUSTOM_DOMAIN>/appliance-mfa");

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

That's all you need to setup your own instance of Guardian

Enroll

An enrollment is a link between the second factor and an Auth0 account. When an account is enrolled you'll need the enrollment data to provide the second factor required to verify the identity. You can create an enrolment using the guardian instance you just created.

First you'll need to obtain the enrollment info by scanning a Guardian QR code or obtaining an enrollment ticket by email for example.

Next you'll have to create a new pair of RSA keys for the new enrollment. 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 should use at least 2048 bit keys
KeyPair keyPair = keyPairGenerator.generateKeyPair();

Then you just use the enroll method like this:

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

String enrollmentUriFromQr = ...; // the data from a Guardian QR code or enrollment ticket

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

or you can also 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 fcmToken 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 FCM token is the token for Firebase Cloud Messaging push notification service. In case your app is not yet using FCM or you're not familiar with it, you should check their docs.

Unenroll

If you want to delete an enrollment -for example if you want to disable MFA- you can make the following request:

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

Allow a login request

Once you have the enrollment in place, you will receive a FCM push notification every time the user has to validate his identity with MFA.

Guardian provides a method to parse the Map<String, String> data inside the RemoteMessage received from FCM and return a Notification instance ready to be used.

// at your FCM listener you receive a RemoteMessage
@Override
public void onMessageReceived(RemoteMessage message) {
    Notification notification = Guardian.parseNotification(message.getData());
    if (notification != null) {
        handleGuardianNotification(notification);
        return;
    }

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

If the RemoteMessage you receive is not from a Guardian notification this method will return null, so you should always check before using it.

Once you have the notification instance, you can easily allow the authentication request by using the allow method. You'll also need the enrollment that you obtained previously. In case you have more than one enrollment, you'll have to find the one that has the same id as the notification (you can get the enrollment id with getEnrollmentId().

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

Reject a login request

To deny an authentication request just call reject instead. You can also send a reject reason if you want. The reject reason will be available in the guardian logs.

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

What is Auth0?

Auth0 helps you to:

Add authentication with multiple authentication sources, either social like Google, Facebook, Microsoft Account, LinkedIn, GitHub, Twitter, Box, Salesforce, among others, or enterprise identity systems like Windows Azure AD, Google Apps, Active Directory, ADFS or any SAML Identity Provider.
Add authentication through more traditional username/password databases.
Add support for linking different user accounts with the same user.
Support for generating signed Json Web Tokens to call your APIs and flow the user identity securely.
Analytics of how, when and where users are logging in.
Pull data from other sources and add it to the user profile, through JavaScript rules.

Create a free account in Auth0

Go to Auth0 and click Sign Up.
Use Google, GitHub or Microsoft Account to login.

Issue Reporting

If you have found a bug or if you have a feature request, please report them at this repository issues section. Please do not report security vulnerabilities on the public GitHub issue tracker. The Responsible Disclosure Program details the procedure for disclosing security issues.

Author

Auth0

License

This project is licensed under the MIT license. See the LICENSE file for more info.

auth0 / Guardian.Android

readme