Skip to main content

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().
  • Websites viewed in Safari running in iOS 17.4 and macOS 14.4 and later are free to invoke WebAuthn as needed. There is an internal rate limiter within Safari to prevent abuse of WebAuthn, but "well-behaving" Relying Parties should no longer have user gesture requirements to contend with anymore (see below.)
    • Versions of Safari running in iOS 17.3 and macOS 14.3 and earlier...
      • ...may experience issues with session replay tools such as Sentry Session Replay or LogRocket causing problems with user gesture detection.
      • ...allow websites to 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:

Firefox​

WebAuthn responses from security keys that generate keypairs using Ed25519 (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.