Name: Guardian.Android
Owner: Auth0
Description: Android toolkit for Auth0 Guardian API
Created: 2016-06-10 19:31:49.0
Updated: 2016-11-23 19:48:49.0
Pushed: 2017-06-02 02:44:45.0
Homepage: https://auth0.com/guardian
Size: 382
Language: Java
GitHub Committers
| User | Most Recent Commit | # Commits |
|---|
Other Committers
| User | Most Recent Commit | # Commits |
|---|
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.
Android API level 15+ is required in order to use Guardian.
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.
GuardianSDK is available both in Maven Central and
JCenter.
To start using GuardianSDK add these lines to your build.gradle dependencies file:
ile 'com.auth0.android:guardian:0.3.0'
Guardian is the core of the SDK. You'll need to create an instance of this class for your specific
tenant/url.
url = Uri.parse("https://<TENANT>.guardian.auth0.com/");
dian guardian = new Guardian.Builder()
.url(url)
.build();
or
ng domain = "<TENANT>.guardian.auth0.com";
dian guardian = new Guardian.Builder()
.domain(domain)
.build();
That's all you need to setup your own instance of Guardian
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.
airGenerator keyPairGenerator = KeyPairGenerator.getInstance("RSA");
airGenerator.initialize(2048); // you should use at least 2048 bit keys
air keyPair = keyPairGenerator.generateKeyPair();
Then you just use the enroll method like this:
entDevice device = new CurrentDevice(context, "gcmToken", "deviceName");
ng enrollmentUriFromQr = ...; // the data from a Guardian QR code or enrollment ticket
llment enrollment = guardian
.enroll(enrollmentUriFromQr, device, keyPair)
.execute();
or you can also execute the request in a background thread
dian
.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 GCM token is the token for Google's GCM push notification service. In case your app is not yet using GCM or you're not familiar with it, you should check their docs.
If you want to delete an enrollment -for example if you want to disable MFA- you can make the following request:
dian
.delete(enrollment)
.execute(); // or start(new Callback<> ...) asynchronously
Once you have the enrollment in place, you will receive a GCM push notification every time the user has to validate his identity with MFA.
Guardian provides a method to parse the Bundle received from GCM and return a Notification
instance ready to be used.
t your GCM listener you receive a Bundle
rride
ic void onMessageReceived(String from, Bundle data) {
Notification notification = Guardian.parseNotification(data);
if (notification != null) {
handleGuardianNotification(notification);
return;
}
/* Handle other push notifications you might be using ... */
If the
Bundleyou receive is not 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().
dian
.allow(notification, enrollment)
.execute(); // or start(new Callback<> ...) asynchronously
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.
dian
.reject(notification, enrollment) // or reject(notification, enrollment, reason)
.execute(); // or start(new Callback<> ...) asynchronously
Auth0 helps you to:
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.
This project is licensed under the MIT license. See the LICENSE file for more info.