@simplewebauthn/server

What is @simplewebauthn/server?

@simplewebauthn/server is a Node.js library that provides server-side functionality for WebAuthn, a web standard for secure authentication using public key cryptography. It helps in implementing registration and authentication flows for WebAuthn, making it easier to integrate strong, passwordless authentication into web applications.

What are @simplewebauthn/server's main functionalities?

Registration

This feature allows you to generate registration options for a new user and verify the registration response from the client. It ensures that the registration process is secure and follows the WebAuthn protocol.

const { generateRegistrationOptions, verifyRegistrationResponse } = require('@simplewebauthn/server');

// Generate registration options
const options = generateRegistrationOptions({
  rpName: 'Example Corp',
  rpID: 'example.com',
  userID: 'user-id',
  userName: '[e-mail]',
  attestationType: 'indirect',
  authenticatorSelection: {
    userVerification: 'preferred',
  },
});

// Verify registration response
const verification = verifyRegistrationResponse({
  credential: response,
  expectedChallenge: options.challenge,
  expectedOrigin: 'https://example.com',
  expectedRPID: 'example.com',
});

Authentication

This feature allows you to generate authentication options for an existing user and verify the authentication response from the client. It ensures that the authentication process is secure and follows the WebAuthn protocol.

const { generateAuthenticationOptions, verifyAuthenticationResponse } = require('@simplewebauthn/server');

// Generate authentication options
const options = generateAuthenticationOptions({
  rpID: 'example.com',
  userVerification: 'preferred',
});

// Verify authentication response
const verification = verifyAuthenticationResponse({
  credential: response,
  expectedChallenge: options.challenge,
  expectedOrigin: 'https://example.com',
  expectedRPID: 'example.com',
  authenticator: authenticator,
});

Other packages similar to @simplewebauthn/server

fido2-lib

fido2-lib is a library for implementing FIDO2 and WebAuthn server functionality. It provides similar features to @simplewebauthn/server, such as registration and authentication flows, but may require more manual setup and configuration.

webauthn

webauthn is another library for implementing WebAuthn server functionality. It offers a straightforward API for handling registration and authentication, similar to @simplewebauthn/server, but with a different approach to configuration and usage.

README

@simplewebauthn/server

• Installation
  • Node LTS 20.x or higher
  • Deno v1.33.x or higher
• Usage
• Supported Attestation Formats

Installation

Node LTS 20.x or higher

This package is available on npm and supports both CommonJS and ECMAScript modules (ESM) projects:

npm install @simplewebauthn/server

Deno v1.33.x or higher

It is also available for import into Deno projects from deno.land/x:

import {...} from 'https://deno.land/x/simplewebauthn/deno/server.ts';

Usage

You can find in-depth documentation on this package here: https://simplewebauthn.dev/docs/packages/server

Supported Attestation Formats

SimpleWebAuthn supports all current WebAuthn attestation formats, including:

• Android Key
• Android SafetyNet
• Apple
• FIDO U2F
• Packed
• TPM
• None

Changelog

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.

Packages

• @simplewebauthn/browser@11.0.0
• @simplewebauthn/server@11.0.0
• @simplewebauthn/types@11.0.0

Changes

• [browser] [server] A new 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)
• [browser] A new 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)
• [server] [types] The 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)
• [server] 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)
• [server] TPM attestation verification recognizes the corrected TPM manufacturer identifier for IBM (#610)
• [server] Types for the defunct authenticator extensions uvm and dpk have been removed (#611)

Breaking Changes

[browser] Positional arguments in startRegistration() and startAuthentication() have been replaced by a single object

Property 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 });

[server] [types] The AuthenticatorDevice type has been renamed to WebAuthnCredential

AuthenticatorDevice.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,
});