共用方式為

教學課程：新增自助式密碼重設

  • 發行項

本教學課程示範如何讓用戶變更或重設其密碼，而不需要系統管理員或技術支援中心介入。

在本教學課程中，您將瞭解如何：

  • 新增自助式密碼重設 （SSPR） 流程。
  • 將 SSPR 所需的使用者介面 （UI） 新增至您的應用程式。
  • 處理錯誤。

先決條件

新增自助式密碼重設流程

若要將 SSPR 流程新增至 Android 應用程式，您需要密碼重設使用者介面：

  • 用於收集使用者電子郵件地址的輸入文字欄位。
  • 用於收集一次性密碼的輸入欄位。
  • 用來輸入新密碼的文字欄位。

當使用者忘記密碼時，他們需要一個窗體來輸入使用者名稱（電子郵件位址），以啟動密碼重設流程。 用戶選取 [忘記密碼] 按鈕或連結。

啟動密碼重設流程

若要在使用者選取 [忘記密碼 ] 按鈕或鏈接時處理要求，請使用 Android SDK 的 resetPassword(parameters) 方法，如下列代碼段所示：

 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) 方法會起始密碼重設流程，並將電子郵件一次性密碼傳送至使用者的電子郵件地址進行驗證。

  • resetPassword(parameters) 傳回結果為 ResetPasswordStartResult.CodeRequired 或 ResetPasswordError。

  • 如果符合 resetPasswordResult is ResetPasswordStartResult.CodeRequired的條件，應用程式需要從使用者那裡收集電子郵件一次性密碼，並將其提交，如 提交電子郵件一次性密碼中所示。

  • 如果 resetPasswordResult is ResetPasswordError，Android SDK 會提供公用程式方法，讓您進一步分析特定錯誤： - isUserNotFound() - isBrowserRequired()

  • 這些錯誤表示先前的作業失敗，因此無法使用新狀態的參考。 處理這些錯誤，如 處理錯誤 一節所示。

提交電子郵件一次性密碼

您的應用程式會從使用者收集電子郵件一次性密碼。 若要提交電子郵件一次性密碼，請使用下列代碼段：

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

  • submitCode() 動作的傳回結果為 ResetPasswordSubmitCodeResult.PasswordRequired 或 SubmitCodeError。

  • 如果 submitCodeResult is ResetPasswordSubmitCodeResult.PasswordRequired 應用程式需要向使用者收集並提交新密碼，如 中“提交新密碼”所示。

  • 如果使用者在電子郵件中未收到電子郵件一次性密碼，應用程式可以重新傳送電子郵件一次性密碼。 使用下列代碼段重新傳送新的電子郵件一次性密碼：

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

    • resendCode() 動作的傳回結果為 ResetPasswordResendCodeResult.Success 或 ResendCodeError。

    • ResendCodeError SDK 發生非預期的錯誤。 此錯誤表示先前的作業失敗，因此無法使用新狀態的參考。

  • 如果 submitCodeResult is SubmitCodeError，Android SDK 會提供公用程式方法，讓您進一步分析特定錯誤：

    • isInvalidCode()
    • isBrowserRequired()

    這些錯誤表示先前的作業失敗，因此無法使用新狀態的參考。 處理這些錯誤，如 處理錯誤 一節所示。

提交新密碼

驗證使用者的電子郵件之後，您必須從使用者收集新密碼並提交。 應用程式從使用者收集的密碼必須符合 Microsoft Entra 的密碼原則。 使用下列代碼段：

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

  • submitPassword() 動作的傳回結果為 ResetPasswordResult.Complete 或 ResetPasswordSubmitPasswordError。

  • ResetPasswordResult.Complete 表示密碼重設流程成功。

  • 如果 submitPasswordResult is ResetPasswordSubmitPasswordError，SDK 會提供公用程式方法來進一步分析傳回的特定錯誤類型： - isInvalidPassword() - isPasswordResetFailed()

    這些錯誤表示先前的作業失敗，因此無法使用新狀態的參考。 處理這些錯誤，如 處理錯誤 一節所示。

密碼重設後自動登入

成功密碼重設流程之後，您可以自動登入使用者，而不需要起始全新的登入流程。

ResetPasswordResult.Complete 會傳回 SignInContinuationState 物件。 SignInContinuationState 可讓您存取 signIn(parameters) 方法。

若要在密碼重設之後自動登入使用者，請使用下列代碼段：

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

若要在登入之後擷取識別碼令牌宣告，請使用 讀取識別碼令牌宣告中的步驟。

處理密碼重設錯誤

可能會發生一些預期的錯誤。 例如，使用者可能會嘗試使用不存在的電子郵件重設密碼，或提供不符合密碼需求的密碼。

發生錯誤時，請向使用者提供錯誤提示。

這些錯誤可能發生在密碼重設流程開始時，或在提交電子郵件一次性密碼或提交密碼時發生。

處理啟動密碼重設錯誤

若要處理啟動密碼重設所造成的錯誤，請使用下列代碼段：

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

處理提交電子郵件一次性密碼錯誤

若要處理提交電子郵件一次性密碼所造成的錯誤，請使用下列程式碼片段：

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

處理送出密碼錯誤

若要處理提交密碼所造成的錯誤，請使用下列代碼段：

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

後續步驟

教學：在 Android 應用程式中支援 Web 後備方案