Guardian for Android SDK

The Guardian for Android SDK helps you create Android apps with Guardian functionality, providing secure access to multi-factor authentication (MFA) with push notifications. With this toolkit, you can build your own customized version of the Guardian application that matches the look and feel of your organization. To learn more, read Getting Started with Google Cloud Messaging for Android on https://docs.aws.amazon.com..

Requirements

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

Install Guardian Android SDK

Guardian is available both in Maven Central and JCenter.

  1. To use Guardian, add these lines to your build.gradle dependencies file: implementation 'com.auth0.android:guardian:0.4.0' You can check for the latest version on the repository Releases tab, in Maven, or in JCenter.

  2. After adding your Gradle dependency, make sure to sync your project with Gradle file.

Enable Guardian push notifications

  1. Go to Dashboard > Security > Multifactor Aut > Push via Auth0 Guardian.

  2. Toggle the switch at the top to enable it.

Auth0 Dashboard Security Multifactor Auth Push via Auth0 Guardian Use a Custom App

Configure SNS for native apps

For your native app to receive push notifications from Guardian, you will need to override the default SNS settings. To learn more, read Configure Push Notifications for MFA.

Use 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 enrollment 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, "fcmToken", "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
        }
    });


You must provide the following data:

Variable Description
deviceName Name for the enrollment displayed to the user when the second factor is required.
fcmToken Token for Firebase Cloud Messaging (FCM) push notification service. See Sample Register for details.

Unenroll

To disable MFA, you can delete the enrollment:

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


Allow login requests

Once you have the enrollment in place, you'll receive a FCM push notification every time the user needs multi-factor authentication.

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 the FCM listener you receive a RemoteMessage
@Override
public void onMessageReceived(RemoteMessage message) {
    Notification notification = Guardian.parseNotification(message.getData());
    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 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 login requests

To deny an authentication request, use reject instead. You can also add an optional 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<> ...)




Learn more