Partager via

Tutoriel : Ajouter une inscription à une application mobile Android à l’aide de l’authentification native

  • Article

Ce tutoriel montre comment inscrire un utilisateur à l’aide d’un code secret à usage unique envoyé par e-mail ou d’un nom d’utilisateur (e-mail) et d’un mot de passe, et à collecter les attributs utilisateur dans votre application mobile Android à l’aide de l’authentification native.

Dans ce tutoriel, vous allez apprendre à :

  • Inscrivez un utilisateur à l’aide d’un code secret à usage unique envoyé par e-mail ou d’un nom d’utilisateur (e-mail) et d’un mot de passe.
  • Collecter les attributs utilisateur lors de l’inscription.
  • Gérer les erreurs d’inscription.

Prérequis

Inscrire un utilisateur

Pour inscrire un utilisateur à l’aide d’un code secret à usage unique envoyé par e-mail ou d’un nom d’utilisateur (e-mail) et d’un mot de passe, collectez l’adresse e-mail de l’utilisateur, puis envoyez-lui un e-mail contenant un code secret à usage unique. L’utilisateur entre un code secret à usage unique valide pour valider son nom d’utilisateur.

Pour inscrire un utilisateur, vous devez :

  1. Créer une interface utilisateur pour :

    • Collecter l’adresse e-mail de l’utilisateur. Ajouter une validation à vos entrées pour vérifier que l’utilisateur entre une adresse e-mail valide.
    • Collecter un mot de passe si vous vous inscrivez avec un nom d’utilisateur (e-mail) et un mot de passe.
    • Collecter auprès de l’utilisateur un code secret à usage unique envoyé par e-mail.
    • Collecter les attributs utilisateur, si besoin.
    • Renvoyer un code secret à usage unique (recommandé).
    • Démarrer le flux d’inscription.

  2. Dans votre application, ajoutez un bouton dont l’événement de sélection déclenche l’extrait de code suivant :

    CoroutineScope(Dispatchers.Main).launch {
    val actionResult = authClient.signUp(
        username = emailAddress
        //password = password, Pass 'password' param if you sign up with username (email) and password
    )
    if (actionResult is SignUpResult.CodeRequired) {
        val nextState = actionResult.nextState
        val submitCodeActionResult = nextState.submitCode(
            code = code
        )
        if (submitCodeActionResult is SignUpResult.Complete) {
            // Handle sign up success
        }
    }
}
    • Utilisez la méthode d’instance du kit SDK, signUp(username) pour démarrer le flux d’inscription.
      • Pour vous inscrire avec un nom d’utilisateur (adresse e-mail) et un mot de passe, transmettez votre paramètre de mot de passe à la fonction signUp , signUp(username, password).
    • Le paramètre de la méthode, username, correspond à l’adresse e-mail que vous collectez auprès de l’utilisateur.
    • Dans le scénario le plus courant, signUp(username) ou signUp(username, password) retourne un résultat, SignUpResult.CodeRequired, qui indique que le SDK s’attend à ce que l’application soumette le code secret à usage unique envoyé par e-mail à l’adresse e-mail de l’utilisateur.
    • L’objet SignUpResult.CodeRequired contient une référence au nouvel état, que nous pouvons récupérer via actionResult.nextState.
    • Le nouvel état nous donne accès à deux nouvelles méthodes :
      • submitCode() soumet le code secret à usage unique envoyé par e-mail que l’application collecte auprès de l’utilisateur.
      • resendCode() renvoie le code secret à usage unique envoyé par e-mail si l’utilisateur ne reçoit pas le code.
    • submitCode() renvoie SignUpResult.Complete, ce qui indique que le flux est terminé et que l’utilisateur est inscrit.
    • signUp(username) ou signUp(username, password) peut également retourner SignUpError pour indiquer qu’une erreur s’est produite.

Collecter les attributs utilisateur lors de l’inscription

Que vous inscriviez un utilisateur à l’aide d’un code secret à usage unique envoyé par e-mail ou à l’aide d’un nom d’utilisateur (e-mail) et d’un mot de passe, vous pouvez collecter les attributs utilisateur avant la création du compte de l’utilisateur :

  • La méthode signUp() accepte un paramètre attributes, comme signUp(username, attributes) :

        CoroutineScope(Dispatchers.Main).launch {
        val actionResult = authClient.signUp(
            username = emailAddress,
            attributes = userAttributes
            //password = password, Pass 'password' param if you sign up with username (email) and password
        )
        //...
    }

  • Le SDK Android fournit une classe utilitaire UserAttribute.Builder que vous utilisez pour créer des attributs utilisateur. Par exemple, pour envoyer les attributs utilisateur ville et pays, utilisez l’extrait de code suivant pour générer la variable userAttributes :

         val userAttributes = UserAttributes.Builder ()
    .country(country) 
    .city(city) 
    .build()

    Les noms de méthodes de la classe UserAttribute.Builder sont identiques aux noms programmables des attributs utilisateur qu’ils génèrent. Découvrez plus en détail le Générateur d’attributs du kit Android SDK.

  • La méthode signUp(username, attributes) ou signUp(username, attributes, password) peut également retourner SignUpResult.AttributesRequired pour indiquer que l’application doit soumettre un ou plusieurs attributs obligatoires avant que Microsoft Entra ne crée un compte. Ces attributs sont configurés par l’administrateur comme étant obligatoires dans le centre d’administration Microsoft Entra. Microsoft Entra ne demande pas explicitement d’attributs utilisateur facultatifs.

  • Le résultat de SignUpResult.AttributesRequired contient un paramètre requiredAttributes. requiredAttributes est une liste d’objets RequiredUserAttribute, qui contient des détails sur les attributs utilisateur que l’application doit soumettre. Pour gérer actionResult is SignUpResult.AttributesRequired, utilisez l’extrait de code suivant :

    val actionResult = authClient.signUp(
    username = email,
    attributes = attributes
    //password = password, Pass 'password' param if you sign up with username (email) and password
)
if (actionResult is SignUpResult.AttributesRequired) {
        val requiredAttributes = actionResult.requiredAttributes 
        // Handle "attributes required" result 
        val nextState = actionResult.nextState
        nextState.submitAttributes(
            attributes = moreAttributes
        )
}

Gérer les erreurs d’inscription

Pendant l’inscription, toutes les actions n’aboutissent pas. Par exemple, l’utilisateur peut tenter de s’inscrire avec une adresse e-mail déjà utilisée, ou soumettre un code secret à usage unique envoyé par e-mail non valide.

Gérer les erreurs au début du processus d’inscription

Pour gérer les erreurs de la méthode signUp(), utilisez l’extrait de code suivant :

val actionResult = authClient.signUp(
    username = email
)
if (actionResult is SignUpResult.CodeRequired) {
    // Next step: submit code
} else if (actionResult is SignUpError) {
     when {
         actionResult.isUserAlreadyExists() -> {
             // Handle "user already exists" error
         }
         else -> {
             // Handle other errors
         }
     }
}

  • signUp(username, attributes) ou signUp(username, password, attributes) peut retourner SignUpError.

  • SignUpError indique un résultat d’action infructueux, retourné par signUp(), et n’inclut pas de référence au nouvel état.

  • Si actionResult is SignUpError, Android SDK MSAL fournit des méthodes utilitaires pour vous permettre d’analyser les erreurs spécifiques plus en avant :

    • La méthode isUserAlreadyExists() vérifie si le nom d’utilisateur a déjà été utilisé pour créer un compte.
    • isInvalidAttributes() indique que la validation d’un ou de plusieurs attributs soumis par l’application a échoué, par exemple à cause d’un mauvais type de données. Elle contient un paramètre invalidAttributes, qui représente la liste de tous les attributs soumis par les applications, mais dont la validation a échoué.
    • isInvalidPassword() indique que le mot de passe n’est pas valide, par exemple lorsque le mot de passe ne répond pas au niveau de complexité demandé pour les mots de passe. En savoir plus sur les stratégies de mot de passe de Microsoft Entra
    • isInvalidUsername() indique que le nom d’utilisateur n’est pas valide, par exemple lorsque l’e-mail de l’utilisateur n’est pas valide.
    • isBrowserRequired() vérifie si un navigateur (secours web) est nécessaire pour effectuer le flux d’authentification. Ce scénario se produit quand l’authentification native n’est pas suffisante pour effectuer le flux d’authentification. Par exemple, un administrateur configure l’adresse e-mail et le mot de passe en tant que méthode d’authentification, mais l’application ne parvient pas à envoyer password en tant que type de demande, ou ne le prend tout simplement pas en charge. Suivez les étapes décrites dans Prise en charge du secours web dans l’application Android pour gérer ce scénario quand il se produit.
    • isAuthNotSupported() vérifie si l’application envoie un type de demande que Microsoft Entra ne prend pas en charge, c’est-à-dire une valeur de type de demande autre que oob ou password. Découvrez plus en détail les types de demandes.

    Informez l’utilisateur que l’e-mail est déjà utilisé ou que des attributs ne sont pas valides en utilisant un message convivial dans l’interface utilisateur de l’application.

  • Pour gérer l’erreur liée aux attributs non valides, utilisez l’extrait de code suivant :

    val actionResult = authClient.signUp(
    username = email,
    attributes = attributes
    //password = password, Pass 'password' param if you sign up with username (email) and password
)
if (actionResult is SignUpError && actionResult.isInvalidAttributes()) {
    val invalidAttributes = actionResult.invalidAttributes
    // Handle "invalid attributes" error, this time submit valid attributes
    authClient.signUp(
        username = emailAddress,
        attributes = resubmittedAttributes
        //password = password, Pass 'password' param if you sign up with username (email) and password
    )
} 
//...

Gérer l’erreur au moment où un code secret à usage unique envoyé par e-mail est soumis

Pour gérer les erreurs de la méthode submitCode(), utilisez l’extrait de code suivant :

val submitCodeActionResult = nextState.submitCode(
    code = code
)
if (submitCodeActionResult is SignUpResult.Complete) {
    // Sign up flow complete, handle success state.
} else if (submitCodeActionResult is SubmitCodeError) {
    // Handle errors under SubmitCodeError
     when {
         submitCodeActionResult.isInvalidCode() -> {
             // Handle "code invalid" error
         }
         else -> {
             // Handle other errors
         }
     }
}

  • submitCode() peut renvoyer SubmitCodeError.

  • Utilisez la méthode isInvalidCode() pour vérifier l’erreur spécifique, par exemple si le code soumis n’est pas valide. Dans ce cas, la référence à l’état précédent doit être utilisée pour effectuer de nouveau l’action.

  • Pour récupérer un nouveau code secret à usage unique envoyé par e-mail, utilisez l’extrait de code suivant :

    val submitCodeActionResult = nextState.submitCode(
    code = code
)
if (submitCodeActionResult is SubmitCodeError && submitCodeActionResult.isInvalidCode()) {
    // Inform the user that the submitted code was incorrect or invalid and ask for a new code to be supplied
    val newCode = retrieveNewCode()
    nextState.submitCode(
        code = newCode
    )
}

Veillez à inclure les instructions import. Android Studio doit inclure automatiquement les instructions import.

Vous avez effectué toutes les étapes nécessaires pour inscrire correctement un utilisateur dans votre application. Créez et exécutez votre application. Si tout est bon, vous devriez pouvoir inscrire l’utilisateur à l’aide d’un code secret à usage unique envoyé par e-mail ou à l’aide d’un e-mail et d’un mot de passe.

Facultatif : Se connecter après un flux d’inscription

Après un flux d’inscription réussi, vous pouvez connecter un utilisateur sans lancer de flux de connexion. Découvrez davantage d’informations dans l’article Tutoriel : Connecter l’utilisateur après l’inscription dans Android.

Étapes suivantes

Tutoriel : ajouter la connexion et la déconnexion avec la fonctionnalité d’envoi d’un code secret à usage unique par e-mail dans une application Android.