Tutorial: Menambahkan pendaftaran di aplikasi seluler Android menggunakan autentikasi asli

Berlaku untuk: Penyewa tenaga kerja Penyewa eksternal (pelajari lebih lanjut)

Tutorial ini menunjukkan cara mendaftarkan pengguna menggunakan kode sandi satu kali email atau nama pengguna (email) dan kata sandi, dan mengumpulkan atribut pengguna di aplikasi seluler Android Anda menggunakan autentikasi asli.

Di tutorial ini, Anda akan:

• Daftarkan pengguna dengan menggunakan kode akses satu kali email atau nama pengguna (email) dan kata sandi.
• Kumpulkan atribut pengguna selama pendaftaran.
• Menangani kesalahan pendaftaran.

Prasyarat

• Selesaikan langkah-langkah dalam artikel Tutorial: Siapkan aplikasi Android Anda untuk autentikasi asli.
• Jika Anda ingin mengumpulkan atribut pengguna selama pendaftaran, konfigurasikan atribut pengguna saat Anda membuat alur pengguna pendaftaran dan masuk.

Mendaftarkan pengguna

Untuk mendaftarkan pengguna menggunakan kode akses satu kali email atau nama pengguna (email) dan kata sandi, Anda mengumpulkan email dari pengguna, lalu mengirim email yang berisi kode sandi satu kali email kepada pengguna. Pengguna memasukkan kode akses satu kali email yang valid untuk memvalidasi nama pengguna mereka.

Untuk mendaftarkan pengguna, Anda perlu:

1. Buat antarmuka pengguna (UI) untuk:

   • Kumpulkan email dari pengguna. Tambahkan validasi ke input Anda untuk memastikan pengguna memasukkan alamat email yang valid.
   • Kumpulkan kata sandi jika Anda mendaftar dengan nama pengguna (email) dan kata sandi.
   • Kumpulkan kode sandi satu kali dari email pengguna.
   • Jika diperlukan, kumpulkan atribut pengguna.
   • Kirim ulang kode akses satu kali (disarankan).
   • Mulai alur pendaftaran.

2. Di aplikasi Anda, tambahkan tombol, yang peristiwa pemilihannya memicu cuplikan kode berikut:

   CoroutineScope(Dispatchers.Main).launch {
        val parameters = NativeAuthSignUpParameters(username = email)
        // Assign 'password' param if you sign in with username (email) and password
        // parameters.password = password
        val actionResult: SignUpResult = authClient.signUp(parameters)
   
        if (actionResult is SignUpResult.CodeRequired) {
            val nextState = actionResult.nextState
            val submitCodeActionResult = nextState.submitCode(
               code = code
            )
            if (submitCodeActionResult is SignUpResult.Complete) {
               // Handle sign up success
            }
       }
   }
   

   • Gunakan metode instans SDK, signUp(parameters) untuk memulai alur pendaftaran.
   • Untuk mendaftar menggunakan nama pengguna (alamat email) dan kata sandi, buat instans kelas NativeAuthSignUpParameters dan tetapkan nama pengguna dan kata sandi Anda.
   • Parameter pendaftaran, username, adalah alamat email yang Anda kumpulkan dari pengguna.
   • Dalam skenario yang paling umum, signUp(parameters) mengembalikan hasil, SignUpResult.CodeRequired, yang menunjukkan bahwa SDK mengharapkan aplikasi untuk mengirimkan kode sandi satu kali email yang dikirim ke alamat email pengguna.
   • Objek SignUpResult.CodeRequired berisi referensi status baru, yang dapat kita ambil melalui actionResult.nextState.
   • Status baru memberi kita akses ke dua metode baru:
     • submitCode() mengirimkan kode sandi sekali pakai yang dikumpulkan aplikasi dari pengguna melalui email.
     • resendCode() mengirim ulang kode akses satu kali email jika pengguna tidak menerima kode.
   • submitCode() mengembalikan SignUpResult.Complete, yang menunjukkan bahwa alur selesai dan pengguna telah mendaftar.
   • signUp(parameters) juga dapat mengembalikan SignUpError untuk menunjukkan bahwa telah terjadi kesalahan.

Mengumpulkan atribut pengguna selama pendaftaran

Baik Anda mendaftarkan pengguna menggunakan kode akses satu kali email atau nama pengguna (email) dan kata sandi, Anda dapat mengumpulkan atribut pengguna sebelum akun pengguna dibuat:

• Instans NativeAuthSignUpParameters menerima parameter attributes:

      CoroutineScope(Dispatchers.Main).launch {
          val parameters = NativeAuthSignUpParameters(username = email)
          // Assign 'password' param if you sign in with username (email) and password
          // parameters.password = password
          parameters.attributes = userAttributes
          val actionResult: SignUpResult = authClient.signUp(parameters)
          //...
      }
  

• Android SDK menyediakan kelas utilitas UserAttribute.Builder yang Anda gunakan untuk membuat atribut pengguna. Misalnya, untuk mengirimkan kota dan atribut pengguna negara, gunakan cuplikan kode berikut untuk membangun variabel userAttributes:

       val userAttributes = UserAttributes.Builder ()
      .country(country) 
      .city(city) 
      .build()   
  

  Nama metode di kelas UserAttribute.Builder sama dengan nama atribut pengguna yang dapat diprogram yang mereka buat. Pelajari lebih lanjut tentang pengelola atribut Android SDK.

• Metode signUp(parameters) dapat mengembalikan SignUpResult.AttributesRequired untuk menunjukkan bahwa aplikasi perlu mengirimkan satu atau beberapa atribut yang diperlukan sebelum Microsoft Entra membuat akun. Atribut ini dikonfigurasi oleh administrator sebagai wajib di pusat admin Microsoft Entra. Microsoft Entra tidak secara eksplisit meminta atribut pengguna opsional.

• Hasil SignUpResult.AttributesRequired berisi parameter requiredAttributes. requiredAttributes adalah daftar objek RequiredUserAttribute yang berisi detail tentang atribut pengguna yang perlu dikirimkan aplikasi. Untuk menangani actionResult is SignUpResult.AttributesRequired, gunakan cuplikan kode berikut:

  val parameters = NativeAuthSignUpParameters(username = email)
  // Assign 'password' param if you sign in with username (email) and password
  // parameters.password = password
  parameters.attributes = userAttributes
  val actionResult: SignUpResult = authClient.signUp(parameters)
  
  if (actionResult is SignUpResult.AttributesRequired) {
          val requiredAttributes = actionResult.requiredAttributes 
          // Handle "attributes required" result 
          val nextState = actionResult.nextState
          nextState.submitAttributes(
              attributes = moreAttributes
          )
  }
  

Menangani kesalahan pendaftaran

Selama pendaftaran, tidak semua tindakan berhasil. Misalnya, pengguna mungkin mencoba mendaftar dengan alamat email yang sudah digunakan atau mengirimkan kode akses satu kali email yang tidak valid.

Menangani kesalahan saat memulai pendaftaran

Untuk menangani kesalahan untuk metode signUp(), gunakan cuplikan kode berikut:

 val parameters = NativeAuthSignUpParameters(username = email)
 // Assign 'password' param if you sign in with username (email) and password
 // parameters.password = password
val actionResult: SignUpResult = authClient.signUp(parameters)

if (actionResult is SignUpResult.CodeRequired) {
    // Next step: submit code
} else if (actionResult is SignUpError) {
     when {
         actionResult.isUserAlreadyExists() -> {
             // Handle "user already exists" error
         }
         else -> {
             // Handle other errors
         }
     }
}

• signUp(parameters) dapat mengembalikan SignUpError.

• SignUpError menunjukkan hasil tindakan yang tidak berhasil yang dikembalikan oleh signUp() dan tidak akan menyertakan referensi ke status baru.

• Jika actionResult is SignUpError, MSAL Android SDK menyediakan metode utilitas untuk memungkinkan Anda menganalisis kesalahan tertentu lebih lanjut:

  • Metode isUserAlreadyExists() memeriksa apakah nama pengguna telah digunakan untuk membuat akun.
  • isInvalidAttributes() memeriksa apakah satu atau beberapa atribut yang dikirimkan aplikasi gagal validasi, seperti jenis data yang salah. Parameter invalidAttributes ini berisi daftar semua atribut yang dikirimkan oleh aplikasi, tetapi gagal dalam validasi.
  • isInvalidPassword() memverifikasi bahwa kata sandi tidak valid, seperti ketika kata sandi tidak memenuhi seluruh persyaratan kompleksitas. Pelajari selengkapnya tentang kebijakan kata sandi Microsoft Entra
  • isInvalidUsername() periksa apakah nama pengguna tidak valid, misalnya ketika email pengguna tidak valid.
  • isBrowserRequired() memeriksa kebutuhan akan browser (fallback web) untuk menyelesaikan alur autentikasi. Skenario ini terjadi ketika autentikasi asli tidak cukup untuk menyelesaikan alur autentikasi. Misalnya, admin mengonfigurasi email dan kata sandi sebagai metode autentikasi, tetapi aplikasi gagal mengirim kata sandi sebagai jenis tantangan atau tidak mendukungnya. Gunakan langkah-langkah dalam Mendukung fallback web di aplikasi Android untuk menangani skenario ketika itu terjadi.
  • isAuthNotSupported() memeriksa apakah aplikasi mengirimkan jenis tantangan yang tidak didukung oleh Microsoft Entra, yaitu nilai jenis tantangan selain oob atau kata sandi . Pelajari selengkapnya tentang jenis tantangan .

  Beri tahu pengguna bahwa email sudah digunakan atau beberapa atribut tidak valid dengan menggunakan pesan ramah di UI aplikasi.

• Untuk menangani kesalahan atribut yang tidak valid, gunakan cuplikan kode berikut:

  val parameters = NativeAuthSignUpParameters(username = email)
  // Assign 'password' param if you sign in with username (email) and password
  // parameters.password = password
  parameters.attributes = userAttributes
  val actionResult: SignUpResult = authClient.signUp(parameters)
  
  if (actionResult is SignUpError && actionResult.isInvalidAttributes()) {
      val invalidAttributes = actionResult.invalidAttributes
  
      // Handle "invalid attributes" error, this time submit valid attributes
      val parameters = NativeAuthSignUpParameters(username = email)
      // Assign 'password' param if you sign in with username (email) and password
      // parameters.password = password
      parameters.attributes = userAttributes
      authClient.signUp(parameters)
  } 
  //...
  

Menangani kesalahan proses pengiriman kode sandi sekali pakai melalui email

Untuk menangani kesalahan untuk metode submitCode(), gunakan cuplikan kode berikut:

val submitCodeActionResult = nextState.submitCode(
    code = code
)
if (submitCodeActionResult is SignUpResult.Complete) {
    // Sign up flow complete, handle success state.
} else if (submitCodeActionResult is SubmitCodeError) {
    // Handle errors under SubmitCodeError
     when {
         submitCodeActionResult.isInvalidCode() -> {
             // Handle "code invalid" error
         }
         else -> {
             // Handle other errors
         }
     }
}

• submitCode() dapat mengembalikan SubmitCodeError.

• Gunakan metode isInvalidCode() untuk memeriksa kesalahan tertentu, seperti, kode yang dikirimkan tidak valid. Dalam hal ini, referensi status sebelumnya harus digunakan untuk mereperformasi tindakan.

• Untuk mengambil kode akses satu kali email baru, gunakan cuplikan kode berikut:

  val submitCodeActionResult = nextState.submitCode(
      code = code
  )
  if (submitCodeActionResult is SubmitCodeError && submitCodeActionResult.isInvalidCode()) {
      // Inform the user that the submitted code was incorrect or invalid and ask for a new code to be supplied
      val newCode = retrieveNewCode()
      nextState.submitCode(
          code = newCode
      )
  }
  

Pastikan Anda menyertakan pernyataan impor. Android Studio harus menyertakan perintah impor untuk Anda secara otomatis.

Anda telah menyelesaikan semua langkah yang diperlukan untuk berhasil mendaftarkan pengguna ke aplikasi Anda. Buat dan jalankan aplikasi Anda. Jika semuanya baik, Anda harus berhasil mendaftarkan pengguna dengan menggunakan kode sandi email satu kali atau email dan kata sandi.

Opsional: Masuk setelah proses pendaftaran

Setelah alur pendaftaran berhasil, Anda dapat masuk pengguna tanpa memulai alur masuk. Pelajari selengkapnya di artikel Tutorial : Masuk pengguna setelah mendaftar di Android.

Langkah berikutnya

Tutorial: Tambahkan fitur masuk dan keluar dengan kode sandi sekali pakai melalui email di aplikasi Android.