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

S’applique à : Locataires externes (en savoir plus)

Ce tutoriel montre comment inscrire un utilisateur à l’aide d’un code secret ou d’un nom d’utilisateur à usage unique (e-mail) et d’un mot de passe dans votre application mobile Android à l’aide de l’authentification native. Vous découvrez également comment collecter des attributs utilisateur lors de l’inscription, y compris un nom d’utilisateur (alias) et gérer les erreurs.

Dans ce tutoriel, vous allez :

Conditions préalables

• Suivez les étapes du Tutoriel : Préparer votre application Android pour l’authentification native.
• Si vous souhaitez collecter les attributs utilisateur lors de l’inscription, configurez les attributs utilisateur lorsque vous créez votre flux utilisateur d’inscription et de connexion.
• Pour collecter un nom d’utilisateur (alias) lors de l’inscription, activez l’attribut utilisateur intégré nom d’utilisateur dans le flux d’utilisateur d’inscription de votre locataire.

Inscrire un utilisateur

Pour inscrire un utilisateur à l’aide du code secret à usage unique ou du nom d’utilisateur (e-mail) et du mot de passe, vous collectez un e-mail auprès de l’utilisateur, puis envoyez un e-mail contenant un code secret à usage unique à l’utilisateur. 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 une 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.
   • Collectez un nom d’utilisateur (alias) si votre application prend en charge la connexion basée sur des alias.
   • 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 parameters = NativeAuthSignUpParameters(username = email)
        // Assign 'password' param if you sign in with username (email) and password
        // parameters.password = password
        val actionResult: SignUpResult = authClient.signUp(parameters)
   
        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(parameters) pour démarrer le flux d’inscription.
   • Pour vous inscrire à l’aide du nom d’utilisateur (adresse e-mail) et du mot de passe, créez une instance de NativeAuthSignUpParameters classe et attribuez votre nom d’utilisateur et votre mot de passe.
   • Le paramètre d’inscription, username, est l’adresse e-mail que vous collectez auprès de l’utilisateur.
   • Dans le scénario le plus courant, le signUp(parameters) renvoie un résultat, SignUpResult.CodeRequired, ce qui indique que le SDK attend de l’application qu’elle soumette le code d’accès à usage unique envoyé à l’adresse e-mail de l’utilisateur.
   • L’objet SignUpResult.CodeRequired contient une nouvelle référence d’état, que vous pouvez récupérer via actionResult.nextState.
   • Le nouvel état vous 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.
   • Le signUp(parameters) 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 :

• L’instance NativeAuthSignUpParameters accepte un paramètre attributes :

      CoroutineScope(Dispatchers.Main).launch {
          val parameters = NativeAuthSignUpParameters(username = email)
          // Assign 'password' param if you sign in with username (email) and password
          // parameters.password = password
          parameters.attributes = userAttributes
          val actionResult: SignUpResult = authClient.signUp(parameters)
          //...
      }
  

• 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(parameters) peut retourner SignUpResult.AttributesRequired pour indiquer que l’application doit envoyer un ou plusieurs attributs requis avant que Microsoft Entra 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 parameters = NativeAuthSignUpParameters(username = email)
  // Assign 'password' param if you sign in with username (email) and password
  // parameters.password = password
  parameters.attributes = userAttributes
  val actionResult: SignUpResult = authClient.signUp(parameters)
  
  if (actionResult is SignUpResult.AttributesRequired) {
          val requiredAttributes = actionResult.requiredAttributes 
          // Handle "attributes required" result 
          val nextState = actionResult.nextState
          nextState.submitAttributes(
              attributes = moreAttributes
          )
  }
  

Collecter un nom d’utilisateur (alias) lors de l’inscription

Le nom d’utilisateur (alias) est un attribut utilisateur spécial. Comme d’autres attributs tels que la ville ou le pays, vous le collectez lors de l’inscription. Contrairement à ces attributs, l’utilisateur peut utiliser ultérieurement l’alias pour se connecter. L’alias (par exemple, « johndoe ») offre aux utilisateurs un moyen plus court et plus convivial de se connecter que leur adresse e-mail.

Le nom d’utilisateur (alias) ne remplace pas le nom d’utilisateur (e-mail). Lors de l’inscription, l’application doit toujours collecter le nom d’utilisateur (e-mail) comme identificateur principal, et il collecte l’alias en tant qu’attribut en même temps que l’e-mail. Lors de la connexion, l’utilisateur peut ensuite choisir de se connecter avec son nom d’utilisateur (e-mail) ou son nom d’utilisateur (alias).

Lorsque l’attribut utilisateur intégré Username est activé dans votre flux utilisateur d’inscription, le SDK l’accepte à l’aide du même générateur UserAttributes utilisé pour les autres attributs, en utilisant la méthode flatUsername(). Vous pouvez transmettre le nom d’utilisateur (alias) directement dans l’appel d’inscription afin que l’utilisateur n’ait pas besoin d’effectuer une étape distincte d’attributs requis.

Pour collecter un nom d’utilisateur (alias), ajoutez un champ d’entrée pour le nom d’utilisateur dans votre interface utilisateur d’inscription en même temps que le champ de messagerie, puis transmettez l’alias en tant qu’attribut dans l’appel d’inscription :

val email = binding.emailText.text.toString()
val password = binding.passwordText.text.toString()
val username = binding.usernameText.text.toString()

val attributes = UserAttributes.Builder()
    .flatUsername(username)
    .build()

CoroutineScope(Dispatchers.Main).launch {
    val actionResult = authClient.signUpUsingPassword(
        username = email,
        password = password,
        attributes = attributes
    )

    when (actionResult) {
        is SignUpResult.CodeRequired -> {
            // Navigate to code verification
            navigateToCodeVerification(actionResult.nextState)
        }
        is SignUpUsingPasswordError -> {
            handleSignUpError(actionResult)
        }
    }
}

Pour les flux de code à usage unique par e-mail (sans mot de passe), utilisez signUp au lieu de signUpUsingPassword :

val actionResult = authClient.signUp(
    username = email,
    attributes = attributes
)

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 parameters = NativeAuthSignUpParameters(username = email)
 // Assign 'password' param if you sign in with username (email) and password
 // parameters.password = password
val actionResult: SignUpResult = authClient.signUp(parameters)

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(parameters) peut renvoyer 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, le SDK Android de Microsoft Authentication Library (MSAL) fournit des méthodes utilitaires pour analyser plus en détail les erreurs spécifiques :

  • La méthode isUserAlreadyExists() vérifie si le nom d’utilisateur ou l’alias 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. Il contient un paramètre invalidAttributes, qui est une liste de tous les attributs soumis par l’application, mais qui n’ont pas passé la validation.
  • isInvalidPassword() vérifie si le mot de passe n’est pas valide, par exemple lorsque le mot de passe ne répond pas à toutes les exigences de complexité du mot de passe. En savoir plus sur les stratégies de mot de passe de Microsoft Entra
  • isInvalidUsername() vérifie si 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 terminer 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’e-mail et le mot de passe comme méthode d’authentification, mais l’application ne parvient pas à envoyer le mot de passe en tant que type de défi ou ne le prend pas en charge. Suivez les étapes décrites dans Solution de secours web dans l’application Android pour traiter ce scénario.
  • 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 parameters = NativeAuthSignUpParameters(username = email)
  // Assign 'password' param if you sign in with username (email) and password
  // parameters.password = password
  parameters.attributes = userAttributes
  val actionResult: SignUpResult = authClient.signUp(parameters)
  
  if (actionResult is SignUpError && actionResult.isInvalidAttributes()) {
      val invalidAttributes = actionResult.invalidAttributes
  
      // Handle "invalid attributes" error, this time submit valid attributes
      val parameters = NativeAuthSignUpParameters(username = email)
      // Assign 'password' param if you sign in with username (email) and password
      // parameters.password = password
      parameters.attributes = userAttributes
      authClient.signUp(parameters)
  } 
  //...
  

Gérer l’erreur d’envoi d’un code secret à usage unique par e-mail

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 d'importation. Android Studio devrait inclure automatiquement les instructions d'importation pour vous.

Vous avez effectué toutes les étapes nécessaires pour inscrire un utilisateur dans votre application. Créez et exécutez votre application. Si tout est configuré correctement, vous devez être en mesure d’inscrire l’utilisateur à l’aide du code secret ou du mot de passe à usage unique par e-mail et du mot de passe, et de collecter les attributs utilisateur, y compris un nom d’utilisateur (alias).

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

Après un processus d’inscription réussi, vous pouvez connecter un utilisateur sans démarrer un processus de connexion. Si l’utilisateur s’est inscrit avec un nom d’utilisateur (alias), il peut se connecter à l’aide de son adresse e-mail ou de son alias. 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.