Lock.Android : Premiers pas

Découvrez Lock pour Android, un widget qui offre une expérience de connexion et d’inscription fluide pour vos applications Android natives.

Lock pour Android peut s’intégrer à vos applications Android natives pour offrir à vos utilisateurs une façon élégante de se connecter et de s’inscrire dans votre application. Il prend en charge les fournisseurs d’identité sociaux comme Facebook, Google ou X, ainsi que des fournisseurs d’identité d’entreprise comme Active Directory.

Consultez le dépôt Lock.Android sur GitHub.

Exigences

Pour utiliser l’UI de Lock ou votre propre UI au moyen de la bibliothèque Auth0.Android, le niveau d’API Android minimal requis est 21+ et la version de Java doit être 8 ou plus récente. Vous aurez aussi besoin d’une application Auth0 de type “Native”.

Voici ce qu’il vous faut dans build.gradle pour cibler le bytecode Java 8 pour les plugins Android et Kotlin, respectivement.

android {
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }

    kotlinOptions {
        jvmTarget = '1.8'
    }
}

Installation

Lock est disponible sur Maven Central. Pour commencer à utiliser Lock, ajoutez ces lignes à votre fichier de dépendances build.gradle :

implementation 'com.auth0.android:lock:3.+'

Vous pouvez consulter la version la plus récente dans le README du dépôt ou sur Maven.

Après avoir ajouté votre dépendance Gradle, n’oubliez pas de synchroniser votre projet avec les fichiers Gradle.

Paramètres du Dashboard

Vous devez définir quelques paramètres dans votre Auth0 Dashboard avant de commencer.

URL de rappel

Allez dans votre Auth0 Dashboard, puis ouvrez les paramètres de l’application. Ajoutez l’URL suivante aux Allowed Callback URLs de l’application :

https://{yourDomain}/android/{yourAppPackageName}/callback

Remplacez {yourAppPackageName} par le véritable nom de package de votre application, que vous trouverez dans votre fichier app/build.gradle sous la valeur applicationId.

Keystores et hachages de clés

Les applications Android doivent être signées avant de pouvoir être installées sur un appareil. Pour ce faire, l’IDE Android Studio génère, à sa première exécution, un « Android Debug Keystore » par défaut qu’il utilisera pour signer les versions de développement. Ce Keystore sera probablement différent de celui de votre version de production, puisqu’il servira à vous identifier en tant que développeur.

Lors de l’utilisation de la fonctionnalité Web Authentication (c.-à-d. les connexions sociales), Lock sera configuré par défaut pour tenter d’utiliser Android App Links. Cela nécessite un paramètre supplémentaire dans le Dashboard de l’application Auth0. Utilisez notre guide Android Keystores and Key Hashes pour terminer cette étape.

Implémentation de Lock (Social, Database, Enterprise)

Les instructions suivantes portent sur l’implémentation de Classic Lock pour Android. Si vous cherchez plutôt à implémenter Passwordless Lock pour Android, consultez Lock.Android: Passwordless.

Configurer le SDK

Dans votre fichier app/build.gradle, ajoutez les espaces réservés du manifeste pour les propriétés Auth0 Domain et Auth0 Scheme, qui seront utilisées en interne par la bibliothèque pour enregistrer un intent-filter capturant le résultat de l’authentification.

plugins {
    id "com.android.application"
    id "kotlin-android"
}

android {
    compileSdkVersion 30
    defaultConfig {
        applicationId "com.auth0.samples"
        minSdkVersion 21
        targetSdkVersion 30
        // ...

        // ---> Ajouter la ligne suivante
        manifestPlaceholders = [auth0Domain: "@string/com_auth0_domain", auth0Scheme: "https"]
        // <---
    }
}

Il est recommandé d’ajouter ces valeurs au fichier strings.xml sous forme de ressources de chaînes auxquelles le code pourra faire référence plus tard. Ce guide suivra cette pratique.

Utilisation du SDK

Dans l’activité où vous prévoyez appeler Lock, créez une instance de Auth0 avec les renseignements de votre application. La façon la plus simple de la créer consiste à lui passer un Context Android. Cela utilisera les valeurs définies précédemment dans le fichier strings.xml. Pour que cela fonctionne, les ressources de chaîne doivent être définies avec les mêmes clés que celles indiquées ci-dessus.

val account = Auth0(context)

Déclarez une mise en œuvre de AuthenticationCallback qui gérera les événements d’authentification des utilisateurs. L’objet Credentials renvoyé en cas d’authentification réussie contiendra les jetons que votre application ou votre API utilisera ensuite. Consultez Tokens pour plus de détails.

private val callback = object : AuthenticationCallback() {
    override fun onAuthentication(credentials: Credentials) {
        // Authentifié
    }

    override fun onError(error: AuthenticationException) {
        // Une exception s'est produite
    }
}

Préparez une nouvelle instance de Lock à l’aide de la classe Builder pour la configurer. Fournissez les détails du compte et l’implémentation du callback déclarée ci-dessus. Des valeurs comme audience, le scope et les connexions disponibles peuvent être configurés ici.

Une fois que c’est fait, créez l’instance Lock. Cette instance est conçue pour être réutilisée et doit être libérée lorsqu’elle n’est plus nécessaire. La méthode onDestroy de votre activité est un bon endroit pour le faire.

// Cette activité affichera Lock
class MyActivity : AppCompatActivity() {

    private lateinit var lock: Lock

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        val account = Auth0(this)
        // Instancier Lock une seule fois
        lock = Lock.newBuilder(account, callback)
            // Personnaliser Lock
            .build(this)
    }

    override fun onDestroy() {
        super.onDestroy()
        // Important ! Libérer Lock et ses ressources
        lock.onDestroy(this)
    }

    private val callback = object : AuthenticationCallback() {
        override fun onAuthentication(credentials: Credentials) {
            // Authentifié
        }

        override fun onError(error: AuthenticationException) {
            // Une exception s'est produite
        }
    }
}

Enfin, lancez le widget Lock à partir de votre activité.

startActivity(lock.newIntent(this))

Et voilà ! Lock s’occupera du reste pour vous.

Android App Links - schéma personnalisé

Le schéma d’URI de rappel utilisé dans cet article, et par défaut par Lock, est https. Cela fonctionne mieux sur Android Marshmallow (API 23) et les versions ultérieures si vous utilisez Android App Links. Toutefois, sur les versions antérieures d’Android, la boîte de dialogue du sélecteur d’intention peut s’afficher et inviter l’utilisateur à choisir soit votre application, soit le navigateur pour traiter l’intention. C’est ce qu’on appelle la « boîte de dialogue de désambiguïsation ». Vous pouvez modifier ce comportement en utilisant un schéma personnalisé unique afin que le système d’exploitation ouvre directement le lien dans votre application.

1. Mettez à jour la valeur de l’espace réservé auth0Scheme dans le fichier app/build.gradle, ou directement dans la définition d’Intent Filter du fichier AndroidManifest.xml, en remplaçant le schéma actuel par le nouveau.
2. Mettez à jour les « Allowed Callback URLs » dans les paramètres de votre Application du Auth0 Dashboard afin qu’elles correspondent à des URL qui commencent par le nouveau schéma.
3. Appelez withScheme() lors de la configuration de Lock avec le builder, en lui passant le schéma que vous souhaitez utiliser.

La valeur du schéma doit être entièrement en minuscules. Un message d’avertissement sera consigné dans le log si ce n’est pas le cas, et l’authentification ne se terminera jamais.

Configuration de Lock

Pour consulter la liste complète des options de configuration de Lock, consultez Lock.Android : Configuration.

Messages d’erreur

Si votre callback reçoit une AuthenticationException, vous pouvez consulter le code source pour voir comment identifier chaque scénario d’erreur.

En savoir plus

• Lock.Android : personnalisation du thème
• Lock.Android : Configuration
• Lock.Android : champs personnalisés lors de l’inscription
• Internationalisation de Lock.Android
• Logout