Handledning: Självbetjäning för lösenordsåterställning i iOS och macOS-app

Gäller för: arbetskraftshyresgäster externa hyresgäster (läs mer)

Den här självstudien visar hur du ger användarna möjlighet att ändra eller återställa sitt lösenord, utan administratörs- eller supportavdelningsengagemang.

I den här handledningen lär du dig hur man:

• Lägg till lösenordsåterställning med självbetjäning.
• Hantera fel.

Förutsättningar

• Aktivera lösenordsåterställning med självbetjäning

Återställa lösenord

För att återställa lösenordet för en befintlig användare måste vi verifiera e-postadressen med ett engångslösenord (OTP).

1. För att verifiera e-postmeddelandet anropar vi metoden resetPassword(parameters:delegate) från SDK-instansen med hjälp av följande kodfragment:

   let parameters = MSALNativeAuthResetPasswordParameters(username: email)
   nativeAuth.resetPassword(parameters: parameters, delegate: self)
   

2. Om du vill implementera ResetPasswordStartDelegate protokoll som ett tillägg till vår klass använder du följande kodfragment:

   extension ViewController: ResetPasswordStartDelegate {
       func onResetPasswordCodeRequired(
           newState: MSAL.ResetPasswordCodeRequiredState,
           sentTo: String,
           channelTargetType: MSALNativeAuthChannelType,
           codeLength: Int
       ) {
           resultTextView.text = "Verification code sent to \(sentTo)"
       }
   
       func onResetPasswordStartError(error: MSAL.ResetPasswordStartError) {
           resultTextView.text = "Error verifying code: \(error.errorDescription ?? "no description")"
       }
   }
   

   Anropet till resetPassword(parameters:delegate) resulterar i ett anrop till antingen onResetPasswordCodeRequired() eller onResetPasswordStartError() delegatmetoder.

   I det vanligaste scenariot anropas onResetPasswordCodeRequired(newState:sentTo:channelTargetType:codeLength) för att ange att en kod har skickats för att verifiera användarens e-postadress. Tillsammans med viss information om var koden har skickats och hur många siffror den innehåller, har den här delegatmetoden också en newState parameter av typen ResetPasswordCodeRequiredState, vilket ger oss åtkomst till två nya metoder:

   • submitCode(code:delegate)
   • resendCode(delegate)

   Om du vill skicka koden som användaren har angett för oss använder du:

   newState.submitCode(code: userSuppliedCode, delegate: self)
   

3. Om du vill verifiera den skickade koden börjar du med att implementera ResetPasswordVerifyCodeDelegate-protokollet som ett tillägg till klassen med hjälp av följande kodfragment:

   extension ViewController: ResetPasswordVerifyCodeDelegate {
   
       func onResetPasswordVerifyCodeError(
           error: MSAL.VerifyCodeError,
           newState: MSAL.ResetPasswordCodeRequiredState?
       ) {
           resultTextView.text = "Error verifying code: \(error.errorDescription ?? "no description")"
       }
   
       func onPasswordRequired(newState: MSAL.ResetPasswordRequiredState) {
           // use newState instance to submit the new password
       }
   }
   

   I det vanligaste scenariot får vi ett anrop till onPasswordRequired(newState) som anger att vi kan ange det nya lösenordet med hjälp av den newState instansen.

   newState.submitPassword(password: newPassword, delegate: self)
   

4. Om du vill implementera ResetPasswordRequiredDelegate protokoll som ett tillägg till vår klass använder du följande kodfragment:

   extension ViewController: ResetPasswordRequiredDelegate {
   
       func onResetPasswordRequiredError(
           error: MSAL.PasswordRequiredError,
           newState: MSAL.ResetPasswordRequiredState?
       ) {
           resultTextView.text = "Error submitting new password: \(error.errorDescription ?? "no description")"
       }
   
       func onResetPasswordCompleted(newState: SignInAfterResetPasswordState) {
           resultTextView.text = "Password reset completed"
       }
   }
   

   I det vanligaste scenariot får vi ett anrop till onResetPasswordCompleted(newState) som anger att flödet för lösenordsåterställning har slutförts.

Hantering av fel

I vår tidigare implementering av ResetPasswordStartDelegate-protokollet visade vi felet när vi hanterade den delegerade funktionen onResetPasswordStartError(error).

Vi kan förbättra användarupplevelsen genom att hantera den specifika feltypen på följande sätt:

func onResetPasswordStartError(error: MSAL.ResetPasswordStartError) {
    if error.isInvalidUsername {
        resultTextView.text = "Invalid username"
    } else if error.isUserNotFound {
        resultTextView.text = "User not found"
    } else if error.isUserDoesNotHavePassword {
        resultTextView.text = "User is not registered with a password"
    } else {
        resultTextView.text = "Error during reset password flow in: \(error.errorDescription ?? "no description")"
    }
}

Hantera fel med statusar

Vissa fel innehåller en referens till ett nytt tillstånd. Om användaren till exempel anger en felaktig e-postverifieringskod innehåller felhanteraren en referens till en ResetPasswordCodeRequiredState som kan användas för att skicka en ny verifieringskod.

I vår tidigare implementering av ResetPasswordVerifyCodeDelegate-protokollet visade vi helt enkelt felet när vi hanterade delegatfunktionen onResetPasswordError(error:newState).

Vi kan förbättra användarupplevelsen genom att be användaren att ange rätt kod och skicka den på nytt på följande sätt:

func onResetPasswordVerifyCodeError(
    error: MSAL.VerifyCodeError,
    newState: MSAL.ResetPasswordCodeRequiredState?
) {
    if error.isInvalidCode {
        // Inform the user that the submitted code was incorrect and ask for a new code to be supplied.
        // Request a new code calling `newState.resendCode(delegate)`
        let userSuppliedCode = retrieveNewCode(newState)
        newState?.submitCode(code: userSuppliedCode, delegate: self)
    } else {
        resultTextView.text = "Error verifying code: \(error.errorDescription ?? "no description")"
    }
}

Ett annat exempel där felhanteraren innehåller en referens till ett nytt tillstånd är när användaren anger ett ogiltigt lösenord. I det här fallet innehåller felhanteraren en referens till en ResetPasswordRequiredState som kan användas för att skicka ett nytt lösenord. Här är ett exempel:

func onResetPasswordRequiredError(
    error: MSAL.PasswordRequiredError,
    newState: MSAL.ResetPasswordRequiredState?
) {
    if error.isInvalidPassword {
        // Inform the user that the submitted password was invalid and ask for a new password to be supplied.
        let newPassword = retrieveNewPassword()
        newState?.submitPassword(password: newPassword, delegate: self)
    } else {
        resultTextView.text = "Error submitting password: \(error.errorDescription ?? "no description")"
    }
}

Logga in efter lösenordsåterställning

SDK ger utvecklare möjlighet att logga in en användare när de har återställt sitt lösenord utan att behöva ange användarnamnet eller verifiera e-postadressen via ett engångslösenord.

Om du vill logga in en användare efter en lyckad lösenordsåterställning använder du metoden signIn(parameters:delegate) från det nya tillståndet SignInAfterResetPasswordState som returneras i funktionen onResetPasswordCompleted(newState):

extension ViewController: ResetPasswordRequiredDelegate {

    func onResetPasswordRequiredError(
        error: MSAL.PasswordRequiredError,
        newState: MSAL.ResetPasswordRequiredState?
    ) {
        resultTextView.text = "Error submitting new password: \(error.errorDescription ?? "no description")"
    }

    func onResetPasswordCompleted() {
        resultTextView.text = "Password reset completed"
        let parameters = MSALNativeAuthSignInAfterResetPasswordParameters()
        newState.signIn(parameters: parameters, delegate: self)
    }
}

signIn(parameters:delegate) accepterar en delegatparameter och vi måste implementera de metoder som krävs i protokollet SignInAfterResetPasswordDelegate.

I det vanligaste scenariot får vi ett anrop till onSignInCompleted(result) som anger att användaren har loggat in. Resultatet kan användas för att hämta access token.

extension ViewController: SignInAfterSignUpDelegate {
    func onSignInAfterSignUpError(error: SignInAfterSignUpError) {
        resultTextView.text = "Error signing in after password reset"
    }

    func onSignInCompleted(result: MSAL.MSALNativeAuthUserAccountResult) {
        // User successfully signed in
        let parameters = MSALNativeAuthGetAccessTokenParameters()
        result.getAccessToken(parameters: parameters, delegate: self)
    }
}

getAccessToken(parameters:delegate) accepterar en delegatparameter och vi måste implementera de metoder som krävs i protokollet CredentialsDelegate.

I det vanligaste scenariot får vi ett anrop till onAccessTokenRetrieveCompleted(result) som anger att användaren fick en access token.

extension ViewController: CredentialsDelegate {
    func onAccessTokenRetrieveError(error: MSAL.RetrieveAccessTokenError) {
        resultTextView.text = "Error retrieving access token"
    }

    func onAccessTokenRetrieveCompleted(result: MSALNativeAuthTokenResult) {
        resultTextView.text = "Signed in. Access Token: \(result.accessToken)"
    }
}

Nästa steg

Självstudie: Stöd för webbfallback