Tutorial: Adicionar redefinição de senha de autoatendimento

Aplica-se a: Locatários externos (saiba mais)

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ê:

Pré-requisitos

• Conclua as etapas descritas em Conectar usuários em um aplicativo móvel Android nativo de exemplo. Este artigo mostra como executar um aplicativo Android de exemplo que você configura usando as configurações do seu ambiente.
• Habilitar redefinição de senha de autoatendimento. Este artigo permite habilitar o método de autenticação de senha única por email para todos os usuários em seu locatário, o que é um requisito para SSPR.
• Tutorial: Prepare seu aplicativo Android para autenticação nativa.

Adicionar fluxo de redefinição de senha de autoatendimento

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 única.
• 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 Esquecer Senha.

Iniciar o fluxo de redefinição de senha

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

 private fun forgetPassword() { 
     CoroutineScope(Dispatchers.Main).launch { 
         val parameter = NativeAuthResetPasswordParameters(username = email)
         val actionResult = authClient.resetPassword(parameter)

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

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

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

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

• Se resetPasswordResult is ResetPasswordError, o SDK do Android fornecerá 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 está disponível. Trate esses erros conforme mostrado na seção Tratar erros.

Enviar senha única por email

Seu aplicativo coleta a senha única de email do usuário. Para enviar a senha única do email, use o seguinte snippet 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 única de email em seu email, o aplicativo poderá reenviar a senha única do email. Use o seguinte snippet de código para reenviar uma nova senha única de 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 está disponível. Trate esses erros conforme mostrado na seção Tratar 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 snippet 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 melhor 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 está disponível. Trate esses erros conforme mostrado na seção Tratar erros.

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

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

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

Para conectar automaticamente os usuários após uma redefinição de senha, use o seguinte snippet 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 signInContinuationState = nextState

     val parameters = NativeAuthSignInContinuationParameters()
     val signInActionResult = signInContinuationState.signIn(parameters)

     when (actionResult) {
         is SignInResult.Complete -> {
             fetchTokens(accountState = actionResult.resultValue)
         }
         else {
             // Handle unexpected error
         }
     }
  }
 
 private suspend fun fetchTokens(accountState: AccountState) {
     val getAccessTokenParameters = NativeAuthGetAccessTokenParameters()
     val accessTokenResult = accountState.getAccessToken(getAccessTokenParameters)

     if (accessTokenResult is GetAccessTokenResult.Complete) {
         val accessToken =  accessTokenResult.resultValue.accessToken
         val idToken = accountState.getIdToken()
     }
 }

Para recuperar as declarações de token de ID após a entrada, use as etapas descritas 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 ocorrerem erros, dê aos usuários uma dica sobre os erros.

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

Tratar o erro de redefinição de senha inicial

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

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

Tratar um erro de senha de uso único por email ao enviar

Para lidar com o erro causado pelo envio de senha única por email, use o seguinte snippet de código:

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

Gerenciar o erro de envio de senha

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

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

Próximas etapas

Tutorial: Como dar suporte ao recurso de fallback da web no aplicativo Android