Introduction

Modern authentication is evolving beyond passwords. With the rise of phishing attacks, credential stuffing, and data breaches, traditional username-password authentication is no longer sufficient on its own. Passkeys (based on the WebAuthn and FIDO2 standards) offer a secure, passwordless authentication method that relies on public-key cryptography and device-based biometrics such as fingerprint, Face ID, or Windows Hello PIN.

This article explains how to implement single passkey authentication using a Node.js backend with Express, MongoDB (Mongoose), and the WebAuthn server libraries. The implementation supports:

Enabling a passkey for a user
Validating the registration response
Generating authentication challenges
Verifying login attempts
Disabling passkey authentication

The design is intentionally limited to one passkey per user tho.

Architecture Overview

The authentication flow is divided into two major phases:

1. Registration (Passkey Enrollment)

Generate a challenge
Send options to the frontend
User registers biometric credential
Verify response
Store credential information in database

2. Authentication (Passkey Login)

Generate challenge
Send options to frontend
User authenticates using biometric device
Verify response
Issue session token

Each user has exactly one passkey credential stored in the database.

User Schema Design

Your User schema includes two important fields:

biometricsEnabled: {
  type: Boolean,
  enum: [true, false],
  select: false,
  required: false,
  default: undefined
},
biometricsToken: {
  challenge: {
    type: String,
    default: undefined,
    select: false,
    required: false
  },
  credentialID: {
    type: String,
    default: undefined,
    select: false,
    required: false
  },
  credentialPublicKey: {
    type: String,
    default: undefined,
    select: false,
    required: false
  },
  counter: {
    type: Number,
    default: 0,
    select: false,
    required: false
  },
  name: {
    type: String,
    default: undefined,
    select: false,
    required: false
  }
}

Field Explanation

biometricsEnabled: Indicates whether passkey authentication is active.
challenge: Temporary cryptographic challenge used for validation.
credentialID: Unique identifier for the passkey credential.
credentialPublicKey: Public key used for verifying authentication.
counter: Protects against replay attacks.
name: Label for the credential (usually username or device name).

Only one credential is stored per user, ensuring single-device passkey usage.

API Routes

router.route('/2fa/passkey/enable').put(protect, enablePasskey);
router.route('/2fa/passkey/disable').put(protect, disablePasskey);
router.route('/2fa/passkey/validate/:id').put(protect, validatePasskey);
router.route('/2fa/passkey/challenge/:id').put(challengePasskey);
router.route('/2fa/passkey/verify/:id').put(verifyPasskey);

Each route corresponds to a stage of the WebAuthn lifecycle:

Route	Purpose
enable	Generate registration options
validate	Verify registration response
challenge	Generate login challenge
verify	Verify login response
disable	Remove stored credential

Enabling Passkey Registration

exports.enablePasskey = asyncHandler(async (req, res, next) => {
  const options = await generateRegistrationOptions({
    rpName: process.env.WEBSITE_NAME,
    rpID: new URL(process.env.WEBSITE_URL).host,
    userID: Buffer.from(req.user._id),
    userName: req.user.username,
    attestationType: 'none',
    authenticatorSelection: {
      userVerification: 'required',
      residentKey: 'required',
      authenticatorAttachment: 'platform',
    },
    requireResidentKey: true,
  });

Purpose

This method generates WebAuthn registration options for the user’s device.

Key configuration choices:

authenticatorAttachment: 'platform' restricts registration to built-in authenticators (Face ID, Touch ID, Windows Hello).
userVerification: 'required' enforces biometric or PIN verification.
residentKey: 'required' allows passwordless login.

The challenge is stored in the database:

biometricsEnabled: false,
biometricsToken: {
  challenge: options.challenge,
  credentialID: undefined,
  credentialPublicKey: undefined,
  counter: 0,
  name: undefined,
}

This ensures the system waits for verification before enabling biometrics.

Disabling Passkey

exports.disablePasskey = asyncHandler(async (req, res, next) => {
  const user = await User.findByIdAndUpdate(
    { _id: req.user._id },
    {
      $set: {
        biometricsEnabled: false,
        biometricsToken: {
          challenge: null,
          credentialID: null,
          credentialPublicKey: null,
          counter: 0,
          name: null,
        },
      },
    }
  )

This removes all biometric credentials and resets the account to non-passkey mode. It is critical for account recovery and user control.

Validating Registration Response

exports.validatePasskey = asyncHandler(async (req, res, next) => {
  const { passkey } = req.body

The backend verifies the response using:

verifyRegistrationResponse({
  response: passkey,
  expectedChallenge: initialUser.biometricsToken.challenge,
  expectedOrigin: process.env.WEBSITE_URL,
  expectedRPID: new URL(process.env.WEBSITE_URL).host,
})

If verification succeeds, credential information is stored:

credentialID: Buffer.from(validation.registrationInfo.credential.id).toString('base64url'),
credentialPublicKey: Buffer.from(validation.registrationInfo.credential.publicKey).toString('base64url'),
counter: validation.registrationInfo.credential.counter,

Finally:

biometricsEnabled: true

This marks the account as fully registered for passkey authentication.

Generating Authentication Challenge

exports.challengePasskey = asyncHandler(async (req, res, next) => {
  const options = await generateAuthenticationOptions({
    userVerification: 'required',
    rpID: new URL(process.env.WEBSITE_URL).host,
  })

This creates a login challenge that is sent to the client. The challenge is stored again in the database so it can be verified later.

This step does not authenticate the user. It prepares the cryptographic proof request.

Verifying Authentication Response

exports.verifyPasskey = asyncHandler(async (req, res, next) => {
  const { authResponse } = req.body

Credential data is reconstructed:

const authCredential = {
  id: initialUser.biometricsToken.credentialID,
  publicKey: base64urlToBuffer(initialUser.biometricsToken.credentialPublicKey),
  counter: initialUser.biometricsToken.counter,
  transports: ['internal'],
}

Verification is performed:

verifyAuthenticationResponse({
  response: authResponse,
  expectedChallenge: initialUser.biometricsToken.challenge,
  expectedOrigin: process.env.WEBSITE_URL,
  expectedRPID: new URL(process.env.WEBSITE_URL).host,
  credential: authCredential,
})

If valid:

Counter is updated
Token is issued
User is logged in securely

Security Benefits

This implementation provides:

Phishing resistance
Replay attack prevention (via counter)
Device-bound authentication
No password transmission
Strong cryptographic proof

Why Single Passkey?

A single-passkey system simplifies:

Database schema
Revocation logic
Recovery flows
Support requests
UI complexity

While multi-device support is desirable, single-passkey authentication is ideal for:

MVPs
Internal tools
High-security systems
Controlled user environments

Frontend Integration (Conceptual)

On the frontend, you would:

Call /enable
Use navigator.credentials.create()
Send response to /validate
On login call /challenge
Use navigator.credentials.get()
Send response to /verify

Best Practices

Always validate origin and rpID
Never store private keys
Base64URL encode buffers
Enforce HTTPS
Require email confirmation before enabling passkeys
Use platform authenticators only if security is priority
Provide a disable option for recovery

Implementing [Single] Passkey Authentication with WebAuthn in a Node.js API

Newsletter