@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
• Usage
• Supported Attestation Formats

Installation

This package is available on npm:

npm install @simplewebauthn/server

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:

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

Changelog

v2.0.0 - The one with -less and more Buffers

This major release includes improvements intended to make it easier to support passwordless and usernameless WebAuthn flows. Additional information returned from attestation verification can be used by RP's to further scrutinize the attestation now or in the future.

I also made the decision to reduce the amount of encoding from Buffer to Base64URL and decoding from Base64URL to Buffer throughout the library. Verification methods now return raw Buffers so that RP's are free to store and retrieve these values as they see fit without the library imposing any kind of encoding overhead that may complicate storage in a database, etc...

Packages:

• @simplewebauthn/server@2.0.0
• @simplewebauthn/typescript-types@2.0.0
• @simplewebauthn/browser@2.0.0
• @simplewebauthn/testing@2.0.0

Changes:

• [server] See Breaking Changes below.
• [typescript-types] See Breaking Changes below
• [browser] Version sync
• [testing] Version sync

Breaking Changes

• [server] The method verifyAttestationResponse() now returns a different data structure with additional information that RP's can use to more easily support passwordless and usernameless WebAuthn flows.
  • Additionally, Buffer values are now returned in place of previously-base64url-encoded values. This is intended to offer more flexibility in how these values are persisted without imposing an encoding scheme that may introduce undesirable overhead.

Before:

type VerifiedAttestation = {
  verified: boolean;
  userVerified: boolean;
  authenticatorInfo?: {
    fmt: ATTESTATION_FORMAT;
    counter: number;
    base64PublicKey: string;
    base64CredentialID: string;
  };
};

After:

type VerifiedAttestation = {
  verified: boolean;
  attestationInfo?: {
    fmt: ATTESTATION_FORMAT;
    counter: number;
    aaguid: string;
    credentialPublicKey: Buffer;
    credentialID: Buffer;
    credentialType: string;
    userVerified: boolean;
    attestationObject: Buffer;
  };
};

• [server] The method verifyAssertionResponse() now returns a different data structure to align with changes made to verifyAttestationResponse().

Before:

type VerifiedAssertion = {
  verified: boolean;
  authenticatorInfo: {
    counter: number;
    base64CredentialID: string;
  };
};

After:

type VerifiedAssertion = {
  verified: boolean;
  assertionInfo: {
    credentialID: Buffer;
    newCounter: number;
  };
};

• [server] The excludeCredentials argument in generateAttestationOptions() now expects a Buffer type for a credential's id property. Previously id needed to be a string. Existing credential IDs stored in base64url encoding can be easily converted to Buffer with a library like base64url:

Before:

const options = generateAttestationOptions({
  // ...
  excludeCredentials: [{
    id: 'PPa1spYTB680cQq5q6qBtFuPLLdG1FQ73EastkT8n0o',
    // ...
  }],
  // ...
});

After:

const options = generateAttestationOptions({
  // ...
  excludeCredentials: [{
    id: base64url.toBuffer('PPa1spYTB680cQq5q6qBtFuPLLdG1FQ73EastkT8n0o'),
    // ...
  }],
  // ...
});

• [server] The allowCredentials argument in generateAssertionOptions() now expects a Buffer type for a credential's id property. Previously id needed to be a string. Existing credential IDs stored in base64url encoding can be easily converted to Buffer with a library like base64url:

Before:

const options = generateAssertionOptions({
  // ...
  allowCredentials: [{
    id: 'PPa1spYTB680cQq5q6qBtFuPLLdG1FQ73EastkT8n0o',
    // ...
  }],
  // ...
});

After:

const options = generateAssertionOptions({
  // ...
  allowCredentials: [{
    id: base64url.toBuffer('PPa1spYTB680cQq5q6qBtFuPLLdG1FQ73EastkT8n0o'),
    // ...
  }],
  // ...
});

• [typescript-types] The AuthenticatorDevice type has been updated to expect Buffer's for credential data. Naming of its properties have also been updated to help maintain consistency with naming in the WebAuthn spec:

Before:

type AuthenticatorDevice = {
  publicKey: Base64URLString;
  credentialID: Base64URLString;
  counter: number;
  transports?: AuthenticatorTransport[];
};

After:

type AuthenticatorDevice = {
  credentialPublicKey: Buffer;
  credentialID: Buffer;
  counter: number;
  transports?: AuthenticatorTransport[];
};