Freigeben über

Tutorial: Hinzufügen der Self-Service-Kennwortzurücksetzung

  • Artikel

In diesem Lernprogramm wird veranschaulicht, wie Benutzer ihr Kennwort ändern oder zurücksetzen können, ohne dass Administratoren oder Helpdesk beteiligt sind.

In diesem Lernprogramm erfahren Sie, wie Sie:

  • Hinzufügen des Flows zur Self-Service-Kennwortzurücksetzung (Self-Service Password Reset, SSPR)
  • Fügen Sie ihrer App die erforderliche Benutzeroberfläche (UI) für SSPR hinzu.
  • Behandeln von Fehlern.

Voraussetzungen

Hinzufügen des Flows zur Self-Service-Kennwortzurücksetzung

Um Ihrer Android-Anwendung einen SSPR-Ablauf hinzuzufügen, benötigen Sie eine Benutzeroberfläche zum Zurücksetzen von Passwörtern.

  • Ein Eingabetextfeld zum Sammeln der E-Mail-Adresse des Benutzers (Benutzername).
  • Ein Eingabetextfeld zum Sammeln eines Einmalpassworts.
  • Ein Eingabetextfeld zum Sammeln eines neuen Kennworts.

Wenn Benutzer ihre Kennwörter vergessen, benötigen sie ein Formular, um ihre Benutzernamen (E-Mail-Adressen) einzugeben, um den Kennwortzurücksetzungsfluss zu starten. Der Benutzer wählt die Schaltfläche oder den Link Kennwort vergessen aus.

Starten des Flows zur Kennwortzurücksetzung

Um die Anforderung zu behandeln, wenn der Benutzer die Schaltfläche oder den Link Kennwort vergessen auswählt, verwenden Sie die resetPassword(parameters)-Methode des Android SDK, wie im folgenden Codeausschnitt gezeigt:

 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) Methode initiiert den Prozess zum Zurücksetzen des Passworts, und zur Überprüfung wird ein Einmalpasscode an die E-Mail-Adresse des Benutzers gesendet.

  • Das Rückgabeergebnis von resetPassword(parameters) ist entweder ResetPasswordStartResult.CodeRequired oder ResetPasswordError.

  • Bei resetPasswordResult is ResetPasswordStartResult.CodeRequired muss die App den E-Mail-Einmal-Passcode vom Benutzer erfassen und wie unter Übermitteln eines E-Mail-Einmal-Passcodes gezeigt übermitteln.

  • Wenn resetPasswordResult is ResetPasswordError, bietet Android SDK Hilfsmethoden, mit denen Sie die spezifischen Fehler weiter analysieren können: - isUserNotFound()- isBrowserRequired()

  • Diese Fehler deuten darauf hin, dass der vorherige Vorgang nicht erfolgreich war und daher ein Verweis auf einen neuen Zustand nicht verfügbar ist. Behandeln Sie diese Fehler, wie im Abschnitt Behandeln von Fehlern dargestellt.

E-Mail Einmalpasswort eingeben

Ihre App sammelt die E-Mail-Einmalkennung des Benutzers. Verwenden Sie den folgenden Codeausschnitt, um die E-Mail-Einmalkennung zu übermitteln:

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

  • Das Rückgabeergebnis der submitCode()-Aktion ist entweder ResetPasswordSubmitCodeResult.PasswordRequired oder SubmitCodeError.

  • Bei submitCodeResult is ResetPasswordSubmitCodeResult.PasswordRequired muss die App ein neues Kennwort vom Benutzer erfassen und wie unter Übermitteln eines neuen Kennworts erläutert übermitteln.

  • Wenn der Benutzer die E-Mail-Einmalkennung in seiner E-Mail nicht erhält, kann die App die E-Mail-Einmalkennung erneut senden. Verwenden Sie den folgenden Codeausschnitt, um eine neue Einmalkennung einer E-Mail erneut zu senden:

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

    • Das Rückgabeergebnis der resendCode()-Aktion ist entweder ResetPasswordResendCodeResult.Success oder ResendCodeError.

    • ResendCodeError ist ein unerwarteter Fehler für DAS SDK. Dieser Fehler gibt an, dass der vorherige Vorgang nicht erfolgreich war, sodass ein Verweis auf einen neuen Zustand nicht verfügbar ist.

  • Wenn submitCodeResult is SubmitCodeError, stellt Android SDK Hilfsmethoden bereit, mit denen Sie die spezifischen Fehler weiter analysieren können:

    • isInvalidCode()
    • isBrowserRequired()

    Diese Fehler deuten darauf hin, dass der vorherige Vorgang nicht erfolgreich war und daher ein Verweis auf einen neuen Zustand nicht verfügbar ist. Behandeln Sie diese Fehler, wie im Abschnitt Behandeln von Fehlern dargestellt.

Übermitteln eines neuen Kennworts

Nachdem Sie die E-Mail des Benutzers überprüft haben, müssen Sie ein neues Kennwort vom Benutzer sammeln und übermitteln. Das Kennwort, das die App vom Benutzer sammelt, muss die Kennwortrichtlinien von Microsoft Entraerfüllen. Verwenden Sie den folgenden Codeausschnitt:

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

  • Das Rückgabeergebnis der submitPassword()-Aktion ist entweder ResetPasswordResult.Complete oder ResetPasswordSubmitPasswordError.

  • ResetPasswordResult.Complete gibt einen erfolgreichen Kennwortzurücksetzungsablauf an.

  • Wenn submitPasswordResult is ResetPasswordSubmitPasswordError, stellt das SDK Hilfsmethoden bereit, um den spezifischen Typ des zurückgegebenen Fehlers weiter zu analysieren: - isInvalidPassword()- isPasswordResetFailed()

    Diese Fehler deuten darauf hin, dass der vorherige Vorgang nicht erfolgreich war und daher ein Verweis auf einen neuen Zustand nicht verfügbar ist. Behandeln Sie diese Fehler, wie im Abschnitt Behandeln von Fehlern dargestellt.

Automatische Anmeldung nach dem Zurücksetzen des Kennworts

Nach einem erfolgreichen Ablauf der Kennwortzurücksetzung können Sie sich automatisch bei Ihren Benutzern anmelden, ohne einen neuen Anmeldefluss zu initiieren.

Die ResetPasswordResult.Complete gibt ein SignInContinuationState-Objekt zurück. Die SignInContinuationState bietet Zugriff auf die signIn(parameters)-Methode.

Verwenden Sie den folgenden Codeausschnitt, um Benutzer nach der Kennwortzurücksetzung automatisch anzumelden:

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

Um ID-Tokenansprüche nach der Anmeldung abzurufen, führen Sie die Schritte unter Lesen von ID-Tokenansprüchen aus.

Behandeln von Kennwortzurücksetzungsfehlern

Einige erwartete Fehler können auftreten. Beispielsweise kann der Benutzer versuchen, das Kennwort mit einer nicht vorhandenen E-Mail zurückzusetzen oder ein Kennwort anzugeben, das nicht den Kennwortanforderungen entspricht.

Wenn Fehler auftreten, geben Sie Ihren Benutzern einen Hinweis auf die Fehler.

Diese Fehler können am Anfang des Kennwortzurücksetzungsprozesses oder beim Absenden eines einmaligen Passworts per E-Mail oder bei der Eingabe des Kennworts auftreten.

Behandeln von Fehlern beim Starten der Kennwortzurücksetzung

Verwenden Sie den folgenden Codeschnipsel, um Fehler beim Starten der Kennwortzurücksetzung zu behandeln:

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

Behandeln von Fehlern beim Übermitteln eines E-Mail-Einmal-Passcodes

Verwenden Sie den folgenden Codeausschnitt, um Fehler zu behandeln, die durch das Absenden einer Einmal-Passcode-Email verursacht werden:

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

Behandeln eines Fehlers beim Übermitteln des Kennworts

Verwenden Sie den folgenden Codeausschnitt, um fehler zu behandeln, der durch das Senden des Kennworts verursacht wird:

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

Nächste Schritte

Lernprogramm: Unterstützung von Web-Fallback in Android-App