Introductie van hints, gerelateerde oorsprongsverzoeken en JSON-serialisatie voor WebAuthn in Chrome

Chrome 128 en 129 introduceren opwindende nieuwe functies voor WebAuthn, de onderliggende API om op wachtwoord gebaseerde authenticatiesystemen te bouwen.

Eiji Kitamura

• Hints : Hints geven Relying Parties (RP's) betere controle over de WebAuthn-gebruikersinterface in de browser. Ze zijn vooral handig voor zakelijke gebruikers die beveiligingssleutels willen gebruiken.
• Gerelateerde oorsprongsverzoeken : met gerelateerde oorsprongsverzoeken kunnen RP's toegangssleutels geldig maken op meerdere domeinen. Als u meerdere sites bezit, kunt u uw gebruikers nu de mogelijkheid bieden hun toegangscode op al uw sites te hergebruiken, waardoor inlogproblemen worden geëlimineerd.
• JSON-serialisatie : Met JSON-serialisatie-API's kunt u de frontend-code van een RP vereenvoudigen door opties en inloggegevens te coderen en te decoderen die worden doorgegeven van en naar de WebAuthn API.

Tips

Met hints kunnen Relying Parties (RP) nu UI-voorkeuren opgeven voor het maken van een wachtwoordsleutel of het verifiëren met een wachtwoordsleutel.

Als een RP eerder de authenticator wilde beperken die de gebruiker kan gebruiken om een ​​toegangssleutel te maken of om zich te authenticeren, kon hij authenticatorSelection.authenticatorAttachment gebruiken om "platform" of "cross-platform" op te geven. Ze beperken de authenticator respectievelijk tot een platformauthenticator of een roamingauthenticator . Met hints kan deze specificatie flexibeler zijn.

De RP kan optionele hints in PublicKeyCredentialCreationOptions of PublicKeyCredentialRequestOptions gebruiken om "security-key" , "client-device" en "hybrid" in een voorkeursvolgorde in een array op te geven.

Het volgende is een voorbeeld van een aanvraag voor het aanmaken van inloggegevens, waarbij de voorkeur wordt gegeven aan "cross-platform" authenticators met "security-key" als hint. Dit vertelt Chrome om een ​​op beveiligingssleutels gerichte gebruikersinterface voor zakelijke gebruikers weer te geven.

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

Wanneer een RP prioriteit wil geven aan een verificatiescenario voor meerdere apparaten, kan hij of zij een authenticatieverzoek sturen waarin de voorkeur wordt gegeven aan "cross-platform" authenticators met "hybrid" als hint.

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

Gerelateerde oorsprongsverzoeken

Met Gerelateerde Origin Requests kunnen RP's toegangssleutels bruikbaar maken vanuit meerdere domeinen. Het bouwen van een gecentraliseerde inlogervaring en het gebruik van federatieprotocollen blijft voor de meeste sites de aanbevolen oplossing. Maar als u meerdere domeinen bezit en federatie niet mogelijk is, kan een gerelateerde oorsprong een oplossing zijn.

Alle WebAuthn-aanvragen moeten een Relying Party ID (RP ID) specificeren, en alle wachtwoordsleutels zijn gekoppeld aan één RP ID. Traditioneel kon een origin alleen een RP-ID specificeren op basis van zijn domein, dus in dat geval zou www.example.co.uk een RP-ID van example.co.uk kunnen specificeren, maar niet example.com . Met gerelateerde oorsprongsverzoeken kan een geclaimde RP-ID worden gevalideerd door een bekend JSON-bestand op te halen dat zich op /.well-known/webauthn bevindt van het doeldomein. example.co.uk (en example.in , example.de , enzovoort) kunnen dus allemaal een RP-ID van example.com gebruiken als example.com deze in de volgende indeling opgeeft:

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

Leer hoe u gerelateerde oorsprongsverzoeken instelt op Hergebruik van wachtwoordsleutels op uw sites toestaan ​​met gerelateerde oorsprongsverzoeken .

JSON-serialisatie

WebAuthn-aanvraag- en antwoordobjecten hebben meerdere velden die onbewerkte binaire gegevens in een ArrayBuffer bevatten, zoals de referentie-ID, gebruikers-ID of uitdaging. Als een website JSON wil gebruiken om deze gegevens uit te wisselen met zijn server, moeten de binaire gegevens eerst worden gecodeerd, bijvoorbeeld met Base64URL. Dit voegt onnodige complexiteit toe voor ontwikkelaars die wachtwoordsleutels op hun websites willen gaan gebruiken.

WebAuthn biedt nu API's voor het parseren van PublicKeyCredentialCreationOptions en PublicKeyCredentialRequestOptions WebAuthn-verzoekobjecten rechtstreeks vanuit JSON, en het PublicKeyCredential- antwoord rechtstreeks in JSON te serialiseren. Alle velden met een ArrayBuffer-waarde die onbewerkte binaire gegevens bevatten, worden automatisch geconverteerd van of naar hun Base64URL-gecodeerde waarden. Deze API's zijn beschikbaar via Chrome 129.

Voordat u een toegangssleutel maakt, haalt u een JSON-gecodeerd PublicKeyCredentialCreationOptions object op van de server en decodeert u dit met 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,
  });
  ...

Nadat u een toegangssleutel hebt gemaakt, codeert u de resulterende referentie met toJSON() zodat deze naar de server kan worden verzonden.

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

Voordat u authenticeert met een toegangssleutel, haalt u een JSON-gecodeerde PublicKeyRequestCreationOptions op van de server en decodeert u deze met 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
  });
  ...

Na authenticatie met een toegangssleutel codeert u de resulterende referentie met behulp van toJSON() methode, zodat deze naar de server kan worden verzonden.

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

Meer informatie

Raadpleeg de volgende bronnen voor meer informatie over WebAuthn en wachtwoordsleutels:

• Wachtwoorden | Chrome voor ontwikkelaars
• Inleiding tot de implementatie van wachtwoordsleutels op de server
• wachtwoordsleutels.dev