Tutoriel : Ajouter la réinitialisation de mot de passe en libre-service

Ce tutoriel montre comment permettre aux utilisateurs de changer ou de réinitialiser leur mot de passe, sans intervention d’un administrateur ou du support technique.

Dans ce tutoriel, vous allez apprendre à :

• Ajouter un flux de réinitialisation de mot de passe en libre-service (SSPR).
• Ajoutez l’interface utilisateur (IU) nécessaire à la réinitialisation SSPR dans votre application.
• Gérer les erreurs.

Prérequis

• Suivez les étapes décrites dans Connecter des utilisateurs dans un exemple d’application mobile Android native. Cet article vous montre comment exécuter un exemple d’application Android que vous configurez à l’aide des paramètres de votre tenant.
• Activer la réinitialisation de mot de passe en libre-service. Cet article vous permet d’activer la méthode d’authentification par code secret à usage unique envoyé par e-mail pour tous les utilisateurs de votre tenant, ce qui est obligatoire pour la réinitialisation SSPR.
• Tutoriel : Préparer votre application Android pour l’authentification native.

Ajouter un flux de réinitialisation de mot de passe en libre-service

Pour ajouter un flux de réinitialisation SSPR à votre application Android, vous avez besoin d’une interface utilisateur de réinitialisation de mot de passe :

• Champ de texte d’entrée permettant de collecter l’adresse e-mail de l’utilisateur (nom d’utilisateur).
• Un champ de texte d’entrée permettant de collecter le code secret à usage unique.
• Champ de texte d’entrée permettant de collecter le nouveau mot de passe.

Quand les utilisateurs oublient leur mot de passe, ils ont besoin d’un formulaire où ils peuvent entrer leurs noms d’utilisateurs (adresses e-mail) pour démarrer le flux de réinitialisation de mot de passe. L’utilisateur sélectionne le bouton ou le lien Oublier le mot de passe.

Démarrer le flux de réinitialisation de mot de passe

Pour gérer la requête quand l’utilisateur sélectionne le bouton ou le lien Oublier le mot de passe, utilisez la méthode resetPassword(username) du kit Android SDK, comme indiqué dans l’extrait de code suivant :

 private fun forgetPassword() { 
  CoroutineScope(Dispatchers.Main).launch { 
      try { 
        val resetPasswordResult = authClient.resetPassword( 
              username = emailAddress 
          ) 

         when (resetPasswordResult) { 
             is ResetPasswordStartResult.CodeRequired -> { 
                 // The implementation of submiteCode() please see below. 
                 submitCode(resetPasswordResult.nextState) 
             } 
              is ResetPasswordError -> {
                  // Handle errors
                  handleResetPasswordError(resetPasswordResult)
              }
         } 
     } catch (exception: MsalException) { 
          // Handle exception 
      } 
  } 
 } 

• La méthode resetPassword(username) lance le flux de réinitialisation de mot de passe, puis un code secret à usage unique est envoyé par e-mail à l’adresse e-mail de l’utilisateur à des fins de vérification.

• Le résultat retourné par resetPassword(username) est ResetPasswordStartResult.CodeRequired ou ResetPasswordError.

• Si resetPasswordResult is ResetPasswordStartResult.CodeRequired, l’application doit collecter le code secret à usage unique envoyé par e-mail auprès de l’utilisateur, puis le soumettre comme indiqué dans Soumettre le code secret à usage unique envoyé par e-mail.

• Si resetPasswordResult is ResetPasswordError, le kit Android SDK fournit des méthodes utilitaires qui vous permettent d’analyser les erreurs spécifiques de manière plus détaillée : - isUserNotFound() - isBrowserRequired()

• Ces erreurs indiquent que l’opération précédente a échoué. Aucune référence à un nouvel état n’est donc disponible. Gérez ces erreurs comme indiqué dans la section Gérer les erreurs.

Soumettre le code secret à usage unique envoyé par e-mail

Votre application collecte le code secret à usage unique envoyé par e-mail auprès de l’utilisateur. Pour soumettre le code secret à usage unique envoyé par e-mail, utilisez l’extrait de code suivant :

private suspend fun submitCode(currentState: ResetPasswordCodeRequiredState) { 
    val code = binding.codeText.text.toString() 
    val submitCodeResult = currentState.submitCode(code) 

    when (submitCodeResult) { 
        is ResetPasswordSubmitCodeResult.PasswordRequired -> { 
            // Handle success
            resetPassword(submitCodeResult.nextState) 
        } 
         is SubmitCodeError -> {
             // Handle errors
             handleSubmitCodeError(actionResult)
         }
    } 
} 

• Le résultat retourné par l’action submitCode() est ResetPasswordSubmitCodeResult.PasswordRequired ou SubmitCodeError.

• Si submitCodeResult is ResetPasswordSubmitCodeResult.PasswordRequired, l’application doit collecter un nouveau mot de passe auprès de l’utilisateur, puis le soumettre, comme indiqué dans Soumettre un nouveau mot de passe.

• Si l’utilisateur ne reçoit pas le code secret à usage unique envoyé par e-mail, l’application peut le renvoyer. Utilisez l’extrait de code suivant pour renvoyer un nouveau code secret à usage unique par e-mail :

  private fun resendCode() { 
       clearCode() 
  
       val currentState = ResetPasswordCodeRequiredState 
  
       CoroutineScope(Dispatchers.Main).launch { 
           val resendCodeResult = currentState.resendCode() 
  
           when (resendCodeResult) { 
               is ResetPasswordResendCodeResult.Success -> { 
                   // Handle code resent success
               } 
               is ResendCodeError -> {
                    // Handle ResendCodeError errors
                }
           } 
       } 
  } 
  

  • Le résultat retourné par l’action resendCode() est ResetPasswordResendCodeResult.Success ou ResendCodeError.

  • ResendCodeError est une erreur inattendue pour le kit SDK. Cette erreur indique que l’opération précédente a échoué. Aucune référence à un nouvel état n’est donc disponible.

• Si submitCodeResult is SubmitCodeError, le kit Android SDK fournit des méthodes utilitaires qui vous permettent d’analyser les erreurs spécifiques de manière plus détaillée :

  • isInvalidCode()
  • isBrowserRequired()

  Ces erreurs indiquent que l’opération précédente a échoué. Aucune référence à un nouvel état n’est donc disponible. Gérez ces erreurs comme indiqué dans la section Gérer les erreurs.

Soumettre un nouveau mot de passe

Une fois que vous avez vérifié l’adresse e-mail de l’utilisateur, vous devez collecter un nouveau mot de passe auprès de cet utilisateur, puis soumettre ce mot de passe. Le mot de passe que l’application collecte auprès de l’utilisateur doit répondre aux stratégies de mot de passe de Microsoft Entra. Utilisez l’extrait de code suivant :

private suspend fun resetPassword(currentState: ResetPasswordPasswordRequiredState) { 
    val password = binding.passwordText.text.toString() 

    val submitPasswordResult = currentState.submitPassword(password) 

    when (submitPasswordResult) { 
        is ResetPasswordResult.Complete -> { 
            // Handle reset password complete. 
        } 
        is ResetPasswordSubmitPasswordError -> {
            // Handle errors
            handleSubmitPasswordError(actionResult)
        }
    } 
} 

• Le résultat retourné par l’action submitPassword() est ResetPasswordResult.Complete ou ResetPasswordSubmitPasswordError.

• ResetPasswordResult.Complete indique un flux de réinitialisation de mot de passe réussi.

• Si submitPasswordResult is ResetPasswordSubmitPasswordError, le kit SDK fournit des méthodes utilitaires pour approfondir l’analyse du type d’erreur spécifique retourné : - isInvalidPassword() - isPasswordResetFailed()

  Ces erreurs indiquent que l’opération précédente a échoué. Aucune référence à un nouvel état n’est donc disponible. Gérez ces erreurs comme indiqué dans la section Gérer les erreurs.

Connexion automatique après la réinitialisation de mot de passe

Après un flux de réinitialisation de mot de passe réussi, vous pouvez connecter automatiquement vos utilisateurs sans lancer un nouveau flux de connexion.

ResetPasswordResult.Complete retourne l’objet SignInContinuationState. SignInContinuationState permet d’accéder à la méthode signIn().

Pour connecter automatiquement les utilisateurs après une réinitialisation de mot de passe, utilisez l’extrait de code suivant :

 private suspend fun resetPassword(currentState: ResetPasswordPasswordRequiredState) { 
     val submitPasswordResult = currentState.submitPassword(password) 
 
     when (submitPasswordResult) { 
         is ResetPasswordResult.Complete -> { 
             signInAfterPasswordReset(nextState = actionResult.nextState)
         } 
     } 
 } 
 
 private suspend fun signInAfterPasswordReset(nextState: SignInContinuationState) {
      val currentState = nextState
      val actionResult = currentState.signIn()
      when (actionResult) {
          is SignInResult.Complete -> {
              fetchTokens(accountState = actionResult.resultValue)
          }
          else {
              // Handle unexpected error
          }
      }
  }
 
  private suspend fun fetchTokens(accountState: AccountState) {
      val accessTokenResult = accountState.getAccessToken()
      if (accessTokenResult is GetAccessTokenResult.Complete) {
          val accessToken =  accessTokenResult.resultValue.accessToken
          val idToken = accountState.getIdToken()
      }
 }

Pour récupérer les revendications de jeton d’ID après la connexion, suivez les étapes décrites dans Lire les revendications de jeton d’ID.

Gérer les erreurs liées à la réinitialisation de mot de passe

Quelques erreurs prévisibles peuvent se produire. Par exemple, l’utilisateur peut tenter de réinitialiser le mot de passe avec un e-mail inexistant, ou fournir un mot de passe qui ne répond pas aux exigences des mots de passe.

Quand des erreurs se produisent, donnez à vos utilisateurs un indice sur ces erreurs.

Ces erreurs peuvent se produire au début du flux de réinitialisation de mot de passe, au moment de soumettre le code secret à usage unique envoyé par e-mail, ou au moment de soumettre le mot de passe.

Gérer l’erreur au lancement du processus de réinitialisation de mot de passe

Pour gérer l’erreur causée par le lancement de la réinitialisation de mot de passe, utilisez l’extrait de code suivant :

private fun handleResetPasswordError(error: ResetPasswordError) {
    when {
        error.isUserNotFound() -> {
            // Display error
        }
        else -> {
            // Unexpected error
        }
    }
}

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

Pour gérer l’erreur au moment où un code secret à usage unique envoyé par e-mail est soumis, utilisez l’extrait de code suivant :

private fun handleSubmitCodeError(error: SubmitCodeError) {
    when {
        error.isInvalidCode() -> {
            // Display error
        }
        else -> {
            // Unexpected error
        }
    }
}

Gérer l’erreur au moment où un mot de passe est soumis

Pour gérer l’erreur au moment où un mot de passe est soumis, utilisez l’extrait de code suivant :

private fun handleSubmitPasswordError(error: ResetPasswordSubmitPasswordError) {
    when {
        error.isInvalidPassword() || error.isPasswordResetFailed()
        -> {
            // Display error
        }
        else -> {
            // Unexpected error
        }
    }
}

Étapes suivantes

Tutoriel : Prise en charge du secours web dans l’application Android