Kompatibilitas versi

Pemulihan Kredensial Credential Manager berfungsi di perangkat yang menjalankan Android 9 (level API 28) dan yang lebih tinggi, layanan Google Play (GMS) versi inti 24220000 atau yang lebih tinggi, dan library androidx.credentials versi 1.5.0 atau yang lebih tinggi.

Prasyarat

Siapkan server pihak tepercaya yang mirip dengan server untuk kunci sandi. Jika Anda sudah menyiapkan server untuk menangani autentikasi dengan kunci sandi, gunakan implementasi sisi server yang sama untuk memulihkan kunci.

Dependensi

Tambahkan dependensi berikut ke file build.gradle modul aplikasi Anda:

dependencies {
    implementation("androidx.credentials:credentials:1.7.0-alpha02")
    implementation("androidx.credentials:credentials-play-services-auth:1.7.0-alpha02")
}

dependencies {
    implementation "androidx.credentials:credentials:1.7.0-alpha02"
    implementation "androidx.credentials:credentials-play-services-auth:1.7.0-alpha02"
}

Pulihkan Kredensial tersedia dari versi 1.5.0 dan yang lebih tinggi dari library androidx.credentials. Namun, sebaiknya gunakan versi stabil terbaru dari dependensi jika memungkinkan.

Ringkasan

1. Buat kunci pemulihan: Untuk membuat kunci pemulihan, selesaikan langkah-langkah berikut:
   1. Buat instance Credential Manager: Buat objek CredentialManager.
   2. Mendapatkan opsi pembuatan kredensial dari server aplikasi: Kirimkan detail yang diperlukan untuk membuat kunci pemulihan dari server aplikasi ke aplikasi klien.
   3. Buat kunci pemulihan: Buat kunci pemulihan untuk akun pengguna jika pengguna login ke aplikasi Anda.
   4. Tangani respons pembuatan kredensial: Kirim kredensial dari aplikasi klien ke server aplikasi untuk diproses, dan tangani pengecualian apa pun.
2. Login dengan kunci pemulihan: Untuk login dengan kunci pemulihan, selesaikan langkah-langkah berikut:
   1. Dapatkan opsi pengambilan kredensial dari server aplikasi: Kirim detail yang diperlukan aplikasi klien untuk mengambil kunci pemulihan dari server aplikasi Anda.
   2. Dapatkan kunci pemulihan: Minta kunci pemulihan dari Pengelola Kredensial saat pengguna menyiapkan perangkat baru. Dengan begitu, pengguna dapat login tanpa input tambahan.
   3. Tangani respons pengambilan kredensial: Kirim kunci pemulihan dari aplikasi klien ke server aplikasi untuk login pengguna.
3. Menghapus kunci pemulihan.

Membuat kunci pemulihan

Aplikasi Anda harus mencakup semua kasus pengguna yang login untuk memastikan pengguna aktif memiliki kunci pemulihan yang dibuat. Buat kunci pemulihan dalam skenario berikut:

• Jika pengguna login dan kunci pemulihan belum dibuat (seperti dalam metode onCreate untuk Activity utama).
• Saat pengguna login atau menyelesaikan alur pendaftaran akun baru.

Untuk mengoptimalkan performa dan menghindari overhead pembuatan atau pemeriksaan kredensial pemulihan pada setiap login, tetapkan tanda boolean atau stempel waktu pembuatan kredensial di penyimpanan lokal, seperti has_synced_restore_credential, untuk melacak apakah kunci telah dibuat.

Buat instance Credential Manager

Gunakan konteks aktivitas aplikasi Anda untuk membuat instance objek CredentialManager.

// Use your app or activity context to instantiate a client instance of
// CredentialManager.
private val credentialManager = CredentialManager.create(context)

Mendapatkan opsi pembuatan kredensial dari server aplikasi Anda

Gunakan library yang kompatibel dengan FIDO di server aplikasi Anda untuk mengirimkan informasi yang diperlukan guna membuat kredensial pemulihan ke aplikasi klien Anda, seperti informasi tentang pengguna, aplikasi, dan properti konfigurasi tambahan. Untuk mengetahui informasi selengkapnya tentang penerapan sisi server, lihat Panduan sisi server.

Buat kunci pemulihan

Setelah mengurai opsi pembuatan kunci publik yang dikirim oleh server, buat kunci pemulihan dengan membungkus opsi ini dalam objek CreateRestoreCredentialRequest dan memanggil metode createCredential() dengan objek CredentialManager.

// createRestoreRequest contains the details sent by the server 
val response = credentialManager.createCredential(context, createRestoreRequest)

Poin penting tentang kode

• Objek CreateRestoreCredentialRequest berisi kolom-kolom berikut:

  • requestJson: Opsi pembuatan kredensial yang dikirim oleh server aplikasi dalam format Web Authentication API untuk PublicKeyCredentialCreationOptionsJSON.

  • isCloudBackupEnabled: kolom Boolean untuk menentukan apakah kunci pemulihan harus dicadangkan ke cloud. Secara default, tanda ini adalah true. Kolom ini memiliki nilai berikut:

    • true: (Direkomendasikan) Nilai ini memungkinkan pencadangan kunci pemulihan ke cloud jika pengguna telah mengaktifkan Pencadangan Google dan enkripsi end-to-end, seperti kunci layar.
    • false: Nilai ini menyimpan kunci secara lokal, bukan di cloud. Kunci tidak tersedia di perangkat baru jika pengguna memilih untuk memulihkan dari cloud.

Menangani respons pembuatan kredensial

Credential Manager API menampilkan respons jenis CreateRestoreCredentialResponse. Respons ini menyimpan respons pendaftaran kredensial kunci publik dalam format JSON.

Kirim kunci publik dari aplikasi Anda ke server pihak tepercaya. Kunci publik ini mirip dengan kunci publik yang dibuat saat Anda membuat kunci sandi. Kode yang sama yang menangani pembuatan kunci sandi di server juga dapat menangani pembuatan kunci pemulihan. Untuk mengetahui informasi selengkapnya tentang penerapan sisi server, lihat panduan untuk kunci sandi.

Selama proses pembuatan kunci pemulihan, tangani pengecualian berikut:

• CreateRestoreCredentialDomException: Pengecualian ini terjadi jika requestJson tidak valid dan tidak mengikuti format WebAuthn untuk PublicKeyCredentialCreationOptionsJSON.
• E2eeUnavailableException: Pengecualian ini terjadi jika isCloudBackupEnabled adalah true, tetapi perangkat pengguna tidak memiliki pencadangan data atau enkripsi end-to-end, seperti kunci layar.
  Untuk memastikan bahwa Kredensial Pemulihan dibuat dalam semua kasus, Anda harus menangani E2eeUnavailableException secara eksplisit dengan memanggil createCredential dengan isCloudBackupEnabled ditetapkan ke true. Jika E2eeUnavailableException ditampilkan, tangkap dan panggil createCredential lagi dengan isCloudBackupEnabled yang ditetapkan ke false.
• IllegalArgumentException: Pengecualian ini terjadi jika createRestoreRequest kosong atau bukan JSON yang valid, atau jika tidak memiliki user.id yang valid yang sesuai dengan spesifikasi WebAuthn.

Login dengan kunci pemulihan

Gunakan Pulihkan Kredensial untuk login pengguna secara diam-diam selama proses penyiapan perangkat.

Mendapatkan opsi pengambilan kredensial dari server aplikasi

Kirim opsi yang diperlukan ke aplikasi klien untuk mendapatkan kunci pemulihan dari server. Untuk panduan kunci sandi serupa untuk langkah ini, lihat Login dengan kunci sandi. Untuk mengetahui informasi selengkapnya tentang penerapan sisi server, lihat panduan autentikasi sisi server.

Mendapatkan kunci pemulihan

Untuk mendapatkan kunci pemulihan di perangkat baru, panggil metode getCredential() pada objek CredentialManager.

Sebaiknya ambil kunci pemulihan dalam kedua skenario berikut:

• Saat peluncuran pertama aplikasi di perangkat. Pemulihan kredensial dalam skenario ini tidak bergantung pada pemulihan data aplikasi.
• Jika pencadangan dan pemulihan data aplikasi diaktifkan, dapatkan kunci pemulihan segera setelah data aplikasi dipulihkan. Gunakan BackupAgent untuk mengonfigurasi pencadangan aplikasi Anda dan pastikan Anda menyelesaikan fungsi getCredential dalam callback onRestoreFinished. Jangan gunakan metode onRestore, karena hanya dipanggil untuk pencadangan key-value, sedangkan onRestoreFinished dipanggil dengan andal untuk semua jenis pemulihan pencadangan. Hal ini menghindari potensi penundaan saat pengguna membuka perangkat baru mereka untuk pertama kalinya dan memungkinkan pengguna berinteraksi dengan aplikasi tanpa menunggu mereka membuka aplikasi Anda. Misalnya, hal ini memungkinkan aplikasi Anda mengirim notifikasi kepada pengguna sebelum mereka membuka aplikasi untuk pertama kalinya di perangkat baru, yang sangat relevan untuk aplikasi pesan atau komunikasi.

Jika Anda baru membuat BackupAgent dan sebelumnya telah mengaktifkan pencadangan dengan allowBackup="true", tetapkan nilai boolean android:fullBackupOnly="true" di manifes aplikasi Anda. Hal ini memastikan perilaku pencadangan dan pemulihan aplikasi Anda tetap terjaga.

// Fetch the options required to get the restore key
val authenticationJson = fetchAuthenticationJson()

// Create the GetRestoreCredentialRequest object
val options = GetRestoreCredentialOption(authenticationJson)
val getRequest = GetCredentialRequest(listOf(options))

val response = credentialManager.getCredential(context, getRequest)

// Type-check and extract the restore credential
val credential = response.credential as RestoreCredential

API pengelola kredensial menampilkan respons jenis GetCredentialResponse. Kredensial yang terdapat dalam respons ini secara eksplisit berjenis RestoreCredential, yang menyimpan kunci publik.

Menangani respons login

Kirim kunci publik dari aplikasi ke server pihak tepercaya, yang kemudian dapat digunakan untuk login pengguna. Di sisi server, tindakan ini mirip dengan login menggunakan kunci sandi. Kode yang sama yang menangani login dengan kunci sandi di server juga dapat menangani login dengan kunci pemulihan. Untuk mengetahui informasi selengkapnya tentang penerapan sisi server untuk kunci sandi, lihat Login dengan kunci sandi.

Menghapus kunci pemulihan

Credential Manager tidak memiliki status dan tidak mengetahui aktivitas pengguna, sehingga tidak menghapus kunci pemulihan secara otomatis setelah digunakan. Untuk menghapus kunci pemulihan, panggil metode clearCredentialState(). Untuk keamanan, hapus kunci setiap kali pengguna logout. Hal ini memastikan bahwa saat pengguna membuka aplikasi di perangkat yang sama pada waktu berikutnya, pengguna akan logout dan diminta untuk login lagi.

Meng-uninstal aplikasi ditafsirkan sebagai maksud untuk menghapus kunci pemulihan yang sesuai dari perangkat tersebut, mirip dengan maksud pengguna saat logout.

Kunci pemulihan dihapus hanya dalam situasi berikut:

• Tindakan tingkat sistem: Pengguna meng-uninstal aplikasi atau menghapus datanya.
• Panggilan tingkat aplikasi: Hapus kunci secara terprogram dengan memanggil clearCredentialState() saat menangani logout pengguna dalam kode aplikasi Anda.

Saat pengguna logout dari aplikasi Anda, panggil metode clearCredentialState() pada objek CredentialManager.

// Create a ClearCredentialStateRequest object
val clearRequest = ClearCredentialStateRequest(TYPE_CLEAR_RESTORE_CREDENTIAL)

// When the user logs out, delete the restore key
val response = credentialManager.clearCredentialState(clearRequest)