Przedstawiamy wskazówki, powiązane żądania dotyczące źródła i serializację JSON dla WebAuthn w Chrome

W Chrome 128 i 129 wprowadzamy ciekawe nowe funkcje WebAuthn – bazowego interfejsu API do tworzenia systemów uwierzytelniania opartych na kluczach dostępu.

Eiji Kitamura

• Wskazówki: wskazówki dają stronom zależnym (RP) większą kontrolę nad WebAuthn Interfejs w przeglądarce. Są one szczególnie przydatne dla użytkowników firmowych, którzy chcą jak używać kluczy bezpieczeństwa.
• Powiązane żądania punktu początkowego: z powiązanym źródłem żądań, adresy URL mogą sprawiać, że klucze dostępu będą ważne w wielu domenach. Jeśli masz kilka możesz umożliwić użytkownikom ponowne korzystanie z kluczy i eliminuje problemy z logowaniem.
• Serializacja JSON: interfejsy API serializacji JSON pozwalają uprościć kod frontendu RP dzięki opcjom kodowania i dekodowania dane logowania przekazywane do i z interfejsu WebAuthn API.

Wskazówki

Dzięki hints podmioty uzależnione mogą teraz określać preferencje interfejsu dotyczące tworzenia lub uwierzytelniania za pomocą klucza dostępu.

Wcześniej, gdy w przypadku grupy objętej ograniczeniami można było ograniczyć narzędzie uwierzytelniające, użytkownik może użyć aby utworzyć klucz dostępu lub się uwierzytelnić, można użyć authenticatorSelection.authenticatorAttachment, aby określić "platform" lub "cross-platform" Ograniczają mechanizm uwierzytelniający odpowiednio do platformy uwierzytelnianie lub roamingu Dzięki hints ta specyfikacja może być bardziej elastyczna.

Grupa z ograniczonym dostępem może użyć opcjonalnego parametru hints w polu PublicKeyCredentialCreationOptions lub PublicKeyCredentialRequestOptions, aby określić "security-key", "client-device" i "hybrid" w preferowanej kolejności w tablicy.

Poniżej znajduje się przykładowa prośba o utworzenie danych logowania preferowana, Moduły uwierzytelniające "cross-platform" z wskazówką "security-key". Dzięki temu Interfejs Chrome przeznaczony dla użytkowników firmowych.

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

Gdy grupa z ograniczonym dostępem chce nadać priorytet scenariuszowi weryfikacji na różnych urządzeniach, wyślij żądanie uwierzytelniania preferowane przez moduły uwierzytelniające "cross-platform" z "hybrid" jako wskazówką.

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

Powiązane prośby dotyczące punktu początkowego

Z powiązanym źródłem Żądania, RP mogą aby używać kluczy dostępu z wielu domen. Tworzenie scentralizowanego logowania i korzystanie z protokołów federacji jest rozwiązaniem zalecanym większości witryn. Jeśli jednak masz wiele domen i federację, nie jest to możliwe, powiązane źródła mogą być rozwiązaniem.

Wszystkie żądania WebAuthn muszą określać identyfikator jednostki uzależnionej (RP ID) i wszystkie klucze dostępu są powiązane z jednym identyfikatorem grupy objętej ograniczeniami. Tradycyjnie źródło mogło określać tylko wartości identyfikator strony objętej ograniczeniami na podstawie jej domeny, więc w takim przypadku www.example.co.uk może określić identyfikator RP o wartości example.co.uk, ale nie example.com. Z powiązanym pochodzeniem Żądania, identyfikator RP, do którego zgłoszono roszczenie, można zweryfikować, pobierając dobrze znany plik JSON znajduje się pod adresem /.well-known/webauthn od domeny docelowej. Dlatego example.co.uk (oraz example.in, example.de itd.) mogą używać identyfikatora RP o wartości example.com, jeśli example.com określa je w tym formacie:

Adres 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"
  ]
}

Aby dowiedzieć się, jak skonfigurować żądania dotyczące powiązanego źródła, przeczytaj artykuł Zezwalaj na ponowne użycie klucza dostępu w witryny z powiązanym źródłem Prośby.

Serializacja JSON

Obiekty żądań i odpowiedzi WebAuthn mają wiele pól zawierających nieprzetworzone danych binarnych w elemencie ArrayBuffer, takich jak identyfikator danych logowania, identyfikator użytkownika czy test zabezpieczający. Jeśli strona chce użyć kodu JSON do wymiany tych danych ze swoim serwerem, plik binarny należy najpierw zakodować dane, np. Base64URL. Dodaje to zbędnych dla deweloperów, którzy chcą zacząć używać kluczy dostępu w swoich witrynach.

WebAuthn oferuje teraz interfejsy API do analizy PublicKeyCredentialCreationOptions oraz PublicKeyCredentialRequestOptions Obiekty żądania WebAuthn bezpośrednio z kodu JSON i serializowane PublicKeyCredential bezpośrednio do pliku JSON. Wszystkie pola o wartości SlateBuffer zawierające nieprzetworzone pola binarne są automatycznie konwertowane z lub na wartości zakodowane w Base64URL. Te interfejsy API są dostępne od Chrome 129.

Zanim utworzysz klucz dostępu, pobierz plik zakodowany w formacie JSON Obiekt PublicKeyCredentialCreationOptions z serwera i zdekoduj go za pomocą 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,
  });
  ...

Po utworzeniu klucza dostępu zakoduj otrzymane dane logowania za pomocą polecenia toJSON(), aby że może być ona przesłana na serwer.

  ...
  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);
  ...

Przed uwierzytelnieniem za pomocą klucza dostępu pobierz plik JSON zakodowany PublicKeyRequestCreationOptions z serwera i zdekoduj go za pomocą 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
  });
  ...

Po uwierzytelnieniu za pomocą klucza dostępu zakoduj otrzymane dane logowania za pomocą toJSON(), aby można było wysłać ją na serwer.

  ...
  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);
  ...

Więcej informacji

Aby dowiedzieć się więcej o WebAuthn i kluczach dostępu, zapoznaj się z tymi materiałami:

• Klucze dostępu | Chrome dla deweloperów
• Wprowadzenie do klucza dostępu po stronie serwera wdrożenie
• passkeys.dev