Partilhar via

Tutorial: Adicionar redefinição de senha de autoatendimento

  • Artigo

Este tutorial demonstra como permitir que os usuários alterem ou redefina suas senhas, sem envolvimento de administrador ou suporte técnico.

Neste tutorial, você aprenderá a:

  • Adicione o fluxo de redefinição de senha de autoatendimento (SSPR).
  • Adicione a interface do usuário (UI) necessária para SSPR ao seu aplicativo.
  • Lide com erros.

Pré-requisitos

Adicionar fluxo de redefinição de senha de autoatendimento

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

  • Um campo de texto de entrada para coletar o endereço de e-mail do usuário (nome de usuário).
  • Um campo de texto de entrada para coletar uma senha única.
  • Um campo de texto de entrada para coletar 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 e-mail) para iniciar o fluxo de redefinição de senha. O usuário seleciona o botão ou link Esquecer senha.

Iniciar fluxo de redefinição de senha

Para lidar com a solicitação quando o usuário seleciona o botão ou link Esquecer senha, use o método resetPassword(parameters) do SDK do Android, conforme mostrado no trecho de código a seguir:

 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 submiteCode() 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 e-mail é enviada para o endereço de e-mail do usuário para verificação.

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

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

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

Enviar código de acesso único por e-mail

Seu aplicativo coleta a senha única de e-mail do usuário. Para enviar a senha única de e-mail, 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 precisa 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 do e-mail em seu e-mail, o aplicativo poderá reenviar a senha única do e-mail. Use o seguinte trecho de código para reenviar uma nova senha única de 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
              }
         } 
     } 
}

    • 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 Android SDK fornece métodos de utilidade 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. Manipule esses erros conforme mostrado na seção Manipular erros.

Enviar uma nova senha

Depois de verificar o e-mail do usuário, você precisa coletar uma nova senha do usuário e enviá-la. A senha que o aplicativo coleta do usuário precisa atender 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 fornece 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. Manipule esses erros conforme mostrado na seção Manipular erros.

Entrada automática após redefinição de senha

Após um fluxo de redefinição de senha bem-sucedido, pode autenticar automaticamente os seus utilizadores sem iniciar um novo fluxo de entrada.

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

Para iniciar sessão automaticamente os utilizadores 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 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 declarações de token de ID após o login, use as etapas em Ler declarações de token de ID.

Lidar com erros de redefinição de palavra-passe

Alguns erros esperados podem ocorrer. Por exemplo, o usuário pode tentar redefinir a senha com um e-mail 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 acontecer no início do fluxo de redefinição de senha ou no envio de senha única de e-mail ou no envio de senha.

Lidar com erro ao iniciar a redefinição de senha

Para manipular o erro causado pela redefinição de senha de início, use o seguinte trecho de código:

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

Lidar com o erro de senha única de envio de e-mail

Para lidar com o erro causado pelo envio de senha única de e-mail, use o seguinte trecho de código:

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

Tratar erro de palavra-passe de envio

Para manipular 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óximos passos

Tutorial: Suporte a fallback da Web no aplicativo Android