Google menggunakan teknologi AI untuk menerjemahkan konten ke dalam bahasa pilihan Anda. Terjemahan AI mungkin mengandung kesalahan.

Pendaftaran kunci sandi sisi server

Ringkasan

Berikut ringkasan umum langkah-langkah utama yang terlibat dalam pendaftaran kunci sandi:

Alur pendaftaran kunci sandi

Tentukan opsi untuk membuat kunci sandi. Kirimkan ke klien, sehingga Anda dapat meneruskannya ke panggilan pembuatan kunci sandi: panggilan API WebAuthn navigator.credentials.create di web, dan credentialManager.createCredential di Android. Setelah pengguna mengonfirmasi pembuatan kunci sandi, panggilan pembuatan kunci sandi akan diselesaikan dan menampilkan kredensial PublicKeyCredential.
Verifikasi kredensial dan simpan di server.

Bagian berikut membahas secara mendalam setiap langkah.

Membuat opsi pembuatan kredensial

Langkah pertama yang perlu Anda lakukan di server adalah membuat objek PublicKeyCredentialCreationOptions.

Untuk melakukannya, andalkan library sisi server FIDO Anda. Biasanya, library ini akan menawarkan fungsi utilitas yang dapat membuat opsi ini untuk Anda. SimpleWebAuthn menawarkan, misalnya, generateRegistrationOptions.

PublicKeyCredentialCreationOptions harus menyertakan semua yang diperlukan untuk pembuatan kunci sandi: informasi tentang pengguna, tentang RP, dan konfigurasi untuk properti kredensial yang Anda buat. Setelah Anda menentukan semua ini, teruskan sesuai kebutuhan ke fungsi di library sisi server FIDO yang bertanggung jawab untuk membuat objek PublicKeyCredentialCreationOptions.

Catatan: Dalam artikel ini, kami berfokus pada kolom PublicKeyCredentialCreationOptions yang memerlukan pekerjaan sisi server. Misalnya, kita menghilangkan authenticatorSelection.authenticatorAttachment. Parameter ini menentukan jenis pengautentikasi yang Anda inginkan untuk diandalkan oleh pengguna. Biasanya, nilai ini akan sama untuk semua pengguna, sehingga dapat berupa konstanta yang ditetapkan sekali dalam kode server Anda. Oleh karena itu, kami tidak membahasnya secara mendetail di sini.
authenticatorAttachment—dan secara umum nilai semua kolom di PublicKeyCredentialCreationOptions—harus dipilih dengan cermat, karena akan menentukan jenis kredensial yang Anda buat dan perilakunya. Baca selengkapnya di Membuat kunci sandi untuk login tanpa sandi (web) dan Memproses login pengguna dengan Credential Manager (Android).

Beberapa kolom PublicKeyCredentialCreationOptions dapat berupa konstanta. Lainnya harus ditentukan secara dinamis di server:

rpId: Untuk mengisi ID RP di server, gunakan fungsi atau variabel sisi server yang memberi Anda nama host aplikasi web, seperti example.com.
user.name dan user.displayName: Untuk mengisi kolom ini, gunakan informasi sesi pengguna yang login (atau informasi akun pengguna baru, jika pengguna membuat kunci sandi saat mendaftar). user.name biasanya berupa alamat email, dan bersifat unik untuk RP. user.displayName adalah nama yang mudah digunakan. Perhatikan bahwa tidak semua platform akan menggunakan displayName.
user.id: String unik acak yang dibuat saat pembuatan akun. ID ini harus bersifat permanen, tidak seperti nama pengguna yang mungkin dapat diedit. ID pengguna mengidentifikasi akun, tetapi tidak boleh berisi informasi identitas pribadi (PII). Anda mungkin sudah memiliki ID pengguna di sistem, tetapi jika diperlukan, buat ID pengguna khusus untuk kunci sandi agar tidak berisi PII.
excludeCredentials: Daftar ID kredensial yang ada untuk mencegah duplikasi kunci sandi dari penyedia kunci sandi. Untuk mengisi kolom ini, cari kredensial yang ada untuk pengguna ini di database Anda. Tinjau detailnya di Mencegah pembuatan kunci sandi baru jika sudah ada.
challenge: Untuk pendaftaran kredensial, verifikasi tidak relevan kecuali jika Anda menggunakan pengesahan, teknik yang lebih canggih untuk memverifikasi identitas penyedia kunci sandi dan data yang dikeluarkannya. Namun, meskipun Anda tidak menggunakan pengesahan, tantangan tetap merupakan kolom wajib diisi. Petunjuk untuk membuat verifikasi yang aman untuk autentikasi tersedia di Autentikasi kunci sandi sisi server.

Encoding dan decoding

PublicKeyCredentialCreationOptions yang dikirim oleh server — `PublicKeyCredentialCreationOptions` yang dikirim oleh server. Kolom biner seperti `challenge` dan `user.id` dienkode di sisi server menjadi `base64URL` sehingga opsi dapat dikirim sebagai JSON melalui HTTPS.

Objek PublicKeyCredentialCreationOptions WebAuthn standar menyertakan kolom yang merupakan ArrayBuffer, yang tidak dapat diserialisasi secara langsung dengan JSON.stringify(). Untuk mengirim opsi ini melalui HTTPS, kolom biner harus dienkode sebagai string base64URL:

Di server, library sisi server FIDO Anda (seperti SimpleWebAuthn) otomatis menghasilkan objek opsi yang dapat diserialisasi JSON (misalnya, PublicKeyCredentialCreationOptionsJSON) dengan kolom berenkode Base64URL.
Di sisi klien, browser modern mendukung PublicKeyCredential.parseCreationOptionsFromJSON() untuk mengonversi opsi JSON langsung menjadi PublicKeyCredentialCreationOptions. Saat menggunakan library sisi klien seperti @simplewebauthn/browser, fungsi seperti startRegistration({ optionsJSON: options }) akan menangani konversi ini secara otomatis.

Contoh kode: membuat opsi pembuatan kredensial

Kami menggunakan library SimpleWebAuthn dalam contoh kami. Di sini, kita menyerahkan pembuatan opsi kredensial kunci publik ke fungsi generateRegistrationOptions.

import {
  generateRegistrationOptions,
  verifyRegistrationResponse,
} from '@simplewebauthn/server';
import { isoBase64URL, isoUint8Array } from '@simplewebauthn/server/helpers';

router.post('/registerRequest', csrfCheck, sessionCheck, async (req, res) => {
  const { user } = res.locals;
  // Ensure you nest verification function calls in try/catch blocks.
  // If something fails, throw an error with a descriptive error message.
  // Return that message with an appropriate error code to the client.
  try {
    // `excludeCredentials` prevents users from re-registering existing
    // credentials for a given passkey provider
    const excludeCredentials = [];
    const credentials = Credentials.findByUserId(user.id);
    if (credentials.length > 0) {
      for (const cred of credentials) {
        excludeCredentials.push({
          id: cred.id,
          type: 'public-key',
          transports: cred.transports,
        });
      }
    }

    // Generate registration options for WebAuthn create
    const options = await generateRegistrationOptions({
      rpName: process.env.RP_NAME,
      rpID: process.env.HOSTNAME,
      userID: isoUint8Array.fromUTF8String(user.id),
      userName: user.username,
      userDisplayName: user.displayName || '',
      attestationType: 'none',
      excludeCredentials,
      authenticatorSelection: {
        authenticatorAttachment: 'platform',
        residentKey: 'required',
        userVerification: 'preferred',
      },
    });

    // Keep the challenge in the session
    req.session.challenge = options.challenge;

    return res.json(options);
  } catch (e) {
    console.error(e);
    return res.status(400).send({ error: e.message });
  }
});

Menyimpan kunci publik

Jika navigator.credentials.create berhasil di-resolve di klien, berarti kunci sandi telah berhasil dibuat. Objek PublicKeyCredential akan ditampilkan.

Objek PublicKeyCredential berisi objek AuthenticatorAttestationResponse, yang mewakili respons penyedia kunci sandi terhadap petunjuk klien untuk membuat kunci sandi. Kredensial ini berisi informasi tentang kredensial baru yang Anda perlukan sebagai RP untuk mengautentikasi pengguna nanti. Pelajari lebih lanjut AuthenticatorAttestationResponse di Lampiran: AuthenticatorAttestationResponse.

Kirim objek PublicKeyCredential ke server. Setelah Anda menerimanya, verifikasi.

Serahkan langkah verifikasi ini ke library sisi server FIDO Anda. Biasanya, library ini akan menawarkan fungsi utilitas untuk tujuan ini. SimpleWebAuthn menawarkan, misalnya, verifyRegistrationResponse. Pelajari apa yang terjadi di balik layar di Lampiran: verifikasi respons pendaftaran.

Setelah verifikasi berhasil, simpan informasi kredensial di database Anda sehingga pengguna nantinya dapat melakukan autentikasi dengan kunci sandi yang terkait dengan kredensial tersebut.

Gunakan tabel khusus untuk kredensial kunci publik yang terkait dengan kunci sandi. Pengguna hanya dapat memiliki satu sandi, tetapi dapat memiliki beberapa kunci sandi — misalnya, kunci sandi yang disinkronkan melalui Apple iCloud Keychain dan satu lagi melalui Pengelola Sandi Google.

Berikut adalah contoh skema yang dapat Anda gunakan untuk menyimpan informasi kredensial:

Skema database untuk kunci sandi

Tabel pengguna:
- user_id: ID pengguna utama. ID acak, unik, dan permanen untuk pengguna. Gunakan ini sebagai kunci utama untuk tabel Users Anda.
- username. Nama pengguna yang ditentukan pengguna, yang berpotensi dapat diedit.
- passkey_user_id: ID pengguna khusus kunci sandi yang bebas PII, yang diwakili oleh user.id di opsi pendaftaran Anda. Saat pengguna mencoba melakukan autentikasi di lain waktu, pengautentikasi akan menyediakan passkey_user_id ini dalam respons autentikasinya di userHandle. Sebaiknya jangan tetapkan passkey_user_id sebagai kunci utama. Kunci utama cenderung menjadi PII de facto dalam sistem, karena digunakan secara luas.
Tabel Kredensial kunci publik:
- id: ID Kredensial. Gunakan ini sebagai kunci utama untuk tabel Kredensial kunci publik Anda.
- public_key: Kunci publik kredensial.
- passkey_user_id: Gunakan ini sebagai kunci asing untuk membuat link dengan tabel Users.
- backed_up: Kunci sandi dicadangkan jika disinkronkan oleh penyedia kunci sandi. Menyimpan status pencadangan berguna jika Anda ingin mempertimbangkan untuk tidak menggunakan sandi di masa mendatang bagi pengguna yang memiliki kunci sandi backed_up. Anda dapat memeriksa apakah kunci sandi dicadangkan dengan memeriksa flag BE di authenticatorData, atau dengan menggunakan fitur library sisi server FIDO yang biasanya tersedia untuk memberi Anda akses mudah ke informasi ini. Menyimpan kelayakan pencadangan dapat membantu menjawab potensi pertanyaan pengguna.
- name: Opsional, nama tampilan untuk kredensial agar pengguna dapat memberikan nama kustom pada kredensial.
- transports: Array transport. Menyimpan transpor berguna untuk pengalaman pengguna autentikasi. Jika transport tersedia, browser dapat berperilaku sebagaimana mestinya dan menampilkan UI yang sesuai dengan transport yang digunakan penyedia kunci sandi untuk berkomunikasi dengan klien—khususnya untuk kasus penggunaan autentikasi ulang saat allowCredentials tidak kosong.

Informasi lain dapat berguna untuk disimpan demi tujuan pengalaman pengguna, termasuk item seperti penyedia kunci sandi, waktu pembuatan kredensial, dan waktu terakhir digunakan. Baca selengkapnya di Desain antarmuka pengguna kunci sandi.

Contoh kode: menyimpan kredensial

Kami menggunakan library SimpleWebAuthn dalam contoh kami. Di sini, kita menyerahkan verifikasi respons pendaftaran ke fungsi verifyRegistrationResponse.

import { isoBase64URL } from '@simplewebauthn/server/helpers';


router.post('/registerResponse', csrfCheck, sessionCheck, async (req, res) => {
  const expectedChallenge = req.session.challenge;
  const expectedOrigin = getOrigin(req.get('User-Agent'));
  const expectedRPID = process.env.HOSTNAME;
  const response = req.body;
  // This sample code is for registering a passkey for an existing,
  // signed-in user

  // Ensure you nest verification function calls in try/catch blocks.
  // If something fails, throw an error with a descriptive error message.
  // Return that message with an appropriate error code to the client.
  try {
    // Verify the credential
    const { verified, registrationInfo } = await verifyRegistrationResponse({
      response,
      expectedChallenge,
      expectedOrigin,
      expectedRPID,
      requireUserVerification: false,
    });

    if (!verified) {
      throw new Error('Verification failed.');
    }

    const {
      aaguid,
      credential,
      credentialBackedUp
    } = registrationInfo;

    // Name the credential based on AAGUID
    const name =
      aaguid === undefined ||
      aaguid === '00000000-0000-0000-0000-000000000000' ?
        req.useragent?.platform : aaguids[aaguid]?.name;

    const base64PublicKey = isoBase64URL.fromBuffer(credential.publicKey);

    // Existing, signed-in user
    const { user } = res.locals;

    // Save the credential
    await Credentials.update({
      id: credential.id,
      passkey_user_id: user.passkey_user_id,
      publicKey: base64PublicKey,
      name,
      aaguid,
      transports: credential.transports || response.response.transports,
      backed_up: credentialBackedUp,
      registered_at: new Date().getTime()
    });

    // Kill the challenge for this session
    delete req.session.challenge;

    return res.json(user);
  } catch (e) {
    delete req.session.challenge;

    console.error(e);
    return res.status(400).send({ error: e.message });
  }
});

Lampiran: `AuthenticatorAttestationResponse`

AuthenticatorAttestationResponse berisi dua objek penting:

response.clientDataJSON adalah versi JSON dari data klien, yang di web merupakan data seperti yang dilihat oleh browser. Objek ini berisi origin RP, verifikasi login, dan androidPackageName jika klien adalah aplikasi Android. Sebagai RP, membaca clientDataJSON akan memberi Anda akses ke informasi yang dilihat browser pada saat permintaan create.
response.attestationObjectberisi dua bagian informasi:
- attestationStatement yang tidak relevan kecuali jika Anda menggunakan pengesahan.
- authenticatorData adalah data seperti yang dilihat oleh penyedia kunci sandi. Sebagai RP, membaca authenticatorData akan memberi Anda akses ke data yang dilihat oleh penyedia kunci sandi dan ditampilkan pada saat permintaan create.

authenticatorDataberisi informasi penting tentang kredensial kunci publik yang terkait dengan kunci sandi yang baru dibuat:

Kredensial kunci publik itu sendiri, dan ID kredensial unik untuknya.
ID RP yang terkait dengan kredensial.
Flag yang menjelaskan status pengguna saat kunci sandi dibuat: apakah pengguna benar-benar ada, dan apakah pengguna berhasil diverifikasi (lihat pembahasan mendalam userVerification).
AAGUID adalah ID untuk penyedia kunci sandi seperti Pengelola Sandi Google. Berdasarkan AAGUID, Anda dapat mengidentifikasi penyedia kunci sandi dan menampilkan namanya di halaman pengelolaan kunci sandi. (lihat Menentukan penyedia kunci sandi dengan AAGUID)

Meskipun authenticatorData disusun bertingkat dalam attestationObject, informasi yang dimuatnya diperlukan untuk implementasi kunci sandi Anda, baik Anda menggunakan pengesahan atau tidak. authenticatorData dienkode, dan berisi kolom yang dienkode dalam format biner. Library sisi server Anda biasanya akan menangani penguraian dan dekode. Jika Anda tidak menggunakan library sisi server, pertimbangkan untuk memanfaatkan getAuthenticatorData() sisi klien untuk menghemat pekerjaan penguraian dan dekode di sisi server.

Lampiran: verifikasi respons pendaftaran

Di balik layar, verifikasi respons pendaftaran terdiri dari pemeriksaan berikut:

Pastikan ID RP cocok dengan situs Anda.
Pastikan asal permintaan adalah asal yang diharapkan untuk situs Anda (URL situs utama, aplikasi Android).
Jika Anda memerlukan verifikasi pengguna, pastikan flag verifikasi pengguna authenticatorData.uv adalah true.
Flag kehadiran pengguna authenticatorData.up biasanya diharapkan berupa true, tetapi jika kredensial dibuat secara bersyarat, flag tersebut diharapkan berupa false.
Periksa apakah klien dapat memberikan tantangan yang Anda berikan. Jika Anda tidak menggunakan pengesahan, pemeriksaan ini tidak penting. Namun, menerapkan pemeriksaan ini adalah praktik terbaik: hal ini memastikan kode Anda siap jika Anda memutuskan untuk menggunakan pengesahan di masa mendatang.
Pastikan ID kredensial belum terdaftar untuk pengguna mana pun.
Pastikan algoritma yang digunakan oleh penyedia kunci sandi untuk membuat kredensial adalah algoritma yang Anda cantumkan (di setiap kolom alg dari publicKeyCredentialCreationOptions.pubKeyCredParams, yang biasanya ditentukan dalam library sisi server dan tidak terlihat oleh Anda). Hal ini memastikan bahwa pengguna hanya dapat mendaftar dengan algoritma yang telah Anda pilih untuk diizinkan.

Untuk mempelajari lebih lanjut, lihat kode sumber SimpleWebAuthn untuk verifyRegistrationResponse atau pelajari daftar lengkap verifikasi dalam spesifikasi.

Berikutnya

Autentikasi kunci sandi sisi server