Memperkenalkan petunjuk, Permintaan Origin Terkait dan serialisasi JSON untuk WebAuthn di Chrome

Chrome 128 dan 129 memperkenalkan fitur baru yang menarik untuk WebAuthn—API yang mendasari pembuatan sistem autentikasi berbasis kunci sandi.

Eiji Kitamura

• Petunjuk: Petunjuk memberi pihak yang mengandalkan (RP) kontrol yang lebih baik atas UI WebAuthn di browser. Kunci keamanan sangat berguna bagi pengguna perusahaan yang ingin menggunakan kunci keamanan.
• Permintaan origin terkait: Dengan permintaan origin terkait, RP dapat membuat kunci sandi valid di beberapa domain. Jika memiliki beberapa situs, Anda kini dapat mengizinkan pengguna menggunakan kembali kunci sandi mereka di seluruh situs, sehingga menghilangkan hambatan login.
• Serialisasi JSON: API serialisasi JSON memungkinkan Anda menyederhanakan kode frontend RP dengan opsi encoding dan decoding serta kredensial yang diteruskan ke dan dari WebAuthn API.

Petunjuk

Dengan hints, pihak tepercaya (RP) kini dapat menentukan preferensi UI untuk membuat kunci sandi atau melakukan autentikasi dengan kunci sandi.

Sebelumnya, saat RP ingin membatasi pengautentikasi yang dapat digunakan pengguna untuk membuat kunci sandi atau melakukan autentikasi, mereka dapat menggunakan authenticatorSelection.authenticatorAttachment untuk menentukan "platform" atau "cross-platform". Masing-masing membatasi pengautentikasi ke pengautentikasi platform atau pengautentikasi roaming. Dengan hints, spesifikasi ini dapat lebih fleksibel.

RP dapat menggunakan hints opsional di PublicKeyCredentialCreationOptions atau PublicKeyCredentialRequestOptions untuk menentukan "security-key", "client-device", dan "hybrid" dalam urutan preferensi dalam array.

Berikut adalah contoh permintaan pembuatan kredensial yang lebih memilih pengautentikasi "cross-platform" dengan "security-key" sebagai petunjuk. Tindakan ini akan memberi tahu Chrome untuk menampilkan UI yang berfokus pada kunci keamanan bagi pengguna perusahaan.

const credential = await navigator.credentials.create({
  publicKey: {
    challenge: *****,
    hints: ['security-key'],
    authenticatorSelection: {
      authenticatorAttachment: 'cross-platform'
    }
  }
});

Saat RP ingin memprioritaskan skenario verifikasi lintas perangkat, RP dapat mengirimkan permintaan autentikasi yang lebih memilih pengautentikasi "cross-platform" dengan "hybrid" sebagai petunjuk.

const credential = await navigator.credentials.create({
  publicKey: {
    challenge: *****,
    residentKey: true,
    hints: ['hybrid']
    authenticatorSelection: {
      authenticatorAttachment: 'cross-platform'
    }
  }
});

Permintaan origin terkait

Dengan Permintaan Asal Terkait, RP dapat membuat kunci sandi dapat digunakan dari beberapa domain. Membangun pengalaman login terpusat dan menggunakan protokol federasi tetap menjadi solusi yang direkomendasikan untuk sebagian besar situs. Namun, jika Anda memiliki beberapa domain dan federasi tidak memungkinkan, asal terkait mungkin menjadi solusinya.

Semua permintaan WebAuthn harus menentukan ID pihak tepercaya (ID RP), dan semua kunci sandi dikaitkan dengan satu ID RP. Biasanya, origin hanya dapat menentukan ID RP berdasarkan domainnya, sehingga dalam hal ini www.example.co.uk dapat menentukan ID RP example.co.uk, tetapi bukan example.com. Dengan Permintaan Origin Related, ID RP yang diklaim dapat divalidasi dengan mengambil file JSON umum yang terletak di /.well-known/webauthn dari domain target. Jadi, example.co.uk (dan example.in, example.de, dan seterusnya) semuanya dapat menggunakan ID RP example.com jika example.com menentukannya dalam format berikut:

URL: https://example.com/.well-known/webauthn

{
  "origins": [
    "https://example.co.uk",
    "https://example.de",
    "https://example.sg",
    "https://example.net",
    "https://exampledelivery.com",
    "https://exampledelivery.co.uk",
    "https://exampledelivery.de",
    "https://exampledelivery.sg",
    "https://myexamplerewards.com",
    "https://examplecars.com"
  ]
}

Pelajari cara menyiapkan Permintaan Asal Terkait di Mengizinkan penggunaan kembali kunci sandi di seluruh situs Anda dengan Permintaan Asal Terkait.

Serialisasi JSON

Objek permintaan dan respons WebAuthn memiliki beberapa kolom yang berisi data biner mentah dalam ArrayBuffer, seperti ID kredensial, ID pengguna, atau verifikasi login. Jika situs ingin menggunakan JSON untuk bertukar data ini dengan servernya, data biner harus dienkode terlebih dahulu, misalnya dengan Base64URL. Hal ini menambah kompleksitas yang tidak perlu bagi developer yang ingin mulai menggunakan kunci sandi di situs mereka.

WebAuthn kini menawarkan API untuk mengurai objek permintaan WebAuthn PublicKeyCredentialCreationOptions dan PublicKeyCredentialRequestOptions secara langsung dari JSON, dan melakukan serialisasi respons PublicKeyCredential secara langsung ke dalam JSON. Semua kolom bernilai ArrayBuffer yang membawa data biner mentah akan otomatis dikonversi dari atau ke nilai yang dienkode ke Base64URL. API ini tersedia mulai Chrome 129.

Sebelum membuat kunci sandi, ambil objek PublicKeyCredentialCreationOptions yang dienkode JSON dari server dan dekode menggunakan PublicKeyCredential.parseCreationOptionsFromJSON().

export async function registerCredential() {

  // Fetch encoded `PublicKeyCredentialCreationOptions`
  // and JSON decode it.
  const options = await fetch('/auth/registerRequest').json();

  // Decode `PublicKeyCredentialCreationOptions` JSON object
  const decodedOptions = PublicKeyCredential.parseCreationOptionsFromJSON(options);  

  // Invoke the WebAuthn create() function.
  const cred = await navigator.credentials.create({
    publicKey: decodedOptions,
  });
  ...

Setelah membuat kunci sandi, encode kredensial yang dihasilkan menggunakan toJSON() sehingga dapat dikirim ke server.

  ...
  const cred = await navigator.credentials.create({
    publicKey: options,
  });

  // Encode the credential to JSON and stringify
  const credential = JSON.stringify(cred.toJSON());

  // Send the encoded credential to the server
  await fetch('/auth/registerResponse', credential);
  ...

Sebelum melakukan autentikasi dengan kunci sandi, ambil PublicKeyRequestCreationOptions yang dienkode JSON dari server dan dekode menggunakan PublicKeyCredential.parseRequestOptionsFromJSON().

export async function authenticate() {

  // Fetch encoded `PublicKeyCredentialRequestOptions`
  // and JSON decode it.
  const options = await fetch('/auth/signinRequest').json();

  // Decode `PublicKeyCredentialRequestOptions` JSON object
  const decodedOptions = PublicKeyCredential.parseRequestOptionsFromJSON(options);

  // Invoke the WebAuthn get() function.
  const cred = await navigator.credentials.get({
    publicKey: options
  });
  ...

Setelah mengautentikasi dengan kunci sandi, encode kredensial yang dihasilkan menggunakan metode toJSON() sehingga dapat dikirim ke server.

  ...
  const cred = await navigator.credentials.get({
    publicKey: options
  });

  // Encode the credential to JSON and stringify
  const credential = JSON.stringify(cred.toJSON());

  // Send the encoded credential to the server
  await fetch(`/auth/signinResponse`, credential);
  ...

Pelajari lebih lanjut

Untuk mempelajari WebAuthn dan kunci sandi lebih lanjut, lihat referensi berikut:

• Kunci sandi | Chrome untuk Developer
• Pengantar penerapan kunci sandi sisi server
• passkeys.dev