Orientasi Kunci Sandi

Fitur web: Autentikasi web

Panduan ini memberikan orientasi yang padat dan berorientasi pada tindakan untuk menerapkan autentikasi kunci sandi dan pengelolaan kredensial yang aman dan tidak bergantung pada framework di aplikasi web modern.

1. Prasyarat Inti untuk Kunci Sandi

Kunci sandi mengandalkan Web Authentication API (WebAuthn), yang menerapkan batasan keamanan lintas sektoral yang ketat yang harus dipenuhi sebelum upaya penerapan apa pun:

  • Konteks Aman: Metode WebAuthn (navigator.credentials.create dan navigator.credentials.get) hanya dapat diakses melalui Konteks Aman. Aplikasi HARUS berjalan di https:// dalam produksi, atau http://localhost untuk pengembangan lokal.
  • ID Pihak Tepercaya (RP): Setiap kredensial terkait dengan ID RP (pada dasarnya nama domain aplikasi). RP ID yang diteruskan dalam opsi sisi server HARUS cocok atau merupakan akhiran yang valid dari nama domain origin saat ini (misalnya, example.com valid untuk login.example.com). Ketidakcocokan akan menyebabkan pengecualian SecurityError di sisi klien.

2. Peringatan UX AAGUID

Authenticator Attestation Globally Unique Identifier (AAGUID) adalah ID unik 128-bit yang ditampilkan dalam data pengesahan pendaftaran yang mewakili model/penyedia pengautentikasi (misalnya, Pengelola Sandi Google, iCloud Keychain, 1Password).

  • Hanya Petunjuk UX: Pihak Pengandalkan HARUS menggunakan AAGUID secara eksklusif untuk petunjuk UX (seperti merender nama dan ikon penyedia kunci sandi dalam daftar pengelolaan untuk membantu pengguna).
  • Tidak Ada Dependensi Keamanan: aplikasi TIDAK BOLEH menggunakan AAGUID untuk keamanan kriptografis atau keputusan akses. Kunci sandi platform saat ini tidak memberikan pengesahan kriptografis untuk AAGUID-nya, yang berarti kunci sandi tersebut dapat diubah atau disimulasikan oleh agen pengguna.

3. Rekomendasi Library Terpisah

Untuk pembuatan opsi FIDO2/WebAuthn backend dan verifikasi tanda tangan, developer HARUS mengandalkan library open source yang telah diperiksa per bahasa, bukan kriptografi yang dibuat secara manual:

  • JavaScript/TypeScript: SimpleWebAuthn (github.com/MasterKale/SimpleWebAuthn)
  • Python: py_webauthn (github.com/duo-labs/py_webauthn)
  • Java: Java WebAuthn Server (github.com/Yubico/java-webauthn-server), WebAuthn4J (github.com/webauthn4j/webauthn4j)
  • .NET: Library .NET untuk FIDO2 (github.com/abergs/fido2-net-lib)
  • Go: Library Go WebAuthn (github.com/go-webauthn/webauthn)
  • Ruby: WebAuthn Ruby (github.com/cedarcode/webauthn-ruby)
  • PHP: WebAuthn Framework (github.com/web-auth/webauthn-framework)

4. Matriks Referensi Kasus Penggunaan

Identifikasi kasus penggunaan yang cocok di bawah dan dapatkan panduan penerapan lengkapnya. Setiap kasus penggunaan memiliki API penting (PublicKeyCredential.parseCreationOptionsFromJSON, parseRequestOptionsFromJSON, signalAllAcceptedCredentials, signalCurrentUserDetails, signalUnknownCredential, mediasi bersyarat, penanganan AAGUID, dll.) yang hanya didokumentasikan dalam panduan per kasus penggunaan. JANGAN lewati langkah pengambilan ini, dan JANGAN ganti wrapper library pihak ketiga (seperti startAuthentication/startRegistration SimpleWebAuthn) di klien — panggil API browser WebAuthn native secara langsung. Rekomendasi library di Bagian 3 hanya berlaku untuk sisi server (verifikasi FIDO2 backend).

Detail implementasi kunci sandi dan WebAuthn tertentu dipetakan ke panduan berikut: