@simplewebauthn/browser
Advanced tools
@simplewebauthn/browser is a JavaScript library that provides a simple interface for implementing WebAuthn (Web Authentication) in web applications. It allows developers to easily integrate passwordless authentication and second-factor authentication using hardware security keys, biometric sensors, and other authenticators that support the WebAuthn standard.
Registration
This feature allows users to register a new authenticator (e.g., a security key or biometric device) with the web application. The code sample demonstrates how to start the registration process, send the registration options to the client, and verify the registration response on the server.
const { startRegistration } = require('@simplewebauthn/browser');
async function register() {
const options = await fetch('/generate-registration-options').then(res => res.json());
const attResp = await startRegistration(options);
const verification = await fetch('/verify-registration', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(attResp),
}).then(res => res.json());
if (verification.verified) {
console.log('Registration successful!');
} else {
console.log('Registration failed.');
}
}Authentication
This feature allows users to authenticate using a previously registered authenticator. The code sample demonstrates how to start the authentication process, send the authentication options to the client, and verify the authentication response on the server.
const { startAuthentication } = require('@simplewebauthn/browser');
async function authenticate() {
const options = await fetch('/generate-authentication-options').then(res => res.json());
const assertionResp = await startAuthentication(options);
const verification = await fetch('/verify-authentication', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(assertionResp),
}).then(res => res.json());
if (verification.verified) {
console.log('Authentication successful!');
} else {
console.log('Authentication failed.');
}
}fido2-lib is a comprehensive library for implementing FIDO2 and WebAuthn server-side functionality. It provides tools for generating and verifying registration and authentication data. Compared to @simplewebauthn/browser, fido2-lib focuses more on the server-side implementation and offers more granular control over the WebAuthn process.
webauthn is a library that provides utilities for implementing WebAuthn in web applications. It includes both client-side and server-side components. While it offers similar functionalities to @simplewebauthn/browser, it may require more configuration and setup to get started.
passport-fido2 is a Passport.js strategy for FIDO2 authentication. It integrates with the Passport.js authentication middleware for Node.js, making it easy to add FIDO2 authentication to existing Passport.js-based applications. Unlike @simplewebauthn/browser, which is focused on client-side interactions, passport-fido2 is designed for server-side integration with Passport.js.
This package is available on npm:
npm install @simplewebauthn/browser
This package can also be installed via unpkg by including the following script in your page's <head> element. The library's methods will be available on the global SimpleWebAuthnBrowser object.
NOTE: The only difference between the two packages below is that the ES5 bundle includes TypeScript's
tslibruntime code. This adds some bundle size overhead, but does enable use ofsupportsWebAuthn()in older browsers to show appropriate UI when WebAuthn is unavailable.
If you need to support WebAuthn feature detection in deprecated browsers like IE11 and Edge Legacy, include the ES5 version:
<script src="https://unpkg.com/@simplewebauthn/browser/dist/bundle/index.es5.umd.min.js"></script>
If you only need to support modern browsers, include the ES2018 version:
<script src="https://unpkg.com/@simplewebauthn/browser"></script>
You can find in-depth documentation on this package here: https://simplewebauthn.dev/docs/packages/browser
v4.0.0 - The one with some new names
A lot has happened to me since I first launched SimpleWebAuthn back in May 2020. My understanding of WebAuthn has grown by leaps and bounds thanks in part to my representing Duo/Cisco in the W3C's WebAuth Adoption Working Group. I'm now in a point in my life in which it's no longer sufficient to think, "what's in SimpleWebAuthn's best interests?" Now, I have an opportunity to think bigger - "what's in the WebAuthn API's best interests?"
While early on I thought "attestation" and "assertion" were important names to WebAuthn, I've since come to better appreciate the spec's efforts to encourage the use of "registration" and "authentication" instead. To that end I decided it was time to rename all of the project's various public methods and types to get as much as possible to use "registration" and "authentication" instead.
This release is one of the more disruptive because it affects everyone who's used SimpleWebAuthn to date. The good news is that, while method and type names have changed, their capabilities remain the same. Updating your code to this version of SimpleWebAuthn should only involve renaming existing method calls and type annotations.
Please take the time to read the entire changelog for this release! There are a handful of new features also included that users with advanced use cases will find helpful. The simple use cases of the library remain unchanged - most new features are for power users who require extra scrutiny of authenticators that interact with their website and are otherwise opt-in as needed.
Packages:
Changes:
platformAuthenticatorIsAvailable() has been
added for detecting when hardware-bound authenticators like Touch ID, Windows Hello, etc... are
available for use.
More info is available here.SettingsService can be used to configure aspects of SimpleWebAuthn like
root certs for enhanced registration response verification or for validating FIDO MDS BLOBs with
MetadataService.
More info is available here.'android-key', 'android-safetynet', 'apple''@simplewebauthn/server/helpers' (not a new package, but a subpath.) These methods can be used,
for example, to process non-standard responses that are not officially part of the WebAuthn spec
and thus unlikely to ever be supported by SimpleWebAuthn.MetadataService now supports
FIDO Alliance Metadata Service version 3.0.The quickest way to update your code is to try changing "attestation" to "registration" and "assertion" to "authentication" in the name of whatever method or type is no longer working and see if that fixes it (exceptions to this rule are called out with asterisks below.) If it doesn't, check out PR #147 to see all of the renamed methods and types and try to cross-reference the original to see what it was renamed to.
Examples:
generateAttestationOptions()->generateRegistrationOptions()GenerateAttestationOptionsOpts->GenerateRegistrationOptionsOptsverifyAssertionResponse()->verifyAuthenticationResponse()VerifiedAttestation->VerifiedRegistrationResponse(*)VerifiedAssertion->VerifiedAuthenticationResponse(*)startAttestation()->startRegistration()startAssertion()->startAuthentication()These examples are not a comprehensive list of all the renamed methods! Rather these are examples of how method names were changed to try and eliminate "attestation" and "assertion" from the public API of both @simplewebauthn/browser and @simplewebauthn/server.
opts argument for MetadataService.initialize() is now optional.opts.mdsServers argument for MetadataService.initialize(opts) is now a simple
array of URL strings to FIDO Alliance MDSv3-compatible servers. If no value is specified then
MetadataService will query the
official FIDO Alliance Metadata Service version 3.0.See here for more information about the updated
MetadataService.
supportsWebAuthn() has been renamed to browserSupportsWebAuthn() in an
effort to make the method convey a clearer idea of what supports WebAuthn.FAQs
SimpleWebAuthn for Browsers
The npm package @simplewebauthn/browser receives a total of 145,941 weekly downloads. As such, @simplewebauthn/browser popularity was classified as popular.
We found that @simplewebauthn/browser demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Socket's package search now displays weekly downloads for npm packages, helping developers quickly assess popularity and make more informed decisions.
Security News
A Stanford study reveals 9.5% of engineers contribute almost nothing, costing tech $90B annually, with remote work fueling the rise of "ghost engineers."
Research
Security News
Socket’s threat research team has detected six malicious npm packages typosquatting popular libraries to insert SSH backdoors.