Menerapkan Pulihkan Kredensial dengan Credential Manager

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

Kompatibilitas versi

Restore Credentials dari Credential Manager berfungsi di perangkat yang menjalankan Android 9 (API level 28) dan yang lebih tinggi, layanan Google Play (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 kunci pemulihan.

Dependensi

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

Kotlin

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

Groovy

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

Restore Credentials tersedia dari library androidx.credentials versi 1.5.0 dan yang lebih baru. Namun, sebaiknya gunakan versi stabil terbaru dari dependensi jika memungkinkan.

Ringkasan

  1. Membuat kunci pemulihan: Untuk membuat kunci pemulihan, selesaikan langkah-langkah berikut:
    1. Membuat 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. Menangani 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: Kirimkan detail yang diperlukan untuk mengambil kunci pemulihan dari server aplikasi Anda ke aplikasi klien.
    2. Mendapatkan kunci pemulihan: Minta kunci pemulihan dari Pengelola Kredensial saat pengguna menyiapkan perangkat baru. Hal ini memungkinkan pengguna login tanpa input tambahan.
    3. Menangani respons pengambilan kredensial: Kirim kunci pemulihan dari aplikasi klien ke server aplikasi untuk memproses login pengguna.
  3. Menghapus kunci pemulihan.

Membuat kunci pemulihan

Aplikasi Anda harus mencakup semua kasus login pengguna 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 flag boolean atau stempel waktu pembuatan kredensial di penyimpanan lokal, seperti has_synced_restore_credential, untuk melacak apakah kunci telah dibuat.

Membuat 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 mematuhi FIDO di server aplikasi Anda untuk mengirimkan informasi yang diperlukan untuk membuat kredensial pemulihan, seperti informasi tentang pengguna, aplikasi, dan properti konfigurasi tambahan, ke aplikasi klien Anda. Untuk mengetahui informasi selengkapnya tentang penerapan sisi server, lihat Panduan sisi server.

Membuat kunci pemulihan

Setelah mengurai opsi pembuatan kunci publik yang dikirim oleh server, buat kunci pemulihan dengan menggabungkan 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, flag 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 dan 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 dilempar, tangkap dan panggil createCredential lagi dengan isCloudBackupEnabled ditetapkan ke false.
  • IllegalArgumentException: Pengecualian ini terjadi jika createRestoreRequest kosong atau bukan JSON yang valid, atau jika tidak memiliki user.id valid yang sesuai dengan spesifikasi WebAuthn.

Login dengan kunci pemulihan

Gunakan Restore Credentials untuk membuat pengguna login secara otomatis tanpa gangguan selama proses penyiapan perangkat.

Mendapatkan opsi pengambilan kredensial dari server aplikasi

Kirimkan opsi yang diperlukan untuk mendapatkan kunci pemulihan dari server ke aplikasi klien. 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 pertama kali aplikasi diluncurkan 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 dan pastikan Anda menyelesaikan fungsi getCredential dalam callback onRestoreFinished. Jangan gunakan metode onRestore, karena metode ini hanya dipanggil untuk pencadangan nilai kunci, sedangkan onRestoreFinished dipanggil dengan andal untuk semua jenis pemulihan cadangan. Hal ini menghindari potensi penundaan saat pengguna membuka perangkat baru 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 membuat BackupAgent baru 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 dipertahankan.

// 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 memproses 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 bersifat stateless dan tidak mengetahui aktivitas pengguna, sehingga tidak otomatis menghapus kunci pemulihan setelah digunakan. Untuk menghapus kunci pemulihan, panggil metode clearCredentialState. Demi keamanan, hapus kunci setiap kali pengguna logout. Tindakan ini memastikan bahwa saat pengguna membuka aplikasi di perangkat yang sama, pengguna akan logout dan diminta untuk login lagi.

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

Kunci pemulihan hanya dihapus 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)