Browser Quirks

Safari

When adding support for WebAuthn, special considerations must be made for the Safari browser on both iOS and macOS:

• @simplewebauthn/browser's startRegistration() and startAuthentication() must be called in a native click listener (user gesture detection). Some JS UI libraries may not use native click handling without the use of framework-specific functionality.
• Safari only supports the use of XHR and fetch within native click handlers for requesting WebAuthn registration and authentication options. fetch and XHR wrappers like ofetch or axios might cause problems with user gesture detection. To avoid problems with user gesture detection, it's best to have a single native fetch or XHR call and not use any other async operations (promises, timeouts, ...) before calling startRegistration() / startAuthentication().
• Session replay tools such as Sentry Session Replay or LogRocket might cause problems with user gesture detection.
• You can make one call to navigator.credentials.create() or navigator.credentials.get() (via startRegistration() or startAuthentication() respectively) for every browser navigation event without requiring a user gesture, e.g. to support Conditional UI. When using a Single-Page Application (SPA) this limit only gets reset after reloading the page.

Microsoft Edge

The Microsoft Edge browser refers to two different browsers: the original release from 2015 (now called "Microsoft Edge Legacy"), and the Chromium-based version from June 2020 that inherited the name "Microsoft Edge".

When adding support for WebAuthn, special considerations must be made for Microsoft Edge Legacy:

• The browser global TextEncoder is not supported. This means @simplewebauthn/browser will not work in this browser without a polyfill for this API. MDN includes a spec-compliant polyfill that can be copied into your project. Various browser polyfill libraries exist on NPM as well.

Firefox

WebAuthn responses from security keys that generate keypairs using Ed12259 (i.e. -8) can fail response verification during registration due to a bug in the browser itself. This can manifest as the following error message from @simplewebauthn/server methods:

Error: Leftover bytes detected while parsing authenticator data

These responses may also fail to be verified by verifyRegistrationResponse(), even when the same server setup and security key are used in a different browser:

const verifiedFirefox = await verifyRegistrationResponse({ ... });

console.log(verifiedFirefox.verified); // false

The issue was caused by a bug in authenticator-rs (mozilla/authenticator-rs#292), and according to Mozilla (Bugzilla Bug 1852812) should be resolved as of Firefox 119.