Kunci Sandi Aplikasi Native: Integrasi Native vs WebView

Catatan: System dan Embedded WebView sering digabungkan di mana System WebView menangani login (dengan berbagi kredensial otomatis), kemudian Embedded WebView merender pengelolaan kunci sandi dalam pengaturan.

Faktor Keputusan Utama:

• Login berbasis OAuth? → System WebView (ASWebAuthenticationSession, Chrome Custom Tabs)
• Ingin menggunakan kembali autentikasi web dalam shell native? → Embedded WebView (WKWebView, Android WebView dengan WebKit 1.12.1+)
• Membangun aplikasi native-first? → Implementasi Native (Apple AuthenticationServices, Google Credential Manager)

Platform seluler modern menyediakan tiga pendekatan berbeda untuk mengintegrasikan kunci sandi ke dalam aplikasi native Anda, masing-masing dengan kelebihan dan kekurangan untuk pengalaman pengguna, kompleksitas teknis, dan kompatibilitas OAuth:

1. Implementasi Native: Bangun alur kunci sandi secara langsung ke dalam UI aplikasi Anda menggunakan platform API (iOS AuthenticationServices, Android Credential Manager). Memberikan pengalaman pengguna terbaik dengan autentikasi biometrik yang mulus, tetapi membutuhkan upaya implementasi teknis menengah hingga tinggi.

2. System WebView: Gunakan komponen browser platform (iOS ASWebAuthenticationSession / SFSafariViewController, Android Chrome Custom Tabs) untuk menangani autentikasi. Sangat baik untuk alur login berbasis OAuth dan berbagi kredensial dengan browser sistem.

3. Embedded WebView: Sematkan tampilan web yang dapat disesuaikan (iOS WKWebView, Android WebView) dalam aplikasi Anda untuk menggunakan kembali autentikasi web dengan kerangka aplikasi native. Memberikan tampilan seperti native tanpa bilah URL dan kontrol penuh atas UI tampilan web. Memerlukan penyiapan tambahan termasuk izin dan entitlement (iOS), dan konfigurasi WebView dengan AndroidX WebKit 1.12.1+ (Android) untuk mengaktifkan fungsi kunci sandi.

Pilihan yang tepat bergantung pada arsitektur autentikasi aplikasi Anda, apakah Anda menggunakan penyedia OAuth, seberapa banyak kontrol yang Anda butuhkan atas UI, dan apakah Anda membangun native-first atau menggunakan kembali komponen web.

Whitepaper Passkey Enterprise. Panduan praktis, pola peluncuran, dan KPI untuk program passkeys.

Dapatkan whitepaper

Implementasi kunci sandi native memberikan pengalaman pengguna yang optimal, dengan alur autentikasi yang dibangun langsung ke dalam UI aplikasi Anda menggunakan API spesifik platform. Pengguna mendapat manfaat dari dialog native platform, verifikasi biometrik yang mulus, dan waktu login tercepat yang memungkinkan.

Kapan memilih Implementasi Native:

• Membangun aplikasi native baru atau memfaktorkan ulang autentikasi ke layar native
• Menginginkan pengalaman pengguna terbaik dengan autentikasi instan dan senyap
• Perintah kunci sandi otomatis saat aplikasi dimulai: Implementasi native dapat menggunakan preferImmediatelyAvailableCredentials untuk menampilkan hamparan kunci sandi secara otomatis ketika kunci sandi tersedia, memberikan pengalaman login tercepat tanpa perlu memasukkan pengidentifikasi
• Memerlukan kontrol penuh atas UI dan alur autentikasi
• Bersedia berinvestasi dalam implementasi spesifik platform (iOS Swift, Android Kotlin)

Keuntungan Utama: preferImmediatelyAvailableCredentials()

Implementasi native dapat memanfaatkan preferImmediatelyAvailableCredentials() untuk membuat hamparan kunci sandi otomatis yang muncul segera saat aplikasi dimulai ketika kunci sandi tersedia. Alur tanpa nama pengguna ini memberikan pengalaman login tercepat—pengguna melihat kunci sandi mereka secara instan tanpa memasukkan pengidentifikasi terlebih dahulu. Kemampuan ini eksklusif untuk implementasi native dan tidak tersedia di varian WebView.

Diagram di bawah ini mengilustrasikan bagaimana autentikasi native memberikan perjalanan pengguna yang lebih cepat dibandingkan dengan pendekatan Conditional UI WebView:

Hamparan otomatis native memberikan UX superior dengan tingkat penggunaan kunci sandi yang lebih tinggi karena autentikasi dimulai segera setelah aplikasi diluncurkan, sedangkan implementasi WebView mengharuskan pengguna berinteraksi dengan kolom input terlebih dahulu.

Tinjauan Persyaratan Teknis:

Integrasi kunci sandi native membutuhkan kepercayaan kriptografi antara aplikasi dan domain web Anda. Tanpanya, OS akan menolak semua operasi WebAuthn. Persyaratan utama:

1. File Asosiasi Aplikasi-Domain yang dihosting di /.well-known/
2. Relying Party ID yang Benar yang cocok dengan domain web Anda
3. Kemampuan Spesifik Platform (dirinci di Bagian 4)

Manfaat utamanya: kunci sandi yang dibuat di situs web Anda berfungsi mulus di aplikasi Anda dan sebaliknya.

Menerapkan kunci sandi secara native di iOS melibatkan kerangka kerja AuthenticationServices Apple, yang menyediakan API untuk operasi WebAuthn:

Komponen Utama:

• ASAuthorizationController: Mengelola alur autentikasi
• ASAuthorizationPlatformPublicKeyCredentialProvider: Membuat permintaan kunci sandi
• Tiga mode UI yang berbeda untuk menangani login kunci sandi:
  • Login kolom teks: Kolom nama pengguna tradisional dengan login kunci sandi yang dimulai saat tombol kirim diklik
  • Hamparan modal kunci sandi: Dialog OS yang mencantumkan kunci sandi yang tersedia
  • Conditional UI: Saran kunci sandi di bilah QuickType di atas keyboard

Kiat Pengembangan

• Caching AASA: Apple melakukan cache file AASA secara agresif (hingga 24 jam), yang dapat menyulitkan pengujian. Solusi: Aktifkan Mode Pengembang di perangkat pengujian Anda dan tambahkan ?mode=developer ke URL AASA Anda untuk memaksa pengambilan file baru
• Pengujian Kinerja: Uji dengan akun iCloud yang berisi ratusan kredensial untuk mengamati latensi dunia nyata. Hamparan sistem mungkin menunjukkan sedikit penundaan dengan banyak kunci sandi yang tersimpan

Implementasi kunci sandi native Android menggunakan Credential Manager API (atau FIDO2 API yang lebih lama untuk kompatibilitas ke belakang):

Komponen Utama:

• CredentialManager: API sentral untuk semua operasi kredensial
• CreatePublicKeyCredentialRequest: Untuk pendaftaran kunci sandi
• GetCredentialRequest: Untuk autentikasi kunci sandi
• Dua mode UI utama:
  • Login kolom teks: Kolom nama pengguna tradisional dengan login kunci sandi yang dimulai saat tombol kirim diklik
  • Hamparan modal kunci sandi: Dialog OS yang mencantumkan kunci sandi yang tersedia

Catatan: Android saat ini tidak memiliki saran keyboard Conditional UI seperti iOS di aplikasi native (meskipun Conditional UI berfungsi di aplikasi web)

Menerapkan kunci sandi secara native memiliki tantangan penting dan pelajaran yang bisa diambil: Mengintegrasikan pada tingkat OS dapat memunculkan masalah di berbagai perangkat dan versi OS.

1. Misalnya, tim kami menemui masalah seperti caching file apple-app-site-association yang agresif dari Apple (digunakan untuk menautkan kredensial aplikasi/web) dan perbedaan UI yang tidak kentara pada beberapa perintah biometrik OEM Android tertentu.
2. Selain itu, pertimbangkan bahwa dalam beberapa skenario perusahaan, perangkat yang dikelola mungkin menonaktifkan sinkronisasi kunci sandi berdasarkan kebijakan. Di lingkungan korporat tempat sinkronisasi iCloud Keychain atau Google Password Manager dimatikan, kunci sandi menjadi terikat pada perangkat dan tidak akan berpindah - skenario penting yang harus direncanakan (misalnya memastikan pengguna masih dapat login jika mereka mendapatkan ponsel baru).
3. Selain itu, aplikasi pengelola kredensial pihak ketiga dapat memengaruhi alur tersebut. Misalnya, jika pengguna memiliki pengelola kata sandi seperti 1Password yang ditetapkan sebagai penyedia kredensial yang aktif, aplikasi tersebut sering kali akan mencegat pembuatan dan penyimpanan kunci sandi, mengambil prioritas di atas pengelola kredensial native platform.

Walaupun Anda dapat mengimplementasikan kunci sandi menggunakan API platform dasar, SDK yang dibuat khusus secara signifikan mempercepat pengembangan dengan menangani kompleksitas WebAuthn, edge cases, dan menyediakan telemetri bawaan. SDK juga menawarkan antarmuka yang dapat di-mock untuk pengujian unit (penting karena Anda tidak dapat menguji biometrik di simulator).

Rekomendasi: Untuk implementasi native, kami menyarankan menggunakan Corbado SDKs (iOS Swift Passkey SDK, Android Kotlin Passkey SDK) yang menangani berbagai kasus edge case yang ditemukan melalui penerapan produksi, memberikan telemetri tambahan dan pengujian.

Igor Gjorgjioski

Head of Digital Channels & Platform Enablement, VicRoads

We hit 80% mobile passkey activation across 5M+ users without replacing our IDP.

See how VicRoads scaled passkeys to 5M+ users — alongside their existing IDP.

Read the case study

System WebView menggunakan komponen browser native platform untuk menangani autentikasi di dalam aplikasi Anda. Tidak seperti implementasi yang sepenuhnya native, System WebView menampilkan konten web menggunakan browser sistem yang sebenarnya (Safari di iOS, Chrome di Android), memelihara cookie bersama, kredensial tersimpan, dan indikator keamanan browser yang sudah dikenal.

Kapan memilih System WebView:

• Aplikasi Anda menggunakan login berbasis OAuth: System WebView adalah pendekatan yang disarankan untuk alur OAuth2/OIDC, menyediakan autentikasi yang aman
• Autentikasi berbasis web yang sudah ada yang ingin Anda gunakan kembali di aplikasi seluler
• Perlu mendukung beberapa metode autentikasi (kata sandi, login sosial, kunci sandi) tanpa membangun ulang secara native
• Ingin memelihara basis kode autentikasi tunggal di seluruh web dan seluler

Keuntungan Utama:

• Kompatibilitas OAuth: Dibuat khusus untuk alur autentikasi OAuth/OIDC
• Indikator keamanan: Pengguna melihat URL aktual dan sertifikat SSL, membangun kepercayaan
• Upaya implementasi rendah: Kode native minimal yang diperlukan
• UX konsisten: Antarmuka browser yang familier yang sudah dipercaya pengguna

Komponen Platform:

• iOS: ASWebAuthenticationSession (disarankan untuk alur autentikasi) atau SFSafariViewController (penjelajahan umum)
• Android: Chrome Custom Tabs (CCT)

Perusahaan besar seperti Google dan GitHub mengadopsi pendekatan ini untuk menambahkan login kunci sandi ke aplikasi seluler mereka melalui hamparan WebView di halaman autentikasi web yang ada. Ini berfungsi dengan baik bila pembuatan ulang autentikasi native sepenuhnya belum memungkinkan.

iOS menyediakan dua komponen System WebView utama untuk autentikasi:

ASWebAuthenticationSession (Disarankan untuk Autentikasi):

• Dibuat khusus untuk OAuth/OIDC dan alur login aman
• Secara otomatis meminta pengguna bahwa aplikasi ingin mengautentikasi
• Berbagi cookie dan kredensial dengan Safari
• Mendukung kunci sandi melalui iCloud Keychain

SFSafariViewController (Penjelajahan Umum):

• Pengalaman Safari penuh di dalam aplikasi
• Menampilkan bilah URL dan indikator keamanan
• Tidak berbagi cookie Safari di iOS 11+; gunakan ASWebAuthenticationSession bila berbagi sesi Safari diperlukan
• Kurang dapat disesuaikan tetapi lebih tepercaya bagi pengguna

Jika aplikasi Anda menggunakan login berbasis OAuth, ASWebAuthenticationSession adalah pilihan yang disarankan karena dirancang khusus untuk skenario autentikasi dan memberikan keseimbangan terbaik antara keamanan dan pengalaman pengguna.

Chrome Custom Tabs (CCT) memberikan pengalaman autentikasi yang didukung Chrome dalam aplikasi Anda:

Fitur Utama:

• Berbagi cookie dan kredensial dengan browser Chrome
• Menampilkan URL dan indikator keamanan
• Dapat menyesuaikan warna bilah alat dan pencitraan merek
• Pre-warming untuk waktu muat yang lebih cepat

Integrasi OAuth: Chrome Custom Tabs adalah ekuivalen Android dari ASWebAuthenticationSession iOS, memberikan dukungan OAuth yang sangat baik sambil mempertahankan akses ke kunci sandi yang disimpan.

Coba passkeys dalam demo live.

Coba passkeys

Embedded WebView memberikan kontrol penuh atas perenderan konten web di dalam aplikasi Anda, memungkinkan manipulasi langsung cookie, sesi, dan navigasi tanpa bilah URL. Namun, kontrol ini disertai dengan persyaratan teknis tambahan untuk mengaktifkan fungsionalitas kunci sandi.

Kapan memilih Embedded WebView:

• Pengalaman seperti native: Aplikasi Anda telah menyematkan autentikasi di dalam tampilan web yang disesuaikan untuk mempertahankan tampilan dan nuansa native, dan Anda ingin menjaga pengalaman pengguna yang konsisten ini
• Membutuhkan kontrol sesi/cookie: Aplikasi Anda memerlukan manipulasi langsung dari token autentikasi dan status sesi setelah autentikasi OAuth selesai
• Alur autentikasi yang ada di mana autentikasi System WebView mengembalikan kode autentikasi tetapi tanpa sesi dalam konteks yang disematkan
• Harus mempertahankan status terautentikasi di beberapa layar web yang disematkan
• Hanya autentikasi pihak pertama: Aplikasi Anda menangani autentikasi secara langsung, untuk implementasi kunci sandi pihak ketiga lihat di sini
• AndroidX WebKit 1.12.1+ dengan deteksi fitur runtime
• Menerima batasan Conditional UI untuk Login (tidak didukung di Embedded WebView), tidak relevan untuk pengaturan pengelolaan

Konteks Penting:

Banyak aplikasi menggunakan pendekatan hybrid: System WebView menangani autentikasi OAuth awal (di mana kunci sandi berfungsi dengan mulus), lalu beralih ke Embedded WebView untuk pasca-autentikasi guna mengelola kunci sandi di pengaturan. Tantangan muncul ketika mencoba menggunakan kunci sandi secara langsung di dalam Embedded WebView.

Persyaratan Teknis:

Embedded WebView memerlukan penyiapan tambahan dibandingkan dengan System WebView:

1. iOS: Entitlement Associated Domains, konfigurasi file AASA
2. Android: AndroidX WebKit 1.12.1+ dengan konfigurasi WebView WebAuthn (deteksi fitur diperlukan)
3. Keduanya: File asosiasi well-known dikonfigurasi dengan benar dan Digital Asset Links

Komponen Platform:

• iOS: WKWebView
• Android: android.webkit.WebView

Pertukaran:

• Kompleksitas menengah: Memerlukan konfigurasi WebView (Android WebKit 1.12.1+) dan penyiapan entitlement (iOS)
• Adopsi kunci sandi lebih rendah: Pengguna mungkin menemui lebih banyak gesekan dibandingkan dengan native
• Conditional UI tidak didukung: Isian otomatis kunci sandi di kolom input tidak berfungsi di Android Embedded WebView
• Dukungan platform terbatas: Beberapa fitur mungkin tidak bekerja secara konsisten (mis. pembuatan kunci sandi otomatis)

Saat menerapkan kunci sandi melalui WebView, memahami perbedaan antara System WebView dan Embedded WebView sangat penting. Tiga pendekatan yang diuraikan di atas (Implementasi Native, System WebView, dan Embedded WebView) masing-masing melayani kasus penggunaan yang berbeda.

Di iOS, Anda memiliki beberapa opsi untuk menampilkan konten web di dalam aplikasi:

• WKWebView adalah WebView yang dapat disesuaikan yang merupakan bagian dari kerangka kerja WebKit (diperkenalkan pada iOS 8). Ini memberi Anda banyak kontrol atas tampilan dan perilaku konten web.
• SFSafariViewController adalah view controller yang disediakan oleh Apple yang bertindak sebagai browser Safari ringan di dalam aplikasi Anda. Ia menggunakan mesin Safari. Di iOS 11+, ia memiliki penyimpanan cookie yang terpisah dan tidak berbagi cookie Safari. Gunakan ASWebAuthenticationSession saat berbagi sesi Safari diperlukan.
• SFAuthenticationSession / ASWebAuthenticationSession adalah sesi autentikasi web khusus (tersedia sejak iOS 11/12) yang ditujukan khusus untuk OAuth/OpenID atau alur login aman lainnya. Keduanya juga memanfaatkan Safari di belakang layar, tetapi difokuskan pada alur autentikasi dan secara otomatis menangani hal-hal seperti cookie bersama dan Single Sign-On (SSO).

Di Android, pilihan utamanya adalah:

• Android WebView adalah widget WebView standar (android.webkit.WebView), yang pada dasarnya adalah browser mini yang dapat disematkan di aktivitas Anda. Ia sangat dapat disesuaikan tetapi berjalan di proses aplikasi Anda.
• Chrome Custom Tabs (CCT) adalah fitur yang membuka tab berdaya Chrome di dalam konteks aplikasi Anda. Custom Tabs muncul sebagai bagian dari aplikasi Anda tetapi diberdayakan oleh browser Chrome (jika diinstal) dengan fitur seperti pra-pemuatan, cookie bersama, dan bilah URL yang familier untuk kepercayaan pengguna.

Di bagian selanjutnya, kita akan menggali lebih dalam jenis-jenis WebView untuk iOS dan Android ini, dan membahas mana yang mungkin paling cocok untuk alur autentikasi kunci sandi.

Berlangganan Passkeys Substack kami untuk berita terbaru.

Berlangganan

Platform Apple menyediakan tiga opsi WebView yang tercantum di atas. Pilihan Anda akan memengaruhi seberapa lancar kunci sandi dapat digunakan di dalam aplikasi:

Untuk menguji berbagai perilaku WebView di iOS, kami merekomendasikan aplikasi WebView - WKWebView and UIWebView rendering.

WKWebView adalah komponen WebView serbaguna untuk iOS. Pengembang dapat menyematkan WKWebView untuk merender konten web dengan kontrol tingkat tinggi atas UI dan perilakunya. WKWebView menggunakan mesin rendering yang sama dengan Safari, jadi sangat efisien dan mendukung fitur web modern. Secara teori, WKWebView dapat menangani WebAuthn (dan karenanya kunci sandi) jika dikonfigurasi dengan benar, tetapi perhatikan bahwa beberapa fitur browser lanjutan mungkin dibatasi untuk keamanan. Satu hal yang perlu diwaspadai adalah bahwa WKWebView secara default tidak berbagi cookie atau data keychain dengan Mobile Safari. Pengguna mungkin harus login kembali karena sesi WebView mereka terisolasi dari sesi Safari. Juga, karena konten WKWebView dapat disesuaikan sepenuhnya oleh aplikasi, pengguna tidak melihat bilah alamat atau UI Safari – yang bagus untuk pencitraan merek, tetapi berarti pengguna memiliki lebih sedikit petunjuk untuk memverifikasi keabsahan halaman (kekhawatiran untuk anti-phising). Beberapa aplikasi bahkan telah menyalahgunakan WKWebView untuk menyuntikkan skrip atau mengubah konten (mis. TikTok diketahui menyuntikkan JS pelacakan melalui browser dalam aplikasi mereka), jadi seseorang harus berhati-hati untuk menggunakan WKWebView dengan cara yang aman dan tepercaya.

SFSafariViewController menyediakan pengalaman Safari dalam aplikasi. Saat Anda membuka URL dengan SFSafariViewController, hal ini hampir seperti membukanya di browser Safari yang sebenarnya, kecuali pengguna tetap berada di dalam UI aplikasi Anda. Keuntungan untuk kunci sandi signifikan: karena ini pada dasarnya adalah Safari, iCloud Keychain dan kunci sandi tersimpan milik pengguna dapat diakses. Perhatikan bahwa cookie tidak dibagikan di iOS 11+. Ini berarti jika pengguna telah memiliki kunci sandi untuk situs Anda, Safari dapat menemukannya dan bahkan menampilkan isian otomatis Conditional UI untuk login yang mudah. SFSafariViewController kurang dapat disesuaikan (Anda tidak dapat banyak mengubah bilah alatnya), tetapi ia secara otomatis menangani banyak fitur keamanan dan privasi. Bilah URL ditampilkan, lengkap dengan ikon gembok untuk HTTPS, yang memberi pengguna keyakinan bahwa mereka berada di domain yang benar. Secara umum, SFSafariViewController dianggap lebih aman daripada WKWebView biasa dan lebih mudah diimplementasikan (Apple menyediakannya sebagai drop-in). Pengorbanan utamanya adalah Anda mengorbankan sebagian kontrol atas tampilan dan nuansa. Untuk alur autentikasi, hal itu biasanya dapat diterima. Prioritas di sini adalah keamanan dan kemudahan login, di mana SFSafariViewController unggul dengan menggunakan konteks Safari.

SFAuthenticationSession / ASWebAuthenticationSession – Kelas-kelas ini (yang terakhir adalah nama ramah-Swift yang lebih baru) dibuat khusus untuk alur login seperti OAuth atau OpenID Connect. Saat Anda perlu mengautentikasi pengguna melalui halaman web (mungkin ke IdP eksternal), sesi ini adalah pilihan yang disarankan di iOS. Keduanya sangat mirip dengan SFSafariViewController dalam hal memanfaatkan browser Safari di latar belakang dan berbagi cookie/penyimpanan dengan Safari. Perbedaan utamanya adalah bahwa SFAuthenticationSession akan selalu meminta pengguna bahwa aplikasi ingin mengautentikasi menggunakan halaman web (untuk kesadaran pengguna) dan ia akan secara otomatis menggunakan sesi Safari pengguna yang sudah ada jika tersedia.

Manfaatnya adalah pengalaman SSO yang mulus – jika pengguna sudah login ke penyedia di Safari, sesi ini dapat menggunakan cookie tersebut untuk menghindari login lagi. Untuk kunci sandi, hal ini penting karena itu berarti setiap kredensial kunci sandi yang tersimpan di Safari/iCloud Keychain dapat digunakan di sini juga. Panduan resmi Apple adalah menggunakan ASWebAuthenticationSession untuk apa pun yang menyerupai alur login. Kelebihannya adalah privasi yang ditingkatkan (aplikasi Anda tidak pernah melihat kredensial atau cookie, Safari menanganinya) dan dukungan SSO bawaan. Kekurangannya adalah bahwa ia terbatas pada alur autentikasi (Anda tidak akan menggunakannya hanya untuk merender konten web arbiter di aplikasi Anda). Singkatnya, jika Anda memilih pendekatan WebView di iOS, ASWebAuthenticationSession biasanya adalah pilihan terbaik untuk mengimplementasikan kunci sandi karena ia aman, berbagi status dengan Safari dan dibuat khusus untuk autentikasi.

Lihat berapa banyak orang yang benar-benar memakai passkeys.

Lihat data adopsi

Di Android, keputusan WebView adalah antara WebView klasik dan Chrome Custom Tabs:

Untuk menguji berbagai perilaku WebView di Android, kami merekomendasikan aplikasi WebView vs Chrome Custom Tabs.

Android WebView (android.webkit.WebView) adalah komponen yang memungkinkan Anda menyematkan halaman web di tata letak aktivitas Anda. Ia mirip dengan WKWebView di mana ia memberi Anda kendali penuh: Anda dapat mencegat navigasi, menyuntikkan JavaScript, menyesuaikan UI, dsb. Ia juga berjalan di dalam proses aplikasi Anda. Menggunakan WebView untuk kunci sandi berarti aplikasi Anda memuat halaman login web Anda, dan halaman itu dapat memulai upacara kunci sandi WebAuthn. WebView Android modern mendukung WebAuthn (asalkan implementasi WebView perangkat mutakhir via Android System WebView atau komponen Chrome). Satu pertimbangan utama: secara default, WebView Android tidak berbagi cookie atau kredensial yang tersimpan dengan browser Chrome pengguna. Jadi kunci sandi apa pun yang dibuat atau digunakan di WebView mungkin tidak diketahui oleh Chrome, dan sebaliknya. Isolasi ini mungkin baik untuk keamanan (aplikasi Anda tidak dapat membaca cookie browser), tetapi dapat memaksa pengguna untuk login kembali jika mereka telah terautentikasi di Chrome. Masalah lainnya adalah kepercayaan. WebView biasa tidak menampilkan URL atau ikon kunci SSL, sehingga pengguna harus sepenuhnya memercayai aplikasi Anda agar tidak memphising mereka. Google bahkan telah melarang penggunaan WebView untuk login OAuth Google karena potensi risiko phising. Dari sisi kinerja, WebView cukup baik, tetapi bisa lebih lambat atau lebih intensif memori daripada menggunakan browser bawaan pengguna, terutama jika memuat halaman yang berat.

Chrome Custom Tabs (CCT) adalah pendekatan hybrid. Keduanya memungkinkan aplikasi Anda membuka halaman yang dirender Chrome yang terlihat seperti bagian dari aplikasi Anda. Anda dapat menyesuaikan warna bilah alat, menambahkan logo aplikasi, dsb., tetapi konten dirender oleh Chrome di proses yang terpisah. Untuk kunci sandi, CCT memiliki beberapa manfaat: keduanya berbagi cookie dan kredensial pengguna dengan Chrome, yang berarti jika pengguna memiliki kunci sandi yang disimpan melalui Chrome (Google Password Manager), Custom Tab dapat mengaksesnya. Pengguna juga akan melihat URL yang sebenarnya dan indikator keamanan, yang membangun kepercayaan. Kinerja sering kali lebih baik – Chrome dapat di-"warm up" di latar belakang untuk pemuatan yang lebih cepat. Dan yang penting, keamanannya kuat: karena pada dasarnya ini adalah aplikasi Chrome, hal-hal seperti Google Safe Browsing melindungi sesi tersebut, dan aplikasi Anda tidak dapat menyuntikkan skrip sembarangan ke dalam halaman (mencegah serangan tertentu).

Kelemahannya adalah bahwa hal itu mengharuskan pengguna memiliki Chrome (atau browser yang didukung) terinstal dan mutakhir. Mayoritas pengguna Android memilikinya, tetapi di beberapa perangkat di area tertentu, ini bisa menjadi masalah. Secara keseluruhan, jika Anda memilih pendekatan web tertanam di Android, Chrome Custom Tabs direkomendasikan untuk alur kunci sandi, karena memberikan keseimbangan integrasi dan keamanan yang baik. Kenyataannya, hal ini serupa dengan SFSafariViewController/ASWebAuthSession dari iOS dalam banyak hal – memanfaatkan browser bawaan untuk autentikasi.

(Tambahan: WKWebView vs SFSafariViewController Apple dan WebView vs CCT Android memiliki banyak paralel. Keduanya Safari VC dan Chrome Tabs berbagi keadaan browser dan memberikan keamanan lebih baik, sementara WKWebView/Android WebView memberikan kontrol lebih tetapi mengisolasi konten web. Untuk kunci sandi, berbagi status (cookie, penyimpanan kredensial) biasanya lebih disukai sehingga kunci sandi dapat diakses dan dibuat dengan mulus.)

Apa pun pendekatan implementasi yang Anda pilih, persyaratan teknis tertentu harus dipenuhi untuk mengaktifkan fungsionalitas kunci sandi. Bagian ini memberikan panduan komprehensif mengenai mengonfigurasi file asosiasi well-known, entitlement iOS, dan konfigurasi WebView Android.

Catatan tentang Perangkat yang Dikelola: Perilaku kunci sandi berubah secara signifikan pada perangkat yang dikelola tempat kebijakan Mobile Device Management (MDM) mengontrol penyimpanan kredensial. Untuk menguji kunci sandi di perangkat yang dikelola, lihat Kunci Sandi pada Perangkat iOS & Android yang Dikelola.

Alur Native dan Embedded WebView memerlukan file asosiasi untuk menetapkan kepercayaan kriptografi antara aplikasi dan domain web Anda. System WebView (ASWebAuthenticationSession) dan Chrome Custom Tabs tidak memerlukan asosiasi aplikasi-ke-situs.

File AASA membangun hubungan antara aplikasi iOS Anda dan domain web Anda, memungkinkan kunci sandi berfungsi di kedua platform.

Lokasi File: https://domainanda.com/.well-known/apple-app-site-association

Persyaratan Konfigurasi:

• Hosting di /.well-known/apple-app-site-association di domain Anda
• Sajikan melalui HTTPS dengan sertifikat SSL yang valid
• Content-Type: application/json
• Tanpa redirect pada jalur .well-known
• Sertakan ID Tim dan ID Bundel Aplikasi Anda

Contoh File AASA:

{
    "webcredentials": {
        "apps": ["TEAMID123.com.example.app"]
    }
}

Caching dan Pengujian AASA:

Apple secara agresif melakukan cache pada file AASA (hingga 24-48 jam) menggunakan CDN, yang dapat menyulitkan pengembangan dan pengujian. Untuk mengabaikan cache selama pengembangan:

1. Aktifkan Mode Pengembang di perangkat pengujian Anda
2. Tambahkan ?mode=developer ke domain terkait Anda di Xcode
3. Ini memaksa iOS untuk mengambil file AASA terbaru langsung dari server Anda

⚠️ Penting: JANGAN gunakan ?mode=developer dalam rilis produksi. Parameter ini hanya untuk pengembangan—menggunakannya di produksi akan mencegah iOS mendeteksi file AASA Anda dengan benar, yang merusak fungsi kunci sandi.

Validasi: Gunakan Validator AASA Apple untuk memverifikasi konfigurasi Anda.

Android menggunakan Digital Asset Links untuk memverifikasi hubungan antara aplikasi dan situs web Anda.

Lokasi File: https://domainanda.com/.well-known/assetlinks.json

Persyaratan Konfigurasi:

• Hosting di /.well-known/assetlinks.json di domain Anda
• Sajikan melalui HTTPS dengan sertifikat valid
• Content-Type: application/json
• Sertakan sidik jari SHA256 aplikasi Anda (dari sertifikat penandatanganan)

Contoh File assetlinks.json:

[
    {
        "relation": [
            "delegate_permission/common.handle_all_urls",
            "delegate_permission/common.get_login_creds"
        ],
        "target": {
            "namespace": "android_app",
            "package_name": "com.example.app",
            "sha256_cert_fingerprints": [
                "AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99:AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99"
            ]
        }
    }
]

Validasi: Gunakan Pembuat Digital Asset Links Google untuk membuat dan memverifikasi konfigurasi Anda.

Aplikasi iOS memerlukan entitlement yang tepat untuk mengakses fungsi kunci sandi. Persyaratannya sedikit berbeda berdasarkan pendekatan implementasi Anda.

File entitlement (sering dinamai Runner.entitlements di aplikasi Flutter atau AplikasiAnda.entitlements di proyek iOS native) mendefinisikan izin khusus dan kemampuan yang diberikan oleh sistem Apple. Untuk kunci sandi, file ini mengonfigurasi Associated Domains.

Lokasi File: Biasanya di proyek Xcode Anda di ios/Runner/Runner.entitlements

Implementasi Native dan Embedded WebView memerlukan kemampuan Associated Domains untuk menautkan aplikasi Anda dengan domain web Anda. System WebView (ASWebAuthenticationSession) tidak memerlukannya karena ia berjalan di konteks Safari.

Penyiapan di Xcode:

1. Buka proyek Anda di Xcode
2. Pilih target aplikasi Anda
3. Buka tab "Signing & Capabilities"
4. Klik "+ Capability" dan tambahkan "Associated Domains"
5. Tambahkan domain Anda dengan awalan webcredentials:

Contoh Konfigurasi:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>com.apple.developer.associated-domains</key>
    <array>
        <string>webcredentials:domainanda.com</string>
        <string>webcredentials:subdomain.domainanda.com</string>
    </array>
</dict>
</plist>

Beberapa Domain: Jika aplikasi Anda perlu bekerja dengan beberapa domain Anda mungkin memerlukan Related Origin Requests (ROR).

Embedded WebView Android mendukung kunci sandi melalui dua pendekatan berbeda: pendekatan berbasis WebKit yang lebih baru (Bagian 5.3.1) dan pendekatan jembatan JavaScript yang lebih lama (Bagian 5.3.2). System WebView (Chrome Custom Tabs) tidak memerlukan konfigurasi apa pun-kredensial berfungsi secara otomatis.

Android menyediakan contoh resmi kunci sandi WebView yang mendemonstrasikan kedua pendekatan implementasi.

Integrasi WebKit modern dengan penanganan kunci sandi native. Pendekatan ini memberikan dukungan WebAuthn native tanpa memerlukan kode jembatan khusus.

Contoh Resmi: Webkit WebView MainActivity

Persyaratan:

• AndroidX WebKit 1.12.1 atau yang lebih baru (1.14.0+ disarankan)
• Digital Asset Links terkonfigurasi
• APK WebView dengan dukungan WebAuthn (periksa via deteksi fitur)
• Catatan: Perpustakaan AndroidX Credentials TIDAK diperlukan untuk WebView WebAuthn, hanya untuk implementasi fully native

Implementasi:

import androidx.webkit.WebSettingsCompat
import androidx.webkit.WebViewFeature
 
// Check if Web Authentication is supported
if (WebViewFeature.isFeatureSupported(WebViewFeature.WEB_AUTHENTICATION)) {
    // Enable Web Authentication
    WebSettingsCompat.setWebAuthenticationSupport(
        webView.settings,
        WebSettingsCompat.WEB_AUTHENTICATION_SUPPORT_FOR_APP
    )
 
    // Enable JavaScript
    webView.settings.javaScriptEnabled = true
}

Poin Penting:

• Tidak memerlukan jembatan JavaScript: WebAuthn bekerja secara native di WebView
• Memerlukan deteksi fitur: Selalu periksa WebViewFeature.WEB_AUTHENTICATION saat runtime
• Conditional UI tidak didukung: mediation:"conditional" (isian otomatis kunci sandi di kolom input) tidak berfungsi di Embedded WebView
• Strategi fallback: Jika fitur tidak tersedia, gunakan Chrome Custom Tabs sebagai gantinya

Catatan Versi:

• Gunakan WebKit 1.12.1 atau yang lebih baru (1.12.0 memiliki masalah ketersediaan runtime)
• Dukungan fitur bergantung pada versi APK WebView pengguna - APK lama di perangkat tidak akan menampilkan fitur ini

Sebelum AndroidX WebKit 1.12.0, dukungan WebAuthn native tidak ada di Embedded WebView. Pendekatan lama ini menggunakan jembatan Web-ke-Native untuk menangani kunci sandi untuk perangkat tanpa dukungan WebView WebAuthn native.

Contoh Resmi:

• PasskeyWebListener (Handler Jembatan)
• Utilitas encode JavaScript

Kapan Menggunakannya: Mendukung versi Android yang lebih lama atau perangkat dengan implementasi WebView warisan.

Tim harus antara:

1. Menggunakan Chrome Custom Tabs atau Auth Tab (disarankan)
2. Membangun jembatan JavaScript kustom

Untuk implementasi terperinci, lihat Panduan Integrasi Credential Manager WebView Android. Namun, kami sangat menyarankan untuk menggunakan pendekatan native WebKit 1.12.1+ untuk aplikasi modern.

Rekomendasi: Gunakan dukungan WebAuthn native dengan AndroidX WebKit 1.12.1+. Jika tidak tersedia saat runtime, beralihlah ke Chrome Custom Tabs yang memberikan dukungan kunci sandi luar biasa dengan kredensial bersama.

Saat menerapkan kunci sandi di aplikasi native, Anda perlu membangun kepercayaan antara aplikasi Anda dan domain web. Bagian ini mencakup cara menangani satu domain, beberapa domain terkait (ROR), dan cara memverifikasi file asosiasi well-known Anda dikonfigurasi dengan benar.

Untuk aplikasi yang menggunakan satu domain (mis. kayak.com), Anda memerlukan:

• Satu file AASA untuk iOS di https://kayak.com/.well-known/apple-app-site-association
• Satu assetlinks.json untuk Android di https://kayak.com/.well-known/assetlinks.json
• Entitlement Associated Domains dikonfigurasi dengan webcredentials:kayak.com

Related Origins (ROR) adalah fitur WebAuthn yang memungkinkan satu set kunci sandi untuk bekerja di seluruh beberapa domain terkait (mis. kayak.com, kayak.de, kayak.co.uk). ROR menggunakan titik akhir /.well-known/webauthn di setiap situs untuk mendefinisikan origin terkait, BUKAN file AASA atau assetlinks.

Poin Penting:

• Konfigurasi ROR: Setiap domain menampung /.well-known/webauthn dengan daftar asal-usul yang terkait
• File asosiasi aplikasi (AASA/assetlinks): Hanya digunakan untuk memetakan aplikasi ke situs web terkait
• Embedded WebView iOS 18+: Mendukung ROR saat dikonfigurasi dengan benar
• Entitlement Associated Domains: Sertakan semua domain yang aplikasi Anda perlukan untuk autentikasi

Contoh Konfigurasi:

Jika aplikasi Anda berfungsi dengan kayak.com dan kayak.de, kedua domain harus:

• Meng-hosting file AASA masing-masing dengan Tim ID dan Bundel ID yang sama
• Tercantum di entitlement Associated Domains aplikasi Anda
• Memiliki file well-known yang terkonfigurasi dengan benar dan dapat diakses

Sebelum tayang, verifikasi file well-known Anda dikonfigurasi dengan benar dan dapat diakses. Apple dan Google menyediakan URL uji berbasis CDN untuk memeriksa ketersediaan file:

Menggunakan URL Uji Ini:

• Klik tautan untuk memverifikasi apakah Apple/Google dapat mengambil file well-known Anda
• Parameter ?nocache=1 Apple memaksa pengambilan baru, mengabaikan cache CDN
• Jika file tidak dapat diakses melalui URL ini, fungsionalitas kunci sandi tidak akan bekerja di aplikasi Anda
• Ganti kayak.com atau kayak.de dengan domain Anda sendiri dalam pola URL di atas

Jebakan Pengujian: Pastikan semua domain memiliki file well-known yang terkonfigurasi dengan benar. File yang hilang atau salah konfigurasi di domain apa pun dapat merusak fungsi kunci sandi untuk domain tersebut.

Informasi Lebih Lanjut: Relying Party ID WebAuthn dalam Aplikasi Native

Memilih pendekatan implementasi yang tepat bergantung pada arsitektur autentikasi aplikasi Anda, persyaratan OAuth, dan kebutuhan kontrol sesi. Gunakan pohon keputusan ini untuk menentukan jalur terbaik ke depan.

Bagan alur berikut memandu Anda dalam memilih pendekatan implementasi yang tepat berdasarkan persyaratan aplikasi Anda:

Referensi cepat untuk tiap jalur:

• Login berbasis OAuth? → System WebView (ASWebAuthenticationSession / Chrome Custom Tabs)
• Gunakan kembali autentikasi web di shell native? → Embedded WebView dengan konfigurasi (WKWebView / Android WebView + WebKit 1.12.1+)
• Membangun native-first? → Implementasi Native (AuthenticationServices / Credential Manager)
• Autentikasi web yang ada untuk digunakan kembali? → System WebView untuk implementasi cepat; jika tidak Native untuk UX optimal

Inilah bagaimana kinerja masing-masing pendekatan pada dimensi utama:

Penjelasan Dimensi:

• Membuat Kunci Sandi: Seberapa mudah pengguna dapat membuat kunci sandi melalui pendekatan ini
• Menggunakan Kunci Sandi: Pengalaman autentikasi saat menggunakan kunci sandi yang ada
• Mengelola Kunci Sandi: Bagaimana pengguna melihat, mengedit, atau menghapus kunci sandi
• Kompleksitas Teknis: Upaya pengembangan dan pemeliharaan berkelanjutan
• Dukungan OAuth: Seberapa baik pendekatan menangani alur autentikasi OAuth2/OIDC
• Waktu Penyiapan: Garis waktu implementasi biasa

Disarankan: System WebView

Jika aplikasi Anda mengautentikasi melalui penyedia login OAuth2, OIDC, atau sosial (Google, GitHub, Microsoft, dsb.), System WebView adalah pilihan optimal:

• iOS: ASWebAuthenticationSession dibuat khusus untuk alur OAuth
• Android: Chrome Custom Tabs memberikan integrasi OAuth yang mulus
• Manfaat: Kode native minimal, berbagi kredensial otomatis
• Implementasi: Tambahkan WebAuthn ke halaman autentikasi web Anda, lalu muat via System WebView

Contoh: Aplikasi Perjalanan seperti kayak.com dan kayak.de menggunakan OAuth untuk autentikasi. System WebView memungkinkan mereka untuk mempertahankan infrastruktur OAuth yang ada sembari menambahkan dukungan kunci sandi melalui halaman autentikasi web mereka.

Disarankan: Pendekatan Hybrid

Gunakan System WebView untuk autentikasi OAuth awal, lalu Embedded WebView untuk sesi pasca-autentikasi:

1. Autentikasi Awal: System WebView menangani login OAuth + kunci sandi
2. Manajemen Sesi: Beralih ke Embedded WebView untuk konten web yang diautentikasi di mana kontrol cookie/sesi diperlukan
3. Penyiapan Teknis: Konfigurasikan persyaratan System dan Embedded WebView-untuk Android, pastikan AndroidX WebKit 1.12.1+ disertakan (lihat Bagian 5)

Kapan digunakan: Aplikasi yang mengautentikasi melalui OAuth tetapi kemudian perlu menampilkan konten web terautentikasi tempat manipulasi sesi secara langsung diwajibkan.

Disarankan: Implementasi Native

Membangun dari awal atau memiliki layar native? Gunakan fully native:

• iOS: Gunakan kerangka kerja AuthenticationServices
• Android: Gunakan Credential Manager API
• Manfaat: UX terbaik, autentikasi instan, kendali penuh
• Keunggulan Unik: Gunakan preferImmediatelyAvailableCredentials untuk menampilkan hamparan kunci sandi otomatis saat aplikasi dimulai - eksklusif untuk implementasi native dan memberikan tingkat konversi tertinggi
• Rekomendasi SDK: Gunakan Corbado SDKs (iOS, Android) untuk mempercepat pengembangan dengan penanganan edge case yang telah teruji dalam produksi

Untuk Aplikasi Baru: Kami sangat merekomendasikan membangun login native dari hari pertama. Mengatur Anda untuk UX optimal dan menghindari migrasi WebView-ke-native di masa mendatang.

Disarankan: Migrasi Bertahap

Diagram berikut menunjukkan jalur migrasi tambahan:

Setiap fase dibangun di atas fase sebelumnya, memungkinkan perbaikan tambahan tanpa mengganggu pengguna yang ada.

Lihat Bagian 5 untuk instruksi konfigurasi terperinci.

Menguji kunci sandi dalam aplikasi native membutuhkan pendekatan yang terstruktur dan berlapis-lapis. Ikuti piramida pengujian: pengujian unit (logika terisolasi), pengujian integrasi (upacara WebAuthn pada simulator/emulator), dan pengujian sistem (end-to-end pada perangkat fisik).

Kategori Pengujian Penting:

• Perjalanan Inti: Pendaftaran, autentikasi, alur lintas perangkat, penghapusan kunci sandi
• Cakupan Platform: iOS (native), Android (native), peramban web di seluruh versi OS
• Asosiasi Domain: Verifikasi file AASA (iOS) dan Digital Asset Links (Android) dapat diakses
• Alur Pembatalan: Uji pembatalan pengguna di perintah OS dan layar biometrik
• Penanganan Kesalahan: Kegagalan backend, batas waktu jaringan, ketidakcocokan kredensial
• Kasus Batas: Kunci layar dinonaktifkan, iCloud/Google Password Manager dinonaktifkan
• Alur OAuth: Integrasi OAuth + kunci sandi lengkap dari hulu ke hilir
• Perangkat yang Dikelola: Lingkungan yang dikendalikan MDM (lihat pengujian perangkat yang dikelola)
• Pengelola Pihak Ketiga: Kompatibilitas 1Password, Bitwarden, Dashlane
• Autentikasi lintas perangkat: Alur kode QR dan pengujian transport hybrid
• Spesifik Embedded WebView: Jika menggunakan Embedded WebView, verifikasi konfigurasi WebKit 1.12.1+ di Android
• Pemantauan Produksi: Dasbor untuk tingkat keberhasilan, kegagalan, dan latensi

Untuk panduan pengujian komprehensif termasuk strategi otomasi, masalah spesifik platform, dan daftar periksa pracampuran lengkap, lihat panduan khusus kami: Menguji Alur Kunci Sandi di Aplikasi Native iOS & Android.

Pertimbangkan untuk meminta pengguna membuat kunci sandi setelah login tradisional yang sukses (kata sandi, OAuth). Pendekatan konversi bertahap ini:

• Tidak mengganggu alur autentikasi yang ada
• Memungkinkan degradasi yang elegan jika pengguna menolak
• Meningkatkan adopsi kunci sandi seiring waktu tanpa memaksakan perubahan
• Bekerja dengan baik di ketiga pendekatan implementasi

Contoh: Setelah login OAuth via System WebView, tampilkan perintah native: "Aktifkan login yang lebih cepat dengan Face ID?" Jika diterima, buat kunci sandi melalui halaman web yang dimuat di System WebView.

Memutuskan bagaimana mengimplementasikan kunci sandi - melalui Implementasi Native, System WebView atau Embedded WebView adalah pilihan desain penting yang berdampak pada keamanan, pengalaman pengguna, dan kompleksitas pengembangan. Tidak ada satu jawaban yang cocok untuk semua.

Untuk aplikasi berbasis OAuth: System WebView (ASWebAuthenticationSession, Chrome Custom Tabs) adalah titik awal yang disarankan. Ia memberikan dukungan OAuth yang sangat baik, upaya implementasi minimal, dan berbagi kredensial otomatis.

Untuk aplikasi native-first: Terapkan native lebih cepat daripada nanti. Login kunci sandi native menawarkan UX paling mulus dengan kemampuan eksklusif seperti preferImmediatelyAvailableCredentials, yang memungkinkan hamparan kunci sandi otomatis pada saat aplikasi dimulai-sesuatu yang tidak dapat disediakan oleh implementasi WebView. Dengan iOS dan Android sekarang memberikan dukungan kelas satu untuk kunci sandi, keberhasilan dunia nyata menunjukkan adopsi tinggi. Alat-alat (termasuk open-source SDKs dan platform libraries) telah matang untuk membuat integrasi native dapat dicapai dalam kerangka waktu yang wajar. Meskipun Anda harus memperhatikan kebijakan pengelolaan perangkat, sinkronisasi lintas perangkat, dan penyedia pihak ketiga, tantangan tersebut dapat dikelola dengan rekayasa dan pengujian yang cermat. Hasilnya adalah login aplikasi yang memanjakan pengguna dengan kemudahan dan kecepatannya sekaligus meningkatkan keamanan secara signifikan.

Untuk kebutuhan bingkai embedded WebView: Embedded WebView umum digunakan dalam dua skenario nyata. Pertama, aplikasi berbasis OAuth sering menggunakan System WebView untuk alur login awal, kemudian beralih ke Embedded WebView untuk merender opsi manajemen kunci sandi di layar pengaturan saat kontrol sesi dibutuhkan-meskipun beberapa aplikasi menyederhanakannya dengan mempertahankan System WebView untuk kedua alur. Kedua, aplikasi yang telah menanamkan alur autentikasi mereka di dalam bingkai WebView sebelum mengadopsi kunci sandi melanjutkan pola ini untuk konsistensi. Embedded WebView dengan dukungan WebAuthn native (AndroidX WebKit 1.12.1+) memerlukan konfigurasi dan pengaturan (izin, entitlement, setelan WebView) tetapi tidak lagi membutuhkan kode jembatan JavaScript kustom. Perhatikan bahwa Conditional UI tidak didukung di Embedded WebView. Pilih pendekatan ini saat memelihara pola autentikasi tersemat yang sudah ada atau ketika Anda membutuhkan kontrol sesi/cookie untuk layar pasca-autentikasi.

Pada akhirnya, kunci sandi dalam aplikasi native merepresentasikan lompatan besar ke depan dalam kenyamanan pengguna dan keamanan. Entah diimplementasikan via Native, System WebView, atau Embedded WebView, mereka menghilangkan risiko phising dan beban manajemen kata sandi bagi pengguna Anda. Implementasi dunia nyata seperti integrasi kunci sandi aplikasi native VicRoads mendemonstrasikan bahwa pendekatan native-first memberikan adopsi dan kepuasan pengguna tertinggi ketika dieksekusi dengan tepat dengan fitur-fitur seperti hamparan kunci sandi otomatis. Dengan mengikuti praktik terbaik untuk autentikasi ramah-pengguna dan memilih pendekatan implementasi yang sesuai dengan arsitektur aplikasi Anda-native-first untuk aplikasi baru, System WebView untuk alur OAuth, atau Embedded WebView untuk pola tersemat yang sudah ada-Anda dapat menawarkan login biometrik tanpa kata sandi yang benar-benar mewujudkan visi kunci sandi: autentikasi yang sederhana, aman, dan menyenangkan bagi semua orang.

Jika kunci sandi tidak berfungsi di aplikasi native Anda, periksa masalah umum ini berdasarkan pendekatan implementasi:

• File disajikan melalui HTTPS dengan sertifikat yang valid
• Tipe MIME yang benar: application/json
• Tanpa redirect di path .well-known
• iOS: ID Tim dan ID Bundel cocok persis dalam file AASA
• Android: Sidik jari SHA256 cocok dengan sertifikat penandatanganan Anda di assetlinks.json
• Relying Party ID cocok dengan domain Anda (tanpa protokol, tanpa porta)
• Tanpa garis miring penutup pada RP ID
• Asal WebAuthn: https://domain-anda.com (bukan app://)

• iOS: Kemampuan Associated Domains diaktifkan di Xcode dengan webcredentials:domainanda.com
• Android: Digital Asset Links dideklarasikan di AndroidManifest.xml
• Pengguna telah mengaktifkan kunci layar (biometrik atau PIN)
• Uji dengan Validator AASA Apple dan alat Digital Asset Links Google
• Verifikasi file Runner.entitlements memuat associated domain yang benar

• iOS: Menggunakan ASWebAuthenticationSession (disarankan) atau SFSafariViewController
• Android: Menggunakan Chrome Custom Tabs (bukan WebView biasa)
• iOS: Verifikasi Associated Domains dikonfigurasi jika diperlukan
• Uji apakah cookie/kredensial dibagikan dengan browser sistem
• Verifikasi halaman autentikasi web memiliki implementasi WebAuthn yang benar

• iOS: Dikonfigurasi dengan entitlement yang tepat
• iOS: Associated Domains menyertakan semua domain yang relevan
• iOS: File AASA dapat diakses dan diformat dengan benar
• iOS: Uji dengan ?mode=developer selama pengembangan (hapus untuk produksi)
• Android: AndroidX WebKit 1.12.1+ (atau yang lebih baru) disertakan di proyek
• Android: Pemeriksaan fitur saat runtime untuk WebViewFeature.WEB_AUTHENTICATION
• Android: setWebAuthenticationSupport() dipanggil dengan WEB_AUTHENTICATION_SUPPORT_FOR_APP
• Android: JavaScript diaktifkan dalam setelan WebView
• Android: Versi APK WebView pengguna mendukung fitur WebAuthn (gunakan deteksi fitur, bukan versi OS)
• Conditional UI tidak digunakan (tidak didukung di Embedded WebView)
• Cadangan ke Chrome Custom Tabs jika fitur WebAuthn tidak tersedia

• Periksa apakah pengguna memiliki penyedia kredensial non-default aktif (1Password, Bitwarden, dll.)
• Verifikasi penyedia mendukung kunci sandi (tidak semua manajer kata sandi mendukungnya)
• Uji dengan pengelola kredensial native platform (iCloud Keychain, Google Password Manager)

"NotAllowedError: Permintaan ini tidak diizinkan oleh user agent atau platform dalam konteks saat ini"

• Biasanya berarti: Entitlement hilang (iOS) atau fitur WebView tidak tersedia/aktif (Android Embedded WebView)
• Periksa: Konfigurasi Associated Domains, aksesibilitas file AASA, versi WebKit, deteksi fitur, panggilan setWebAuthenticationSupport()

Tidak ada perintah kunci sandi yang muncul

• Dapat berarti: AASA/assetlinks.json tidak dimuat, jenis WebView salah, file AASA dicache
• Coba: Validasi file asosiasi, gunakan ?mode=developer pada iOS untuk pengujian, verifikasi jenis WebView

Untuk proses debugging terperinci, lihat artikel kami tentang Relying Party IDs di aplikasi native.

Jebakan umum: lingkungan staging dengan akses terbatas (IP whitelisting, hanya VPN) akan gagal karena CDN Apple dan Google harus bisa mengambil file asosiasi Anda.

• File AASA/assetlinks dapat diakses secara publik (tanpa whitelisting IP, tanpa persyaratan VPN)
• Verifikasi CDN Apple dapat mencapai file Anda: https://app-site-association.cdn-apple.com/a/v1/domain-staging-anda.com?nocache=1
• Verifikasi Google dapat mencapai file Anda: https://digitalassetlinks.googleapis.com/v1/statements:list/?source.web.site=https://domain-staging-anda.com&relation=delegate_permission/common.handle_all_urls

Subdomain staging dengan rpID produksi:

Jika lingkungan staging Anda (mis., stg.login.example.com) menggunakan domain produksi sebagai rpID (mis., example.com), pencarian AASA terjadi pada domain rpID, bukan subdomain staging Anda. Ini berarti:

• Tambahkan bundel ID aplikasi staging ke file AASA produksi Anda
• Sadarilah bahwa kunci sandi yang dibuat di staging akan muncul di alur login produksi (potensi kebingungan)

Contoh (beberapa lingkungan berbagi satu AASA):

{
    "webcredentials": {
        "apps": [
            "TEAMID123.com.example.app",
            "TEAMID123.com.example.app.dev",
            "TEAMID123.com.example.app.stg",
            "TEAMID123.com.example.app.pre"
        ]
    }
}

Rekomendasi: Gunakan rpID staging terpisah yang cocok dengan domain staging Anda untuk menghindari tumpang tindih kredensial di antara lingkungan. Ini membutuhkan file AASA yang dapat diakses publik pada domain staging.

Klarifikasi ?mode=developer:

Parameter ?mode=developer di Associated Domains melewati cache CDN Apple tetapi tidak mengabaikan persyaratan aksesibilitas. File AASA Anda masih harus dapat dijangkau dari perangkat (bukan melalui CDN Apple, tetapi secara langsung). Hal ini membantu selama pengembangan ketika beralih pada perubahan AASA, tetapi tidak akan membantu jika server staging Anda terdaftar dalam IP-whitelist.

SDK Native Corbado:

• iOS SDK (Swift)
• Android SDK (Kotlin)
• Paket Flutter

Dokumentasi Platform:

• Apple: Mendukung Kunci Sandi
• Google: Credential Manager

Alat Validasi:

• Validator AASA Apple
• Pembuat Digital Asset Links Google

Tentang Corbado

Corbado adalah Passkey Intelligence Platform untuk tim CIAM yang menjalankan autentikasi consumer dalam skala besar. Kami membantu Anda melihat apa yang tidak bisa ditunjukkan oleh log IDP dan tool analytics generik: device, versi OS, browser, dan credential manager mana yang mendukung passkey; mengapa enrollment tidak menjadi login; di mana flow WebAuthn gagal; dan kapan update OS atau browser diam-diam merusak login — semuanya tanpa mengganti Okta, Auth0, Ping, Cognito, atau IDP internal Anda. Dua produk: Corbado Observe menambah observability untuk passkey dan metode login lainnya. Corbado Connect menghadirkan managed passkey dengan analytics terintegrasi (berdampingan dengan IDP Anda). VicRoads menjalankan passkey untuk 5M+ pengguna dengan Corbado (aktivasi passkey +80%). Bicara dengan pakar Passkey →

Pilihan bergantung pada arsitektur autentikasi Anda. Jika aplikasi Anda menggunakan OAuth2 atau OIDC, System WebView (ASWebAuthenticationSession di iOS atau Chrome Custom Tabs di Android) membutuhkan upaya implementasi paling sedikit dan tanpa pengaturan file asosiasi. Untuk aplikasi native-first baru, Implementasi Native memberikan UX yang unggul, sementara Embedded WebView cocok untuk aplikasi yang sudah menyematkan autentikasi dalam bingkai WebView dan memerlukan kontrol sesi atau cookie setelah login.

SFSafariViewController memanfaatkan mesin Safari, menampilkan bilah URL dengan indikator SSL, dan memberikan perlindungan phising, sehingga lebih tepercaya untuk alur autentikasi. WKWebView menawarkan lebih banyak penyesuaian UI tetapi memiliki penyimpanan cookie terisolasi yang terpisah dari Safari, memerlukan entitlement Associated Domains dan file AASA untuk mengaktifkan kunci sandi, dan tidak menampilkan bilah URL, yang mengurangi sinyal kepercayaan pengguna.

Chrome Custom Tabs berbagi cookie dan kredensial yang disimpan dengan browser Chrome pengguna, yang berarti kunci sandi yang disimpan di Google Password Manager dapat diakses selama autentikasi. Android WebView standar memiliki penyimpanan cookie yang terisolasi, tidak menampilkan URL atau indikator SSL, dan Google telah secara eksplisit melarangnya untuk login akun Google karena risiko phising.

Jika pengguna memiliki pengelola kredensial pihak ketiga seperti 1Password yang ditetapkan sebagai penyedia aktif mereka, hal itu sering kali akan mencegat pembuatan dan penyimpanan kunci sandi, mengambil prioritas di atas pengelola kredensial native platform (iCloud Keychain atau Google Password Manager). Ini berarti kunci sandi mungkin disimpan di aplikasi pihak ketiga daripada keychain platform, yang memengaruhi sinkronisasi lintas perangkat dan perilaku pengelolaan kunci sandi.

Ketika kebijakan MDM menonaktifkan sinkronisasi kredensial, kunci sandi menjadi terikat pada perangkat dan tidak dapat berpindah ke perangkat pengganti, tidak seperti skenario konsumen biasa. Aplikasi yang menargetkan lingkungan korporat harus merencanakan mekanisme autentikasi cadangan seperti kata sandi atau login tautan ajaib untuk menangani kasus saat pengguna menerima perangkat yang dikelola baru.