@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
v11.0.0 - The one that auto-registers
Say hello to support for automatic passkey registration, support for valid conditional UI <input>
elements stashed away in web components, and to the new WebAuthnCredential type that modernizes
some logic within.
There are some breaking changes in this release! Please see Breaking Changes below for refactor guidance.
useAutoRegister argument has been added to startRegistration() to
support attempts to automatically register passkeys for users who just completed non-passkey auth.
verifyRegistrationResponse() has gained a new requireUserPresence option that can be set to
false when verifying responses from startRegistration({ useAutoRegister: true, ... })
(#623)verifyBrowserAutofillInput argument has been added to
startAuthentication() to disable throwing an error when a correctly configured <input> element
cannot be found (but perhaps a valid one is present in a web component shadow's DOM)
(#621)AuthenticatorDevice type has been renamed to WebAuthnCredential and
has had its properties renamed. The return value out of verifyRegistrationResponse() and
corresponding inputs into verifyAuthenticationResponse() have been updated accordingly. See
Breaking Changes below for refactor guidance
(#625)verifyRegistrationResponse() now verifies that the authenticator data AAGUID
matches the leaf cert's id-fido-gen-ce-aaguid extension AAGUID when it is present
(#609)uvm and dpk have been removed
(#611)startRegistration() and startAuthentication() have been replaced by a single objectProperty names in the object match the names of the previously-positional arguments. To update existing implementations, wrap existing options in an object with corresponding properties:
Before:
startRegistration(options);
startAuthentication(options, true);
After:
startRegistration({ optionsJSON: options });
startAuthentication({ optionsJSON: options, useBrowserAutofill: true });
AuthenticatorDevice type has been renamed to WebAuthnCredentialAuthenticatorDevice.credentialID and AuthenticatorDevice.credentialPublicKey have been shortened
to WebAuthnCredential.id and WebAuthnCredential.publicKey respectively.
verifyRegistrationResponse() has been updated accordingly to return a new credential value of
type WebAuthnCredential. Update code that stores credentialID, credentialPublicKey, and
counter out of verifyRegistrationResponse() to store credential.id, credential.publicKey,
and credential.counter instead:
Before:
const { registrationInfo } = await verifyRegistrationResponse({...});
storeInDatabase(
registrationInfo.credentialID,
registrationInfo.credentialPublicKey,
registrationInfo.counter,
body.response.transports,
);
After:
const { registrationInfo } = await verifyRegistrationResponse({...});
storeInDatabase(
registrationInfo.credential.id,
registrationInfo.credential.publicKey,
registrationInfo.credential.counter,
registrationInfo.credential.transports,
);
Update calls to verifyAuthenticationResponse() to match the new credential argument that
replaces the authenticator argument:
Before:
import { AuthenticatorDevice } from '@simplewebauthn/types';
const authenticator: AuthenticatorDevice = {
credentialID: ...,
credentialPublicKey: ...,
counter: 0,
transports: [...],
};
const verification = await verifyAuthenticationResponse({
// ...
authenticator,
});
After:
import { WebAuthnCredential } from '@simplewebauthn/types';
const credential: WebAuthnCredential = {
id: ...,
publicKey: ...,
counter: 0,
transports: [...],
};
const verification = await verifyAuthenticationResponse({
// ...
credential,
});
FAQs
SimpleWebAuthn for Browsers
The npm package @simplewebauthn/browser receives a total of 173,511 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
Ransomware payment rates hit an all-time low in 2024 as law enforcement crackdowns, stronger defenses, and shifting policies make attacks riskier and less profitable.
Security News
require(esm) backported to Node.js 20, easing the transition to ESM-only packages and reducing complexity for developers as Node 18 nears end-of-life.
Security News
PyPI now supports iOS and Android wheels, making it easier for Python developers to distribute mobile packages.