Menerapkan Pulihkan Kredensial dengan Credential Manager

Halaman ini menjelaskan cara membuat, login dengan, dan menghapus kunci pemulihan.

Kompatibilitas versi

Restore Credentials Credential Manager berfungsi di perangkat yang menjalankan Android 9 dan yang lebih tinggi, Google Play services (GMS) core versi 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:

Kotlin

dependencies {
    implementation("androidx.credentials:credentials:1.6.0-rc01")
    implementation("androidx.credentials:credentials-play-services-auth:1.6.0-rc01")
}

Groovy

dependencies {
    implementation "androidx.credentials:credentials:1.6.0-rc01"
    implementation "androidx.credentials:credentials-play-services-auth:1.6.0-rc01"
}

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

Ringkasan

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 Anda 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.
Login dengan kunci pemulihan: Untuk login dengan kunci pemulihan, selesaikan langkah-langkah berikut:
1. Dapatkan opsi pengambilan kredensial dari server aplikasi: Kirimkan detail yang diperlukan aplikasi klien untuk mengambil kunci pemulihan dari server aplikasi Anda.
2. Mendapatkan kunci pemulihan: Meminta 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.
Menghapus kunci pemulihan.

Membuat kunci pemulihan

Buat kunci pemulihan setelah pengguna melakukan autentikasi ke aplikasi Anda—segera setelah login, atau selama peluncuran aplikasi berikutnya jika mereka sudah login.

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 untuk 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.

val credentialManager = CredentialManager.create(context)

// On a successful authentication create a Restore Key
// Pass in the context and CreateRestoreCredentialRequest object
val response = credentialManager.createCredential(context, createRestoreRequest)

Poin penting tentang kode

Objek CreateRestoreCredentialRequest berisi 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.
Perhatian: Sebaiknya setel isCloudBackupEnabled ke true. Jika cadangan cloud dinonaktifkan dan pengguna memulihkan dari cadangan cloud, panggilan untuk mengambil kunci pemulihan akan gagal. Pengguna yang memulihkan aplikasi Anda dengan cadangan cloud tidak menerima kunci pemulihan dan tidak otomatis login.

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

Anda dapat mengambil kunci pemulihan dalam skenario berikut:

(Direkomendasikan) Segera setelah data aplikasi dipulihkan. Gunakan BackupAgent untuk mengonfigurasi pencadangan aplikasi dan menyelesaikan fungsi getCredential dalam callback onRestore untuk memastikan kredensial aplikasi dipulihkan segera setelah data aplikasi dipulihkan. Hal ini menghindari potensi penundaan saat pengguna membuka perangkat baru mereka untuk pertama kalinya dan memungkinkan pengguna berinteraksi tanpa menunggu mereka membuka aplikasi Anda.
Saat peluncuran pertama aplikasi di perangkat.

Untuk mengirim notifikasi kepada pengguna sebelum mereka membuka aplikasi untuk pertama kalinya di perangkat baru, ambil kunci pemulihan dalam callback onRestore BackupAgent. Hal ini sangat relevan untuk aplikasi pesan atau komunikasi.

// Fetch the Authentication JSON from server
val authenticationJson = fetchAuthenticationJson()

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

// The restore key can be fetched in two scenarios to
// 1. On the first launch of app on the device, fetch the Restore Key
// 2. In the onRestore callback (if the app implements the Backup Agent)
val response = credentialManager.getCredential(context, getRequest)

API pengelola kredensial menampilkan respons jenis GetCredentialResponse. Respons ini menyimpan kunci publik.

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.

Hapus kunci pemulihan

Pengelola Kredensial 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)

// On user log-out, clear the restore key
val response = credentialManager.clearCredentialState(clearRequest)