チュートリアル: セルフサービス パスワード リセットを追加する

適用対象: 従業員テナント 外部テナント (詳細情報)

このチュートリアルでは、管理者やヘルプ デスクの関与なしで、ユーザーが自分のパスワードを変更またはリセットできるようにする方法について説明します。

このチュートリアルでは、次の操作を行います。

前提条件

• 「ネイティブ Android モバイル アプリケーションのサンプルでユーザーをサインインする」の手順を完了します。 この記事では、テナント設定を使用して構成するサンプル Android を実行する方法について説明します。
• セルフサービス パスワード リセットを有効にします。 この記事では、SSPR の要件であるテナント内のすべてのユーザーに対して電子メール ワンタイム パスコード認証方法を有効にすることができます。
• チュートリアル: ネイティブ認証用に Android アプリを準備します。

セルフサービス パスワード リセット フローを追加する

Android アプリケーションに SSPR フローを追加するには、パスワード リセット ユーザー インターフェイスが必要です。

• ユーザーのメール アドレス (ユーザー名) を収集するための入力テキスト フィールド。
• ワンタイム パスコードを収集する入力テキスト フィールド。
• 新しいパスワードを収集するための入力テキスト フィールド。

ユーザーがパスワードを忘れた場合、パスワード リセット フローを開始するためにユーザー名 (電子メール アドレス) を入力するフォームが必要です。 ユーザーが [パスワードを忘れた場合] ボタンまたはリンクを選択します。

パスワード リセット フローを開始する

ユーザーが [パスワードを忘れる] ボタンまたはリンク 選択したときに要求を処理するには、次のコード スニペットに示すように 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 submitCode() 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()
     }
 }

サインイン後に ID トークン要求を取得するには、「id トークン要求の読み取り の手順を使用します。

パスワード リセット エラーの処理

予期されるエラーがいくつか発生する可能性があります。 たとえば、ユーザーが存在しないメールでパスワードをリセットしようとしたり、パスワードの要件を満たしていないパスワードを指定しようとしたりすることがあります。

エラーが発生した場合は、ユーザーにエラーのヒントを提供します。

これらのエラーは、パスワード リセット フローの開始時、または電子メールのワンタイム パスコードの送信時、またはパスワードの送信時に発生する可能性があります。

パスワード リセットの開始エラーを処理する

パスワードリセットの開始に起因するエラーを処理するには、次のコード スニペットを使用します。

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 フォールバックのサポート