@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
v7.0.0 - The one that sets the library loose
The highlight of this release is the rearchitecture of @simplewebauthn/server to start allowing
it to be used in more environments than Node. This was accomplished by refactoring the library
completely away from Node's Buffer type and crypto package, and instead leveraging Uint8Array
and the WebCrypto Web API for all
cryptographic operations. This means that, hypothetically, this library can now also work in any
non-Node environment that provides access to the WebCrypto API on the global crypto object.
Existing Node support is still first-class! In fact because @simplewebauth/server still builds to CommonJS it will continue to be tricky to incorporate the library in non-Node, ESM-only environments that do not support CommonJS modules (whether natively, via a bundler, etc...) A future update will attempt to fix this to offer better support for use in ESM-only projects with support for WebCrypto (e.g. Deno).
Please read all of the changes below! There are significant breaking changes in this update and additional information has been included to help adapt existing projects to the newest version of these libraries.
Packages:
Changes:
@simplewebauthn/server/helpers now includes several new helpers for working with
WebAuthn-related data types that should work in all run times:
isoCBOR for working with CBOR-encoded valuesisoCrypto for leveraging the WebCrypto API when working with various WebAuthn/FIDO2 data
structuresisoBase64URL for encoding and decoding values into base64url (with optional base64 support)isoUint8Array for working with Uint8Arrayscose for working with COSE-related methods and typesverifyRegistrationResponse() are now a
Uint8Array instead of a Buffer. They will need to be passed into Buffer.from(...) to convert
them to Buffer if needed:
aaguidauthDataclientDataHashcredentialIDcredentialPublicKeyrpIdHashverifyAuthenticationResponse() are now a
Uint8Array instead of a Buffer. They will need to be passed into Buffer.from(...) to convert
them to Buffer if needed:
credentialIDisBase64URLString() helper is now isoBase64URL.isBase64url()decodeCborFirst() helper is now isoCBOR.decodeFirst()convertPublicKeyToPEM() helper has been removedRegistrationCredentialJSON type has been replaced by the RegistrationResponseJSON typeAuthenticationCredentialJSON type has been replaced by the AuthenticationResponseJSON
typeRegistrationCredentialJSON.transports has been relocated into
RegistrationResponseJSON.response.transports to mirror response structure in the WebAuthn specverifyRegistrationResponse() method has had its credential argument renamed to
responseverifyAuthenticationResponse() method has had its credential argument renamed to
responsegenerateRegistrationOptions() now marks user verification as "preferred" during
registration and authentication (to reduce some user friction at the browser+authenticator level),
and requires user verification during response verification. See below for refactor tips
(#307)verifyRegistrationResponse()Before
const verification = await verifyRegistrationResponse({
credential: attestationFIDOU2F,
// ...
});
After
const verification = await verifyRegistrationResponse({
credential: attestationFIDOU2F,
// ...
requireUserVerification: false,
});
verifyAuthenticationResponse()Before
const verification = await verifyAuthenticationResponse({
credential: assertionResponse,
// ...
});
After
const verification = await verifyAuthenticationResponse({
credential: assertionResponse,
// ...
requireUserVerification: false,
});
generateRegistrationOptions() now defaults to preferring the creation of
discoverable credentials. See below for refactor tips
(#324)generateRegistrationOptions()Before
const options = generateRegistrationOptions({
rpName: 'SimpleWebAuthn',
rpID: 'simplewebauthn.dev',
userID: '1234',
userName: 'usernameHere',
});
After
const options = generateRegistrationOptions({
rpName: 'SimpleWebAuthn',
rpID: 'simplewebauthn.dev',
userID: '1234',
userName: 'usernameHere',
authenticatorSelection: {
// See https://www.w3.org/TR/webauthn-2/#enumdef-residentkeyrequirement
residentKey: 'discouraged',
},
});
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.