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()
andstartAuthentication
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(Fixed as of February 2021. See here)fetch
within click handlers for requesting WebAuthn registration and authentication options.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.