Tutorial: Menambahkan pengaturan ulang kata sandi mandiri

Tutorial ini menunjukkan cara memungkinkan pengguna mengubah atau mengatur ulang kata sandi mereka, tanpa keterlibatan administrator atau staf dukungan.

Dalam tutorial ini, Anda akan mempelajari cara:

• Tambahkan alur pengaturan ulang kata sandi mandiri (SSPR).
• Tambahkan antarmuka pengguna (UI) yang diperlukan untuk SSPR ke aplikasi Anda.
• Menangani kesalahan.

Prasyarat

• Selesaikan langkah-langkah dalam Memasukkan pengguna dalam sampel aplikasi seluler Android asli. Artikel ini memperlihatkan kepada Anda cara menjalankan contoh Android yang Anda konfigurasi dengan menggunakan pengaturan penyewa Anda.
• Aktifkan pengaturan ulang kata sandi mandiri. Artikel ini memungkinkan Anda mengaktifkan metode autentikasi kode akses satu kali email untuk semua pengguna di penyewa Anda, yang merupakan persyaratan untuk SSPR.
• Tutorial: Siapkan aplikasi Android Anda untuk autentikasi asli.

Menambahkan alur pengaturan ulang kata sandi mandiri

Untuk menambahkan alur SSPR ke aplikasi Android, Anda memerlukan antarmuka pengguna reset kata sandi:

• Bidang teks input untuk mengumpulkan alamat email pengguna (nama pengguna).
• Bidang teks input untuk mengumpulkan kode akses satu kali.
• Bidang teks input untuk mengumpulkan kata sandi baru.

Ketika pengguna lupa kata sandi mereka, mereka memerlukan formulir untuk memasukkan nama pengguna mereka (alamat email) untuk memulai alur reset kata sandi. Pengguna memilih tombol atau tautan Lupa Kata Sandi .

Memulai alur reset kata sandi

Untuk menangani permintaan saat pengguna memilih tombol atau tautan Lupa Kata Sandi , gunakan metode Android SDK seperti yang ditunjukkan resetPassword(username) dalam cuplikan kode berikut:

 private fun forgetPassword() { 
  CoroutineScope(Dispatchers.Main).launch { 
      try { 
        val resetPasswordResult = authClient.resetPassword( 
              username = emailAddress 
          ) 

         when (resetPasswordResult) { 
             is ResetPasswordStartResult.CodeRequired -> { 
                 // The implementation of submiteCode() please see below. 
                 submitCode(resetPasswordResult.nextState) 
             } 
              is ResetPasswordError -> {
                  // Handle errors
                  handleResetPasswordError(resetPasswordResult)
              }
         } 
     } catch (exception: MsalException) { 
          // Handle exception 
      } 
  } 
 } 

• resetPassword(username) metode memulai alur reset kata sandi dan kode sandi satu kali email dikirim ke alamat email pengguna untuk verifikasi.

• Hasil pengembalian adalah resetPassword(username) ResetPasswordStartResult.CodeRequired atau ResetPasswordError.

• Jika resetPasswordResult is ResetPasswordStartResult.CodeRequired, aplikasi perlu mengumpulkan kode akses satu kali email dari pengguna dan mengirimkannya seperti yang ditunjukkan dalam Kirim kode sandi satu kali email.

• Jika resetPasswordResult is ResetPasswordError, Android SDK menyediakan metode utilitas untuk memungkinkan Anda menganalisis kesalahan spesifik lebih lanjut: - isUserNotFound() - isBrowserRequired()

• Kesalahan ini menunjukkan bahwa operasi sebelumnya tidak berhasil, sehingga referensi ke status baru tidak tersedia. Tangani kesalahan ini seperti yang ditunjukkan di bagian Menangani kesalahan .

Kirim kode akses satu kali email

Aplikasi Anda mengumpulkan kode akses satu kali email dari pengguna. Untuk mengirimkan kode akses satu kali email, gunakan cuplikan kode berikut:

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

• Hasil pengembalian tindakan submitCode() adalah ResetPasswordSubmitCodeResult.PasswordRequired atau SubmitCodeError.

• Jika submitCodeResult is ResetPasswordSubmitCodeResult.PasswordRequired aplikasi perlu mengumpulkan kata sandi baru dari pengguna dan mengirimkannya seperti yang ditunjukkan di Kirim kata sandi baru.

• Jika pengguna tidak menerima kode akses satu kali email dalam email mereka, aplikasi dapat mengirim ulang kode sandi email satu kali. Gunakan cuplikan kode berikut untuk mengirim ulang kode akses satu kali email baru:

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

  • Hasil pengembalian tindakan resendCode() adalah ResetPasswordResendCodeResult.Success atau ResendCodeError.

  • ResendCodeError adalah kesalahan tak terduga untuk SDK. Kesalahan ini menunjukkan bahwa operasi sebelumnya tidak berhasil, sehingga referensi ke status baru tidak tersedia.

• Jika submitCodeResult is SubmitCodeError, Android SDK menyediakan metode utilitas untuk memungkinkan Anda menganalisis kesalahan tertentu lebih lanjut:

  • isInvalidCode()
  • isBrowserRequired()

  Kesalahan ini menunjukkan bahwa operasi sebelumnya tidak berhasil, sehingga referensi ke status baru tidak tersedia. Tangani kesalahan ini seperti yang ditunjukkan di bagian Menangani kesalahan .

Mengirimkan kata sandi baru

Setelah memverifikasi email pengguna, Anda perlu mengumpulkan kata sandi baru dari pengguna dan mengirimkannya. Kata sandi yang dikumpulkan aplikasi dari pengguna harus memenuhi kebijakan kata sandi Microsoft Entra. Gunakan cuplikan kode berikut:

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

• Hasil pengembalian tindakan submitPassword() adalah ResetPasswordResult.Complete atau ResetPasswordSubmitPasswordError.

• ResetPasswordResult.Complete menunjukkan alur reset kata sandi yang berhasil.

• Jika submitPasswordResult is ResetPasswordSubmitPasswordError, SDK menyediakan metode utilitas untuk menganalisis lebih lanjut jenis kesalahan tertentu yang dikembalikan: - isInvalidPassword() - isPasswordResetFailed()

  Kesalahan ini menunjukkan bahwa operasi sebelumnya tidak berhasil, sehingga referensi ke status baru tidak tersedia. Tangani kesalahan ini seperti yang ditunjukkan di bagian Menangani kesalahan .

Masuk otomatis setelah reset kata sandi

Setelah alur reset kata sandi berhasil, Anda dapat secara otomatis masuk ke pengguna Anda tanpa memulai alur masuk baru.

Objek ResetPasswordResult.Complete yang SignInContinuationState dikembalikan. menyediakan SignInContinuationState akses ke signIn() metode.

Untuk memasukkan pengguna secara otomatis setelah reset kata sandi, gunakan cuplikan kode berikut:

 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 currentState = nextState
      val actionResult = currentState.signIn()
      when (actionResult) {
          is SignInResult.Complete -> {
              fetchTokens(accountState = actionResult.resultValue)
          }
          else {
              // Handle unexpected error
          }
      }
  }
 
  private suspend fun fetchTokens(accountState: AccountState) {
      val accessTokenResult = accountState.getAccessToken()
      if (accessTokenResult is GetAccessTokenResult.Complete) {
          val accessToken =  accessTokenResult.resultValue.accessToken
          val idToken = accountState.getIdToken()
      }
 }

Untuk mengambil klaim token ID setelah masuk, gunakan langkah-langkah dalam klaim token ID Baca.

Menangani kesalahan pengaturan ulang kata sandi

Beberapa kesalahan yang diharapkan mungkin terjadi. Misalnya, pengguna mungkin mencoba mengatur ulang kata sandi dengan email yang tidak ada atau memberikan kata sandi yang tidak memenuhi persyaratan kata sandi.

Saat kesalahan terjadi, beri petunjuk kepada pengguna Anda untuk kesalahan tersebut.

Kesalahan ini dapat terjadi di awal alur reset kata sandi atau saat mengirimkan kode sandi satu kali email atau saat mengirimkan kata sandi.

Menangani kesalahan mulai pengaturan ulang kata sandi

Untuk menangani kesalahan yang disebabkan oleh mulai reset kata sandi, gunakan cuplikan kode berikut:

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

Menangani kesalahan kirim kode akses satu kali email

Untuk menangani kesalahan yang disebabkan oleh pengiriman kode akses satu kali email, gunakan cuplikan kode berikut:

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

Menangani kesalahan pengiriman kata sandi

Untuk menangani kesalahan yang disebabkan oleh pengiriman kata sandi, gunakan cuplikan kode berikut:

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

Langkah berikutnya

Tutorial: Mendukung fallback web di aplikasi Android