Introduzione di suggerimenti, richieste di origini correlate e serializzazione JSON per WebAuthn in Chrome

Le versioni 128 e 129 di Chrome introducono nuove entusiasmanti funzionalità per WebAuthn, l'API sottostante per creare sistemi di autenticazione basati su passkey.

Eiji Kitamura

• Suggerimenti: i suggerimenti offrono alle parti attendibili (RP) un migliore controllo sull'UI di WebAuthn nel browser. Sono particolarmente utili per gli utenti aziendali che vogliono utilizzare i token di sicurezza.
• Richieste di origini correlate: con le richieste di origini correlate, le parti soggette a limitazioni possono rendere valide le passkey su più domini. Se possiedi più siti, ora puoi consentire agli utenti di riutilizzare la passkey su tutti i tuoi siti, eliminando le difficoltà di accesso.
• Serializzazione JSON: le API di serializzazione JSON ti consentono di semplificare il codice frontend di un RP codificando e decodificando le opzioni e le credenziali passate all'API WebAuthn e viceversa.

Suggerimenti

Con hints, le parti attendibili (RP) ora possono specificare le preferenze dell'interfaccia utente per creare una passkey o autenticarsi con una passkey.

In precedenza, quando un RP voleva limitare l'autenticatore che l'utente poteva utilizzare per creare una passkey o per autenticarsi, poteva utilizzare authenticatorSelection.authenticatorAttachment per specificare "platform" o "cross-platform". Limitano rispettivamente l'autenticatore a un autenticatore di piattaforma o a un autenticatore in roaming. Con hints, questa specifica può essere più flessibile.

L'RP può utilizzare hints facoltativo in PublicKeyCredentialCreationOptions o PublicKeyCredentialRequestOptions per specificare "security-key", "client-device" e "hybrid" in un ordine di preferenza in un array.

Di seguito è riportato un esempio di richiesta di creazione delle credenziali che preferisce gli autenticatori "cross-platform" con "security-key" come suggerimento. In questo modo, Chrome mostra un'interfaccia utente incentrata sui token di sicurezza per gli utenti aziendali.

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

Quando un RP vuole dare la priorità a uno scenario di verifica cross-device, può inviare una richiesta di autenticazione che preferisce gli autenticatori "cross-platform" con "hybrid" come suggerimento.

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

Richieste di origine correlate

Con le richieste di origini correlate, le parti soggette a limitazioni possono rendere utilizzabili le passkey da più domini. La creazione di un'esperienza di accesso centralizzata e l'utilizzo di protocolli di federazione rimane la soluzione consigliata per la maggior parte dei siti. Tuttavia, se possiedi più domini e la federazione non è possibile, le origini correlate potrebbero essere una soluzione.

Tutte le richieste WebAuthn devono specificare un ID della terza parte attendibile (RP ID) e tutte le passkey sono associate a un singolo ID RP. In genere, un'origine poteva specificare solo un ID RP in base al proprio dominio, quindi in questo caso www.example.co.uk poteva specificare un ID RP di example.co.uk, ma non example.com. Con le richieste di origine correlata, un ID RP rivendicato può essere convalidato recuperando un file JSON ben noto situato all'indirizzo /.well-known/webauthn dal dominio di destinazione. Pertanto, example.co.uk (e example.in, example.de e così via) potrebbero utilizzare tutti un ID RP di example.com se example.com li specifica nel seguente formato:

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

Scopri come configurare le richieste di origine correlate in Consentire il riutilizzo delle passkey su tutti i siti con le richieste di origine correlate.

Serializzazione JSON

Gli oggetti di richiesta e risposta WebAuthn hanno più campi che contengono dati binari non elaborati in un ArrayBuffer, ad esempio l'ID della credenziale, l'ID utente o la verifica. Se un sito web vuole utilizzare JSON per scambiare questi dati con il proprio server, i dati binari devono prima essere codificati, ad esempio con Base64URL. Ciò aggiunge complessità non necessaria per gli sviluppatori che vogliono iniziare a utilizzare le passkey sui propri siti web.

WebAuthn ora offre API per analizzare gli oggetti di richiesta PublicKeyCredentialCreationOptions e PublicKeyCredentialRequestOptions WebAuthn direttamente da JSON e per serializzare la risposta PublicKeyCredential direttamente in JSON. Tutti i campi con valori ArrayBuffer che contengono dati binari non elaborati vengono convertiti automaticamente da o nei relativi valori codificati in Base64URL. Queste API sono disponibili a partire da Chrome 129.

Prima di creare una passkey, recupera un oggetto PublicKeyCredentialCreationOptions codificato in JSON dal server e decodificalo utilizzando 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,
  });
  ...

Dopo aver creato una passkey, codifica la credenziale risultante utilizzando toJSON() in modo che possa essere inviata al 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);
  ...

Prima di autenticarti con una passkey, recupera un PublicKeyRequestCreationOptions codificato in JSON dal server e decodificalo utilizzando 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
  });
  ...

Dopo l'autenticazione con una passkey, codifica la credenziale risultante utilizzando il metodo toJSON() in modo che possa essere inviata al 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);
  ...

Scopri di più

Per scoprire di più su WebAuthn e sulle passkey, consulta le seguenti risorse:

• Passkey | Chrome per gli sviluppatori
• Introduzione all'implementazione della passkey lato server
• passkeys.dev