Samouczek: Dodaj samoobsługowe resetowanie hasła

Dotyczy: Dzierżawy zewnętrzne (dowiedz się więcej)

W tym samouczku pokazano, jak umożliwić użytkownikom zmianę lub zresetowanie hasła bez udziału administratora ani działu pomocy technicznej.

W tym samouczku nauczysz się następujących rzeczy:

• Dodaj przepływ resetowania hasła metodą samoobsługową (SSPR).
• Dodaj wymagany interfejs użytkownika dla SSPR do aplikacji.
• Zarządzanie błędami.

Warunki wstępne

• Wykonaj kroki opisane w Logowanie użytkowników w przykładowej natywnej aplikacji mobilnej systemu Android. W tym artykule pokazano, jak uruchomić przykładowy system Android skonfigurowany przy użyciu ustawień dzierżawy.
• Włącz samoobsługowe resetowanie haseł. Ten artykuł umożliwia włączenie metody uwierzytelniania przy użyciu jednorazowego kodu dostępu wysyłanego e-mailem dla wszystkich użytkowników w twojej dzierżawie, co jest wymaganiem dla samoobsługowego resetowania hasła (SSPR).
• Samouczek: Przygotuj aplikację Android do natywnego uwierzytelniania.

Dodaj przepływ samoobsługowego resetowania hasła

Aby dodać przepływ samoobsługowego resetowania hasła (SSPR) do aplikacji Android, potrzebujesz interfejsu użytkownika do resetowania hasła:

• Pole tekstowe danych wejściowych do zbierania adresu e-mail użytkownika (nazwy użytkownika).
• Pole tekstowe wejściowe do zbierania jednorazowego kodu dostępu.
• Pole tekstowe wejściowe do zbierania nowego hasła.

Gdy użytkownicy zapomną hasła, potrzebują formularza, aby wprowadzić swoje nazwy użytkowników (adresy e-mail), aby rozpocząć przepływ resetowania hasła. Użytkownik wybiera przycisk Zapomnij hasło lub link.

Uruchamianie przepływu resetowania hasła

Aby obsłużyć żądanie, gdy użytkownik wybierze przycisk Zapomnij hasło lub link, użyj metody resetPassword(parameters) zestawu SDK systemu Android, jak pokazano w poniższym fragmencie kodu:

 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) metoda inicjuje przepływ resetowania hasła, a jednorazowy kod dostępu wiadomości e-mail jest wysyłany na adres e-mail użytkownika na potrzeby weryfikacji.

• Wynik zwracany przez resetPassword(parameters) to ResetPasswordStartResult.CodeRequired lub ResetPasswordError.

• Jeśli resetPasswordResult is ResetPasswordStartResult.CodeRequired, aplikacja musi zebrać jednorazowy kod dostępu e-mail od użytkownika i przesłać go, jak pokazano w Prześlij jednorazowy kod dostępu wiadomości e-mail.

• Jeśli resetPasswordResult is ResetPasswordError, zestaw Android SDK udostępnia metody narzędziowe umożliwiające dalsze analizowanie określonych błędów: — isUserNotFound() - isBrowserRequired()

• Te błędy wskazują, że poprzednia operacja zakończyła się niepowodzeniem, dlatego odwołanie do nowego stanu nie jest dostępne. Obsłuż te błędy, jak pokazano w sekcji Obsługa błędów.

Prześlij jednorazowy kod dostępu z wiadomości e-mail

Aplikacja zbiera kod jednorazowy otrzymany przez e-mail od użytkownika. Aby przesłać jednorazowy kod dostępu wiadomości e-mail, użyj następującego fragmentu kodu:

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

• Rezultat akcji submitCode() może być ResetPasswordSubmitCodeResult.PasswordRequired lub SubmitCodeError.

• Jeśli submitCodeResult is ResetPasswordSubmitCodeResult.PasswordRequired aplikacja musi zebrać nowe hasło od użytkownika i przesłać je, jak pokazano w Prześlij nowe hasło.

• Jeśli użytkownik nie otrzyma jednorazowego kodu dostępu w wiadomości e-mail, aplikacja może wysłać ponownie kod dostępu jednorazowego wiadomości e-mail. Użyj następującego fragmentu kodu, aby ponownie wysłać nowy kod dostępu jednorazowego wiadomości 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
                }
           } 
       } 
  } 
  

  • Rezultat akcji resendCode() może być ResetPasswordResendCodeResult.Success lub ResendCodeError.

  • ResendCodeError jest nieoczekiwanym błędem zestawu SDK. Ten błąd wskazuje, że poprzednia operacja nie powiodła się, więc odwołanie do nowego stanu nie jest dostępne.

• Jeśli submitCodeResult is SubmitCodeError, zestaw Sdk systemu Android udostępnia metody narzędziowe umożliwiające dalsze analizowanie określonych błędów:

  • isInvalidCode()
  • isBrowserRequired()

  Te błędy wskazują, że poprzednia operacja zakończyła się niepowodzeniem, dlatego odwołanie do nowego stanu nie jest dostępne. Obsłuż te błędy, jak pokazano w sekcji Obsługa błędów.

Prześlij nowe hasło

Po zweryfikowaniu wiadomości e-mail użytkownika należy zebrać nowe hasło od użytkownika i przesłać je. Hasło zbierane przez aplikację od użytkownika musi spełniać zasad haseł firmy Microsoft Entra. Użyj następującego fragmentu kodu:

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

• Rezultat akcji submitPassword() może być ResetPasswordResult.Complete lub ResetPasswordSubmitPasswordError.

• ResetPasswordResult.Complete wskazuje pomyślny przepływ resetowania hasła.

• Jeśli submitPasswordResult is ResetPasswordSubmitPasswordError, zestaw SDK udostępnia metody narzędziowe do dalszej analizy zwróconego typu błędu: — isInvalidPassword() - isPasswordResetFailed()

  Te błędy wskazują, że poprzednia operacja zakończyła się niepowodzeniem, dlatego odwołanie do nowego stanu nie jest dostępne. Obsłuż te błędy, jak pokazano w sekcji Obsługa błędów.

Automatyczne logowanie po zresetowaniu hasła

Po pomyślnym przepływie resetowania hasła możesz automatycznie logować użytkowników bez inicjowania nowego przepływu logowania.

ResetPasswordResult.Complete zwraca obiekt SignInContinuationState. SignInContinuationState zapewnia dostęp do metody signIn(parameters).

Aby automatycznie logować użytkowników po zresetowaniu hasła, użyj następującego fragmentu kodu:

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

Aby pobrać roszczenia tokenu ID po zalogowaniu, wykonaj kroki opisane w Read ID token claims.

Obsługa błędów resetowania hasła

Może wystąpić kilka oczekiwanych błędów. Na przykład użytkownik może podjąć próbę zresetowania hasła z nieistniejącą wiadomością e-mail lub podać hasło, które nie spełnia wymagań dotyczących hasła.

Gdy wystąpią błędy, daj użytkownikom wskazówkę dotyczącą błędów.

Te błędy mogą wystąpić na początku przepływu resetowania hasła, podczas przesyłania jednorazowego kodu dostępu w wiadomości e-mail lub przy wprowadzaniu nowego hasła.

Obsługa błędu uruchamiania resetowania hasła

Aby obsłużyć błąd spowodowany przez uruchomienie resetowania hasła, użyj następującego fragmentu kodu:

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

Obsługa błędu jednorazowego kodu dostępu wysyłanego e-mailem

Aby obsłużyć błąd spowodowany przesyłaniem jednorazowego kodu wiadomości e-mail, użyj następującego fragmentu kodu:

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

Obsługa błędu przesyłania hasła

Aby obsłużyć błąd spowodowany przesyłaniem hasła, użyj następującego fragmentu kodu:

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

Następne kroki

Samouczek: obsługa internetowego rozwiązania awaryjnego w aplikacji Android