Tutorial: Adicionar redefinição de senha self-service

Este tutorial demonstra como permitir que os usuários alterem ou redefinam sua senha, sem envolvimento de administrador ou suporte técnico.

Neste tutorial, você aprenderá a:

• Adicione fluxo de SSPR (redefinição de senha self-service).
• Adicione a IU (interface do usuário) necessária para SSPR ao seu aplicativo.
• Identificar erros.

Pré-requisitos

• Conclua as etapas Conectar usuários em um aplicativo móvel Android nativo de exemplo. Este artigo mostra como executar um Android de amostra que você configura usando suas configurações de locatário.
• Habilite a redefinição de senha self-service. Este artigo permite habilitar o método de autenticação de senha de uso único por email para todos os usuários em seu locatário, o que é um requisito para SSPR.
• Tutorial: Preparar o aplicativo do Android para a autenticação nativa.

Adicionar fluxo de redefinição de senha self-service

Para adicionar o fluxo SSPR ao seu aplicativo Android, você precisa de uma interface do usuário de redefinição de senha:

• Um campo de texto de entrada para coletar o endereço de email do usuário (nome de usuário).
• Um campo de texto de entrada para coletar a senha de uso único.
• Um campo de texto de entrada para coletar uma nova senha.

Quando os usuários esquecem suas senhas, eles precisam de um formulário para inserir seus nomes de usuário (endereços de email) para iniciar o fluxo de redefinição de senha. O usuário seleciona o botão ou link Esqueci a Senha.

Iniciar o fluxo de redefinição de senha

Para lidar com a solicitação quando o usuário selecionar o botão ou link Esqueci a Senha, use o método do SDK do Android resetPassword(username), conforme mostrado no seguinte trecho de código:

 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 
      } 
  } 
 } 

• O método resetPassword(username) inicia o fluxo de redefinição de senha e uma senha de uso único por email é enviada para o endereço de email do usuário para verificação.

• O resultado de resetPassword(username) é ResetPasswordStartResult.CodeRequired ou ResetPasswordError.

• Se resetPasswordResult is ResetPasswordStartResult.CodeRequired, o aplicativo precisa coletar a senha de uso único por email do usuário e enviá-la conforme mostrado em Enviar senha de uso único por email.

• Se resetPasswordResult is ResetPasswordError, o SDK do Android fornece métodos utilitários para permitir que você analise ainda mais os erros específicos: - isUserNotFound() - isBrowserRequired()

• Esses erros indicam que a operação anterior não foi bem-sucedida e, portanto, uma referência a um novo estado não estará disponível. Lide com esses erros conforme mostrado na seção Lidar com erros.

Enviar senha de uso único por email

Seu aplicativo coleta a senha de uso único por email do usuário. Para enviar a senha de uso único por email, use o seguinte trecho de código:

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)
         }
    } 
} 

• O resultado de retorno da ação submitCode() é ResetPasswordSubmitCodeResult.PasswordRequired ou SubmitCodeError.

• Se submitCodeResult is ResetPasswordSubmitCodeResult.PasswordRequired o aplicativo precisar coletar uma nova senha do usuário e enviá-la conforme mostrado em Enviar uma nova senha.

• Se o usuário não receber a senha de uso único por email, o aplicativo poderá reenviar a senha de uso único por email. Use o seguinte trecho de código para reenviar uma nova senha de uso único por email:

  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
                }
           } 
       } 
  } 
  

  • O resultado de retorno da ação resendCode() é ResetPasswordResendCodeResult.Success ou ResendCodeError.

  • ResendCodeError é um erro inesperado para o SDK. Esse erro indica que a operação anterior não foi bem-sucedida, portanto, uma referência a um novo estado não está disponível.

• Se submitCodeResult is SubmitCodeError, o SDK do Android fornecerá métodos utilitários para permitir que você analise ainda mais os erros específicos:

  • isInvalidCode()
  • isBrowserRequired()

  Esses erros indicam que a operação anterior não foi bem-sucedida e, portanto, uma referência a um novo estado não estará disponível. Lide com esses erros conforme mostrado na seção Lidar com erros.

Enviar uma nova senha

Depois de verificar o email do usuário, você precisa coletar uma nova senha do usuário e enviá-la. A senha coletada pelo aplicativo do usuário precisa atender às políticas de senha do Microsoft Entra. Use o seguinte trecho de código:

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)
        }
    } 
} 

• O resultado de retorno da ação submitPassword() é ResetPasswordResult.Complete ou ResetPasswordSubmitPasswordError.

• ResetPasswordResult.Complete indica um fluxo de redefinição de senha bem-sucedido.

• Se submitPasswordResult is ResetPasswordSubmitPasswordError, o SDK fornecerá métodos utilitários para analisar ainda mais o tipo específico de erro retornado: - isInvalidPassword() - isPasswordResetFailed()

  Esses erros indicam que a operação anterior não foi bem-sucedida e, portanto, uma referência a um novo estado não estará disponível. Lide com esses erros conforme mostrado na seção Lidar com erros.

Entrar automaticamente após a redefinição de senha

Após um fluxo de redefinição de senha bem-sucedido, você pode entrar automaticamente em seus usuários sem iniciar um novo fluxo de entrada.

O ResetPasswordResult.Complete retorna o objeto SignInContinuationState. O SignInContinuationState fornece acesso ao método signIn().

Para conectar automaticamente os usuários após uma redefinição de senha, use o seguinte trecho de código:

 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()
      }
 }

Para recuperar declarações de token de ID após a entrada, use as etapas em Ler declarações de token de ID.

Lidar com erros de redefinição de senha

Alguns erros esperados podem ocorrer. Por exemplo, o usuário pode tentar redefinir a senha com um email inexistente ou fornecer uma senha que não atenda aos requisitos de senha.

Quando os erros ocorrerem, dê aos usuários uma dica sobre os erros.

Esses erros podem ocorrer no início do fluxo de redefinição de senha ou ao enviar senha de uso único por email ou ao enviar senha.

Lidar com o erro de redefinição de senha inicial

Para lidar com o erro causado pela redefinição de senha inicial, use o seguinte trecho de código:

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

Manipular o erro de senha de envio de email único

Para lidar com o erro causado pelo envio da senha de uso único por email, use o seguinte trecho de código:

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

Lidar com o erro de envio de senha

Para lidar com o erro causado pelo envio de senha, use o seguinte trecho de código:

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

Próximas etapas

Tutorial: Suporte ao fallback da Web no aplicativo Android