Menerapkan Pulihkan Kredensial dengan Credential Manager

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

Kompatibilitas versi

Fitur Pulihkan Kredensial Credential Manager berfungsi di perangkat yang menjalankan Android 9 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 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"
}

Pulihkan Kredensial tersedia dari library androidx.credentials versi 1.5.0 dan yang lebih tinggi. Namun, sebaiknya gunakan dependensi versi stabil terbaru 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: Kirim detail yang diperlukan aplikasi klien untuk membuat kunci pemulihan dari server aplikasi Anda.
    3. Membuat kunci pemulihan: Buat kunci pemulihan untuk akun pengguna jika pengguna login ke aplikasi Anda.
    4. Menangani respons pembuatan kredensial: Kirim kredensial dari aplikasi klien Anda ke server aplikasi Anda untuk diproses, dan tangani pengecualian apa pun.
  2. Login dengan kunci pemulihan: Untuk login dengan kunci pemulihan, selesaikan langkah-langkah berikut:
    1. Mendapatkan opsi pengambilan kredensial dari server aplikasi: Kirim detail yang diperlukan aplikasi klien untuk mengambil kunci pemulihan dari server aplikasi Anda.
    2. Mendapatkan kunci pemulihan: Minta kunci pemulihan dari Credential Manager 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 membuat pengguna login.
  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 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 sesuai dengan FIDO di server aplikasi Anda untuk mengirimkan informasi yang diperlukan aplikasi klien Anda untuk membuat kredensial pemulihan, seperti informasi tentang pengguna, aplikasi, dan properti konfigurasi tambahan. Untuk mengetahui informasi selengkapnya tentang implementasi 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-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, flag ini adalah true. Kolom ini memiliki nilai berikut:

      • true: (Direkomendasikan) Nilai ini memungkinkan pencadangan kunci pemulihan ke cloud jika pengguna mengaktifkan Pencadangan Google dan enkripsi menyeluruh, 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 berjenis CreateRestoreCredentialResponse. Respons ini menyimpan kredensial kunci publik respons pendaftaran 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 implementasi 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 menyeluruh, seperti kunci layar.
    Untuk memastikan 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 ditetapkan ke false.
  • IllegalArgumentException: Pengecualian ini terjadi jika createRestoreRequest kosong atau bukan JSON yang valid, atau jika tidak memiliki user.id yang sesuai dengan spesifikasi WebAuthn.

Login dengan kunci pemulihan

Gunakan Pulihkan Kredensial untuk membuat pengguna login secara otomatis selama proses penyiapan perangkat.

Mendapatkan opsi pengambilan kredensial dari server aplikasi

Kirim opsi yang diperlukan aplikasi klien untuk mendapatkan kunci pemulihan dari server. Untuk panduan kunci sandi yang serupa untuk langkah ini, lihat Login dengan kunci sandi. Untuk mengetahui informasi selengkapnya tentang implementasi 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:

  • Pada peluncuran pertama aplikasi di perangkat. Pemulihan kredensial dalam skenario ini independen dari 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 metode ini hanya dipanggil untuk pencadangan nilai kunci, 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 mengirimkan notifikasi kepada pengguna sebelum mereka membuka aplikasi untuk pertama kalinya di perangkat baru, yang sangat relevan untuk aplikasi pesan atau komunikasi.
// 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

Credential Manager API menampilkan respons berjenis 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 membuat pengguna login. 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 implementasi 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 otomatis menghapus kunci pemulihan 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 lain waktu, pengguna akan logout dan diminta untuk login lagi.

Menghapus aplikasi diinterpretasikan sebagai intent untuk menghapus kunci pemulihan yang sesuai dari perangkat tersebut, mirip dengan intent pengguna saat logout.

Kunci pemulihan hanya dihapus dalam situasi berikut:

  • Tindakan tingkat sistem: Pengguna menghapus 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)