Guardian pour Android SDK

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

Le Guardian pour Android SDK vous aide à créer des applications Android intégrant les fonctionnalités de Guardian, en offrant un accès sécurisé à la authentification multifacteur (MFA) par notifications push. Grâce à cette boîte à outils, vous pouvez créer votre propre version personnalisée de l’application Guardian, à l’image 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 Guardian pour Android SDK.

​

Installer Guardian Android SDK

Guardian est disponible à la fois sur 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é votre dépendance Gradle, assurez-vous de synchroniser votre projet avec le fichier Gradle.

​

Activer les notifications push de Guardian

1. Accédez à Dashboard > Sécurité > Multifactor Auth > Push via Auth0 Guardian.
2. Utilisez le commutateur en haut pour l’activer.

3. Configurer 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 associée à votre tenant.

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 s’appelle un enrôlement.

Vous pouvez créer un enrôlement à l’aide de la fonction Guardian.enroll, mais vous devrez d’abord créer une nouvelle paire de clés RSA pour cet enrôlement. La clé privée servira à signer les requêtes afin d’autoriser ou de refuser une connexion. La clé publique sera envoyée pendant le processus d’enrôlement 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 données d’enrôlement 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 aussi exécuter la requête dans un fil d’exécution en arrière-plan :

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

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

Vous devez fournir les données suivantes :

Variable	Description
deviceName	Nom de l’enrôlement affiché à l’utilisateur lorsque le second 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 l’authentification multifacteur (MFA), vous pouvez supprimer l’enrôlement :

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

​

Autoriser les requêtes de connexion

Une fois l’enrôlement effectué, vous recevrez une notification push de 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, gérez-la
        handleGuardianNotification(notification);
        return;
    }

    /* gérez les autres notifications push que vous utilisez peut-être ... */
}

Une fois que vous avez l’instance de notification, vous pouvez utiliser la méthode allow pour approuver la demande d’authentification. Vous aurez aussi besoin de l’enrôlement que vous avez obtenue précédemment. S’il y a plusieurs enrôlements, assurez-vous d’utiliser celui qui a le même id que la notification (la propriété enrollmentId).

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

​

Rejeter les requêtes de connexion

Pour rejeter une requête d’authentification, utilisez plutôt reject. Vous pouvez aussi ajouter un motif de rejet facultatif, qui sera visible dans les logs Guardian.

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

​

Configurer l’enrôlement OTP sur mobile uniquement

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

Pour inviter un utilisateur à s’enrôler, accédez à Auth0 Dashboard > Gestion des utilisateurs > Utilisateurs et sélectionnez l’utilisateur en question. Ouvrez ensuite son onglet Détails, puis utilisez la section Authentification multifacteur pour envoyer une invitation à l’enrôlement.

​

Connecter une ressource

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

Utiliser Auth0 Dashboard

1. Accédez au prompt de connexion Auth0 et copiez le code fourni ou une clé semblable encodée en base32 provenant d’une autre source.

   

2. Une fois votre code obtenu, ajoutez-le au Guardian SDK :

Java

public String copiedCode = "{copiedCode}";

Kotlin

val copiedCode: String = "{copiedCode}"

Utiliser Guardian SDK

Commencez par ajouter 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"

   }

}

​

Entrez le code à usage unique

Entrez le mot de passe à usage unique généré par getCode() dans le prompt 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 votre utilisateur.

​

Connectez-vous avec votre application

Une fois le facteur inscrit, l’utilisateur peut se connecter avec votre application. Commencez par choisir l’application Guardian comme méthode d’authentification.

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

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

​

En savoir plus

• Configurer les notifications push pour la MFA