Chrome 128 and 129 introduces exciting new features for WebAuthn—theunderlying API to build passkey-based authentication systems.
- Hints: Hints give relying parties (RPs) better control over WebAuthnUI in the browser. They are especially helpful for enterprise users who wantto use security keys.
- Related origin requests: With related originrequests, RPs can make passkeys valid on multiple domains. If you own multiplesites, you can now enable your users to reuse their passkey across your sites,eliminating login friction.
- JSON serialization: JSON serialization APIs let you simplify an RP's frontend code by encoding and decoding options andcredentials passed to and from WebAuthn API.
Hints
With hints, relying parties (RP) can now specify UI preferences for creating apasskey or authenticating with a passkey.
Previously, when an RP wanted to restrict the authenticator the user can use tocreate a passkey or to authenticate with, they could useauthenticatorSelection.authenticatorAttachment to specify "platform" or"cross-platform". They respectively limit the authenticator to a platformauthenticatoror a roamingauthenticator.With hints, this specification can be more flexible.
The RP can use optional hints in the PublicKeyCredentialCreationOptions orPublicKeyCredentialRequestOptions to specify "security-key","client-device" and "hybrid" in a preference order in an array.
The following is an example credential creation request that prefers"cross-platform" authenticators with "security-key" as a hint. This tellsChrome to show a security key focused UI for enterprise users.
const credential = await navigator.credentials.create({ publicKey: { challenge: *****, hints: ['security-key'], authenticatorSelection: { authenticatorAttachment: 'cross-platform' } }});
When an RP wants to prioritize a cross-device verification scenario, they cansend an authentication request that prefers "cross-platform" authenticatorswith "hybrid" as a hint.
const credential = await navigator.credentials.create({ publicKey: { challenge: *****, residentKey: true, hints: ['hybrid'] authenticatorSelection: { authenticatorAttachment: 'cross-platform' } }});
With Related OriginRequests, RPs canmake passkeys usable from multiple domains. Building a centralized loginexperience and using federation protocols remains the recommended solution formost sites. But if you own multiple domains and federation isn't possible,related origins may be a solution.
All WebAuthn requests must specify a relying party ID (RP ID), and all passkeysare associated with a single RP ID. Traditionally, an origin could only specifyan RP ID based on its domain, so in that case www.example.co.uk could specifyan RP ID of example.co.uk, but not example.com. With Related OriginRequests, a claimed RP ID can be validated by fetching a well-known JSON filelocated at /.well-known/webauthn from the target domain. So example.co.uk(and example.in, example.de, and so on) could all use an RP ID ofexample.com if example.com specifies them in the following format:
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" ]}Learn how to set up Related Origin Requests at Allow passkey reuse across yoursites with Related OriginRequests.
JSON serialization
WebAuthn request and response objects have multiple fields that contain rawbinary data in an ArrayBuffer, such as the credential ID, user ID, or challenge.If a website wants to use JSON to exchange this data with its server, the binarydata must first be encoded, for example with Base64URL. This adds unnecessarycomplexity for developers that want to start using passkeys on their websites.
WebAuthn now offers APIs to parsePublicKeyCredentialCreationOptionsandPublicKeyCredentialRequestOptionsWebAuthn request objects directly from JSON, and serialize thePublicKeyCredentialresponse directly into JSON. All ArrayBuffer-valued fields that carry raw binarydata are automatically converted from or to their Base64URL-encoded values.These APIs are available from Chrome 129.
Before creating a passkey, fetch a JSON encodedPublicKeyCredentialCreationOptions object from the server and decode it usingPublicKeyCredential.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, }); ...After creating a passkey, encode the resulting credential using toJSON() sothat it can be sent to the 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); ...Before authenticating with a passkey, fetch a JSON encodedPublicKeyRequestCreationOptions from the server and decode it usingPublicKeyCredential.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 }); ...After authenticating with a passkey, encode the resulting credential usingtoJSON() method so that it can be sent to the 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); ...Learn more
To learn more about WebAuthn and passkeys, check out the following resources:
- Passkeys | Chrome for Developers
- Introduction to server-side passkeyimplementation
- passkeys.dev
