SDK Guardian pour Android

Décrit comment installer, configurer et utiliser les options du SDK Auth0 Guardian pour Android.

Le SDK Guardian pour Android vous aide à créer des applications Android dotées des fonctionnalités de Guardian, en offrant un accès sécurisé à l’authentification multifacteur (MFA) grâce aux notifications push. Avec cet ensemble d’outils, vous pouvez créer votre propre version personnalisée de l’application Guardian, adaptée à l’apparence et à l’expérience de votre organisation. Pour en savoir plus, consultez Configurer les notifications push pour la MFA.

Le niveau d’API Android 15 ou supérieur est requis pour utiliser le SDK Guardian pour Android.

​

Installer le SDK Android Guardian

Guardian est disponible dans Maven Central et JCenter.

1. Pour utiliser Guardian, ajoutez les lignes suivantes au fichier de dépendances build.gradle : implementation 'com.auth0.android:guardian:0.4.0' Vous pouvez consulter la version la plus récente dans l’onglet Releases du dépôt, dans Maven ou dans JCenter.
2. Après avoir ajouté la dépendance Gradle, assurez-vous de synchroniser votre projet avec le fichier Gradle.

​

Activer les notifications push de Guardian

1. Accédez à Dashboard > Security > Multifactor Auth > Push via Auth0 Guardian.
2. Activez le bouton bascule en haut de la page.

3. Configurez les notifications push.

​

Utiliser le SDK

Guardian est au cœur du SDK. Vous devrez créer une instance de cette classe pour l’URL propre à votre locataire.

Uri url = Uri.parse("https://<tenant>.<region>.auth0.com");

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

ou

String domain = "<tenant>.<region>.auth0.com";

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

​

Inscrire

Le lien entre le second facteur (une instance de votre application sur un appareil) et un compte Auth0 correspond à une inscription.

Vous pouvez créer une inscription à l’aide de la fonction Guardian.enroll, mais vous devez d’abord générer une nouvelle paire de clés RSA. La clé privée servira à signer les requêtes permettant d’autoriser ou de refuser une connexion. La clé publique sera envoyée pendant le processus d’inscription afin que le serveur puisse ensuite vérifier la signature de la requête.

KeyPairGenerator keyPairGenerator = KeyPairGenerator.getInstance("RSA");
keyPairGenerator.initialize(2048); // vous DEVEZ utiliser des clés d'au moins 2048 bits
KeyPair keyPair = keyPairGenerator.generateKeyPair();

Ensuite, obtenez les informations d’inscription en numérisant le code QR Guardian, puis utilisez-les pour inscrire le compte :

Uri enrollmentUriFromQr = ...; // l'URI obtenu à partir d'un code QR Guardian

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

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

Vous pouvez également exécuter la requête dans un thread en arrière-plan :

guardian
    .enroll(enrollmentUriFromQr, device, keyPair)
    .start(new Callback<Enrollment> {
        @Override
        void onSuccess(Enrollment enrollment) {
            // nous avons les données d'inscription
        }

        @Override
        void onFailure(Throwable exception) {
            // quelque chose a échoué
        }
    });

Vous devez fournir les données suivantes :

Variable	Description
deviceName	Nom associé à l’inscription, affiché à l’utilisateur lorsque le deuxième facteur est requis.
fcmToken	Jeton du service de notifications push Firebase Cloud Messaging (FCM). Consultez Sample Register pour en savoir plus.

​

Désinscrire

Pour désactiver le MFA, vous pouvez supprimer l’inscription :

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

​

Autoriser les demandes de connexion

Une fois l’inscription en place, vous recevrez une notification push FCM chaque fois que l’utilisateur aura besoin d’une authentification multifacteur.

Guardian fournit une méthode pour analyser les données Map<String, String> contenues dans le RemoteMessage reçu de FCM et renvoyer une instance Notification prête à l’emploi.

// au listener FCM vous recevez un RemoteMessage
@Override
public void onMessageReceived(RemoteMessage message) {
    Notification notification = Guardian.parseNotification(message.getData());
    if (notification != null) {
        // vous avez reçu une notification Guardian, traitez-la
        handleGuardianNotification(notification);
        return;
    }

    /* gérez les autres notifications push que vous pourriez utiliser ... */
}

Une fois que vous avez l’instance de la notification, vous pouvez utiliser la méthode allow pour approuver la demande d’authentification. Vous aurez aussi besoin de l’inscription obtenue précédemment. S’il y a plusieurs inscriptions, assurez-vous d’utiliser celle dont le id correspond à celui de la notification (propriété enrollmentId).

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

​

Rejeter les demandes de connexion

Pour refuser une requête d’authentification, utilisez plutôt reject. Vous pouvez aussi ajouter un motif facultatif de refus, qui sera accessible dans les journaux Guardian.

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

​

Configurer l’inscription OTP sur mobile seulement

Vous pouvez activer les mots de passe à usage unique (OTP) comme facteur MFA à l’aide de Auth0 Dashboard ou de Management API. Cette option ne nécessite pas de code QR et permet aux utilisateurs de s’inscrire manuellement.

Pour inviter un utilisateur à s’inscrire, accédez à Auth0 Dashboard > User Management > Users et sélectionnez un utilisateur. Accédez ensuite à son onglet Details, puis utilisez la section Multi-Factor Authentication pour envoyer une invitation à l’inscription.

​

Connecter une ressource

Vous pouvez connecter une ressource à l’aide de l’Auth0 Dashboard ou du SDK Guardian.

Utiliser Auth0 Dashboard

1. Accédez à l’invite de connexion d’Auth0 et copiez le code fourni, ou une clé semblable encodée en base32 obtenue d’une autre source.

   

2. Après avoir obtenu votre code, ajoutez-le au SDK Guardian :

Java

public String copiedCode = "{copiedCode}";

Kotlin

val copiedCode: String = "{copiedCode}"

Utilisez le SDK Guardian

Ajoutez d’abord la classe LoginCodeGenerator à votre projet. Ensuite, utilisez getCode (String copiedCode) to pour générer un code à usage unique dans votre application.

Java

public class LoginCodeGenerator {

   private static final int TOTP_LENGTH = 6;

   private static final int TOTP_DURATION = 30;

   private static final String TOTP_ALGORITHM = "SHA1";

   public String getCode(String copedCode) {

       byte[] key = new byte[0];

       try {

           key = Base32.decode(copedCode);

       } catch (Base32.DecodingException ex) {

//            gérer l'exception

       }

       TOTP totp = new TOTP(TOTP_ALGORITHM, key, TOTP_LENGTH, TOTP_DURATION);

       return totp.generate();

   }

}

Kotlin

class LoginCodeGenerator {

   fun getCode(copiedCode: String): String {

       var key: ByteArray? = ByteArray(0)

       try {

           key = Base32.decode(copiedCode)

       } catch (ex: Base32.DecodingException) {

//            gérer l'exception

       }

       val totp = TOTP(TOTP_ALGORITHM, key, TOTP_LENGTH, TOTP_DURATION)

       return totp.generate()

   }

   companion object {

       private const val TOTP_LENGTH = 6

       private const val TOTP_DURATION = 30

       private const val TOTP_ALGORITHM = "SHA1"

   }

}

​

Saisir le code à usage unique

Entrez le code à usage unique généré par getCode() dans l’invite de connexion Auth0.

Après avoir sélectionné Continuer, un message s’affiche indiquant que votre application a été ajoutée comme facteur d’authentification pour le compte utilisateur.

​

Connectez-vous avec votre application

Une fois le facteur inscrit, l’utilisateur peut se connecter à l’aide de votre application. Choisissez d’abord l’application Guardian comme méthode d’authentification.

Pour générer le code à usage unique, appelez getCode(copedCode: String) avec le code que vous avez copié depuis l’invite de connexion Auth0.

Ensuite, saisissez le code à usage unique dans l’invite de connexion pour vérifier votre identité.

​

En savoir plus

• Configurer les notifications push pour MFA