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. Some JS UI libraries, like VueJS, may not use native click handling without the use of framework-specific functionality like Vue's .native modifier.
• Safari only supports the use of XHR and fetch within click handlers for requesting WebAuthn registration and authentication options. (Fixed as of February 2021. See here)
• Not all browsers on iOS or macOS support Touch ID or Face ID. Check Supported Devices for more information on which iOS and macOS browsers support which Apple-specific hardware authenticator. (Fixed as of iOS 14.5. See here)

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.