Memilih penerapan kunci sandi yang tepat untuk aplikasi Android Anda

Kunci sandi telah menjadi standar untuk autentikasi yang aman dan mudah digunakan, dan makin banyak layanan yang mengadopsinya di situs dan aplikasi Android. Namun, saat mulai menambahkan kunci sandi ke aplikasi Android, Anda sering kali menghadapi pertanyaan arsitektur utama: apakah Anda memanggil API native secara langsung, membuka halaman login web yang ada di tab browser, atau menjalankan kunci sandi di dalam WebView dalam aplikasi?

Ringkasan

Anda dapat mendukung kunci sandi di aplikasi Android melalui tiga pendekatan utama: Credential Manager, Tab Auth, dan WebView. Dokumentasi resmi membahas detail penerapan langkah demi langkah untuk setiap opsi. Memilih arsitektur yang meminimalkan hambatan bagi pengguna sekaligus menjaga biaya pengembangan dan pemeliharaan tetap terkendali bergantung pada pemahaman karakteristik dan batasan setiap opsi secara umum. Panduan ini menjelaskan cara memilih pendekatan yang tepat berdasarkan desain aplikasi dan infrastruktur autentikasi yang ada. Tabel berikut membandingkan pendekatan ini:

Fitur Credential Manager Tab Auth WebView
Kasus penggunaan yang direkomendasikan Aplikasi dengan UI login native Menggunakan kembali halaman login web yang ada, atau penyedia identitas (IdP) OAuth atau OpenID Connect (OIDC) Aplikasi WebView hybrid yang ada (khusus domain pihak pertama)
UI dan pengalaman pengguna Integrasi panel bawah OS native dan isi otomatis keyboard Tab browser khusus dan minimal untuk autentikasi Halaman web tersemat dengan panel bawah OS native
Isi Otomatis dan UI Bersyarat Didukung (Isi otomatis Credential Manager) Didukung (UI Bersyarat WebAuthn) Tidak didukung
Berbagi sesi dan kredensial Membagikan kunci sandi di seluruh web dan aplikasi menggunakan assetlinks.json dan rpId bersama (cookie Chrome tidak dibagikan) Membagikan cookie dan status kredensial ke Chrome (dapat dinonaktifkan menggunakan penjelajahan sementara) Membagikan kunci sandi menggunakan assetlinks.json, tetapi mengisolasi cookie dan sesi dari Chrome
Digital Asset Links (assetlinks.json) Wajib di domain web pihak tepercaya Diperlukan di domain URI pengalihan Anda untuk pengalihan HTTPS (direkomendasikan daripada skema kustom, yang tidak memerlukannya) Diperlukan di domain web pihak tepercaya (tidak dapat digunakan dengan IdP eksternal atau pihak ketiga)

Credential Manager

Jika aplikasi Android Anda memiliki layar login atau pendaftaran native, library Jetpack Credential Manager adalah pendekatan utama yang direkomendasikan.

Keunggulan utama Credential Manager adalah menyatukan kunci sandi, sandi, dan Login dengan Google dalam satu panel bawah sistem yang efisien. Saat login, pengguna menyelesaikan autentikasi biometrik dengan sekali ketuk tanpa keluar dari aplikasi Anda, sehingga mengurangi hambatan login. Meskipun pengguna menutup panel bawah awal dan mengetuk kolom input nama pengguna atau sandi, Anda dapat menggunakan PendingGetCredentialRequest untuk menampilkan kunci sandi, sandi, dan Login dengan Google langsung di keyboard atau saran isi otomatis drop-down. Penggantian ini menyediakan integrasi isi otomatis native yang setara dengan UI Bersyarat WebAuthn.

Panel bawah Credential Manager yang menampilkan opsi kunci sandi, Login dengan Google, dan sandi.
Gambar 1. Credential Manager menyatukan kunci sandi, Login dengan Google, dan sandi dalam panel bawah sistem.

Credential Manager juga memberikan kesetaraan fitur lengkap dengan kemampuan siklus proses kunci sandi web modern. Dengan Pengelola Kredensial, Anda dapat melakukan hal berikut:

Kunci sandi didukung di perangkat yang menjalankan Android 9 (level API 28) dan yang lebih tinggi, sementara kredensial lain, seperti sandi, tetap didukung di versi Android yang lebih rendah melalui layanan Google Play. Di Android 14 (level API 34) dan yang lebih tinggi, Pengelola Kredensial juga berfungsi dengan penyedia kredensial pihak ketiga yang dipilih oleh pengguna. Kemampuan tambahan, seperti integrasi isi otomatis berbasis View (PendingGetCredentialRequest) dan Signal API, memerlukan Android 15 (level API 35) dan yang lebih tinggi.

Berbagi kredensial di seluruh web dan aplikasi

Untuk memulai, ikuti Prasyarat untuk menghosting file Digital Asset Links (assetlinks.json) di domain web Anda untuk mengaitkan situs dan aplikasi Android Anda. Mengaitkan situs dan aplikasi Anda melalui assetlinks.json berarti keduanya memiliki ID pihak tepercaya (rpId) yang sama, sehingga kunci sandi yang dibuat di situs Anda di Chrome berfungsi di aplikasi Android native Anda melalui Credential Manager, dan kunci sandi yang dibuat di aplikasi Anda berfungsi di situs Anda. Credential Manager membagikan kredensial di seluruh situs dan aplikasi Anda; Anda hanya memerlukan Tab Auth jika ingin menggunakan kembali UI login web atau halaman IdP.

Seperti yang dijelaskan dalam Membuat kunci sandi, Anda juga harus mengonfigurasi server untuk memverifikasi origin aplikasi Android (android:apk-key-hash:ENCODED_SHA256_HASH, yang diformat menggunakan hash SHA-256 yang dienkode Base64URL tanpa padding dari sertifikat penandatanganan APK Anda). Jika aplikasi Anda memiliki UI native dan Anda menginginkan pengalaman yang terintegrasi dengan OS untuk login dengan kunci sandi, pilih Credential Manager.

Tab Auth

Banyak layanan mengoperasikan microservice penyedia identitas (IdP) yang dibuat di OAuth atau OpenID Connect (OIDC), atau ingin menggunakan kembali halaman login web yang mendukung kunci sandi yang ada di seluruh aplikasi seluler. Sebelumnya, aplikasi menggunakan Tab Kustom untuk alur ini. Mulai Chrome 137 dan AndroidX Browser 1.9.0, Tab Autentikasi menyediakan tab browser khusus yang disesuaikan secara khusus untuk alur autentikasi.

Tab Auth yang menampilkan antarmuka login browser minimal tanpa item menu browser tujuan umum.
Gambar 2. Tab Auth menampilkan antarmuka browser terfokus yang disesuaikan untuk alur autentikasi.

Tab Khusus standar dirancang sebagai browser dalam aplikasi untuk tujuan umum, yang menampilkan elemen UI yang tidak terkait dengan login—seperti menu berbagi, bookmark, dan Buka di Chrome—yang dapat mengalihkan perhatian pengguna. Alur ini juga memerlukan deklarasi filter intent dalam file manifes Anda untuk menerima pengalihan pasca-autentikasi, menambahkan kode boilerplate, dan memerlukan pengamanan terhadap intersepsi intent oleh aplikasi berbahaya.

Tab Auth menyelesaikan tantangan khusus autentikasi ini. Fitur ini menghapus UI browser yang tidak diperlukan, seperti tombol perkecil dan menu bagikan, serta menampilkan antarmuka yang terfokus dengan kemampuan login yang penting saja, termasuk isi otomatis kunci sandi dan sandi. Alih-alih merutekan melalui intent OS, Tab Auth mengirimkan pengalihan autentikasi langsung ke callback dalam aplikasi menggunakan skema kustom atau URL HTTPS yang diverifikasi dengan Digital Asset Links, sehingga memperkuat keamanan dan mengurangi boilerplate implementasi.

Berbagi sesi dan penggantian Tab Khusus

Secara default, Tab Auth juga membagikan cookie dan status kredensial secara langsung ke browser Chrome sistem. Dengan berbagi ini, aplikasi Anda dapat memanfaatkan sesi login aktif di Chrome dan menjalankan implementasi WebAuthn yang ada apa adanya—termasuk UI Bersyarat dan mode UI Langsung (setara web dengan preferImmediatelyAvailableCredentials Credential Manager). Sebaliknya, jika kasus penggunaan Anda memerlukan sesi autentikasi terisolasi yang tidak membagikan cookie atau histori penjelajahan ke browser, Anda dapat mengaktifkan penjelajahan sementara dengan memanggil AuthTabIntent.Builder.setEphemeralBrowsingEnabled(true).

Meskipun Anda memaketkan androidx.browser:browser (versi 1.9.0 atau yang lebih tinggi) dengan aplikasi, apakah Tab Auth berjalan saat runtime bergantung pada browser default pengguna. Jika browser default adalah versi Chrome yang lebih rendah dari 137 atau browser pihak ketiga yang tidak mendukung Tab Auth, Tab Auth akan otomatis beralih ke peluncuran Tab Khusus standar. Saat penggantian ini terjadi, pengalihan pasca-autentikasi akan ditampilkan melalui filter intent di AndroidManifest.xml seperti di Tab Khusus standar, bukan melalui callback Tab Auth (ActivityResultCallback). Dalam produksi, Google merekomendasikan untuk memeriksa dukungan browser default terlebih dahulu menggunakan CustomTabsClient.isAuthTabSupported(context, provider) untuk mencabangkan alur Anda atau mempertahankan filter intent manifes sehingga aplikasi Anda dapat menangani hasil dari jalur mana pun. Untuk contoh implementasi penggantian konkret, lihat Android Browser Helper.

Persyaratan keamanan OAuth dan OIDC

Tab Auth hanya mengamankan dan menyederhanakan saluran pengalihan sisi klien dari browser kembali ke aplikasi Anda; Tab Auth tidak otomatis mengamankan protokol OAuth atau OIDC itu sendiri. Terutama mengingat perilaku penggantian Tab Khusus, Anda harus mengikuti OAuth 2.0 untuk Aplikasi Native (RFC 8252). Secara khusus, gabungkan PKCE (Proof Key for Code Exchange, RFC 7636) menggunakan parameter code_challenge dan code_verifier untuk mencegah intersepsi kode otorisasi, validasi parameter state untuk mencegah serangan pemalsuan permintaan lintas situs (CSRF) dan fiksasi sesi, serta pembuatan dan validasi parameter nonce di OpenID Connect untuk mencegah serangan replay token ID. Dengan adanya perlindungan ini, Google merekomendasikan untuk memigrasikan arsitektur login berbasis web dari Tab Khusus standar ke Tab Auth.

WebView

Beberapa aplikasi dibuat berdasarkan arsitektur WebView hybrid, yang tidak memungkinkan pemisahan layar login saja ke UI native (Credential Manager) atau tab browser (Tab Auth). Dalam kasus tersebut, Anda dapat mengaktifkan dukungan WebAuthn langsung di dalam WebView.

Untuk menggunakan kunci sandi di WebView, tambahkan library WebKit AndroidX (androidx.webkit:webkit versi 1.12.0 atau yang lebih tinggi) dan dependensi Credential Manager (androidx.credentials:credentials dan androidx.credentials:credentials-play-services-auth) ke file build.gradle Anda. Selanjutnya, periksa dukungan fitur menggunakan WebViewFeature.isFeatureSupported(WebViewFeature.WEB_AUTHENTICATION) dan aktifkan dukungan WebAuthn secara eksplisit dengan memanggil WebSettingsCompat.setWebAuthenticationSupport(webView.settings, WebSettingsCompat.WEB_AUTHENTICATION_SUPPORT_FOR_APP). Konfigurasi ini otomatis menjembatani permintaan pembuatan dan autentikasi kunci sandi dari halaman web di WebView ke Credential Manager.

Batasan domain dan UX

Seperti integrasi Credential Manager native, Anda harus mengikuti Prasyarat untuk menghosting file Digital Asset Links (assetlinks.json) di domain web pihak tepercaya untuk mengaitkan aplikasi Anda. Server Anda menerima android:apk-key-hash:ENCODED_SHA256_HASH (hash sertifikat SHA-256 yang dienkode Base64URL) sebagai origin. Karena pendekatan ini memerlukan hosting assetlinks.json di domain pihak tepercaya untuk memercayai sertifikat penandatanganan aplikasi Android Anda, pendekatan ini hanya berfungsi jika Anda mengontrol domain web pihak tepercaya (login web pihak pertama). Jika alur autentikasi Anda mengalihkan ke IdP eksternal atau pihak ketiga tempat Anda tidak dapat menghosting assetlinks.json untuk paket aplikasi, Anda harus menggunakan Tab Auth (atau Login dengan Google native melalui Credential Manager), bukan WebView.

Perhatikan dua batasan UX dan fungsional: WebView tidak mendukung UI Bersyarat (integrasi isi otomatis mediation: "conditional" saat pengguna berfokus pada kolom input), dan tidak membagikan cookie atau sesi login dengan browser Chrome sistem. Karena batasan ini, Google merekomendasikan Credential Manager atau Tab Auth saat mendesain alur autentikasi baru. Namun, jika Anda ingin menambahkan dukungan kunci sandi ke aplikasi hybrid pihak pertama yang sudah ada tanpa perubahan arsitektur yang signifikan, Anda dapat mengintegrasikan kunci sandi dengan WebView.

Ringkasan

Memulai dari UI dan infrastruktur autentikasi aplikasi saat ini akan membantu Anda memilih pendekatan kunci sandi yang tepat:

  • Jika aplikasi Anda memiliki UI login native dan Anda menginginkan pengalaman yang terintegrasi dengan OS tanpa beralih ke layar browser, pilih Credential Manager untuk login dengan kunci sandi.
  • Jika Anda mengoperasikan microservice IdP OAuth atau OIDC, mengalihkan ke IdP eksternal, atau ingin menggunakan kembali halaman login web yang mendukung kunci sandi yang ada (termasuk UI Bersyarat) dan membagikan sesi browser aktif dengan Chrome, gunakan Tab Auth dan terapkan persyaratan keamanan di OAuth 2.0 untuk Aplikasi Native (RFC 8252)—khususnya PKCE, state, dan nonce.
  • Jika aplikasi Anda dibuat pada arsitektur WebView hybrid yang mengharuskan login tetap berada dalam layar web pihak pertama yang disematkan, gunakan WebView sambil memperhitungkan kurangnya dukungan UI Bersyarat dan cookie yang terisolasi.

Langkah berikutnya