Developers have to hash passwords, salt them, rate-limit login attempts, and build "forgot password" flows that nobody enjoys using.

Fortunately, passkeys address many of these issues․ Instead of providing a password‚ users can confirm their identity with a different type of authenticator they use on other devices‚ like fingerprints, facial recognition, or a PIN․ The authenticator signs a challenge using a cryptographic key stored on the device and is never shared with others․

This tutorial shows you how to build an app that doesn't use traditional passwords. The backend is a NestJS API that stores users and their passkeys in PostgreSQL. The frontend is a Next.js app where users sign up and sign in with nothing but an email address and a passkey.

You'll use SimpleWebAuthn, a well-maintained TypeScript library to simplify tasks involving WebAuthn cryptography and data parsing․

By the end of this article, you should have what you need to implement passkey registration and authentication for your website and validate passkeys on your server securely. You'll also learn about potential risks and problems with passkeys that could impact your app or user accounts so you can take steps to prevent them.

You can find the complete source code on GitHub.

Table of Contents

• The Problems with Password-Based Authentication
• How Passkeys Solve These Problems
• Prerequisites
• What Are Passkeys?
• How Passkey Authentication Works
• Project Structure
• How to Set Up the NestJS Backend
  • Create the Database
  • Add Environment Variables
  • Connect to PostgreSQL
• How to Define the Database Entities
• How to Register a Passkey on the Server
  • Generate Registration Options
  • Verify the Registration Response
• How to Sign In with a Passkey on the Server
  • Generate Authentication Options
  • Verify the Authentication Response
• How to Expose the Auth Endpoints
  • How to Protect Routes with a JWT
  • How to Register the Auth Module
• How to Set Up the Next.js Frontend
• How to Build the Sign Up Page
• How to Build the Sign In Page
• How to Show Helpful Error Messages
• How to Test Your App
• Security Mistakes to Avoid
  • Encoding the Credential ID Twice
  • Clearing the Challenge with undefined
  • Looking Up a Credential Without Checking Its Owner
  • Letting Sign Up Add Passkeys to Existing Accounts
  • Asking for Verification Without Requiring It
• Where to Go From Here
• Conclusion

The Problems with Password-Based Authentication

Before we write a single line of code, we need to clearly define what we're replacing.

For decades, password-based authentication has been the default login method. And it has proven its effectiveness, which is why it became the standard. But the model it relies on (a secret that a person must memorize, enter, and keep to themselves) has significant limitations. Every aspect of this model is problematic, as we'll now see.

1. Phishing Attacks

A password will work anywhere it's entered. If an attacker builds a page that's identical to your bank's login page, then the password will work just as well on that page. The only thing stopping the user from being compromised is the fact that they might notice that the URL looks a little odd.

That's a lot to ask. Phishing pages are often very close to being pixel-perfect, and they come in the form of urgent emails or text messages designed to get you to act immediately. Even a very careful, technically minded user can be fooled.

One-time passwords sent via SMS or from an authenticator app are of course useful, but people can still be tricked into typing those in on a fake page.

2. Password Reuse

Most people have dozens, if not hundreds of online accounts. You can't possibly remember a unique, strong password for each one, so you'll invariably reuse the same few passwords across the board.

Attackers know this. If one site is breached, they'll take the email and password pairs that have been leaked and try them automatically against other sites. That's credential stuffing. A breach at a little forum you've long since forgotten can result in someone getting into your email or your bank account.

3. Data Breaches

Every site that uses passwords has to store something that can be used to verify the password. The ideal situation is for the site to store salted hashes rather than the passwords themselves. But not all sites do this well, and hashes of weak passwords can still be cracked offline once an attacker has a copy of the database.

This is clearly the developers' burden. You have to choose the right hashing algorithm, tune it, protect the database, and still treat a leak as a disaster for your users.

4. Lack of Privacy

With passwords, users pass a shared secret to every site they sign up with. They have to trust that site to protect it, and they have no control over what happens to it once it's been breached.

As people reuse the same email and password combinations, it's possible for leaked credentials to be matched across breaches. That, in turn, makes it much easier to link accounts across services and build up a profile of a person's online behaviour.

5. Credential Fatigue

Then there's the day-to-day frustration. You're constantly juggling password policies (at least one symbol, no more than 16 characters, and so on), forced resets every few months, security questions, verification codes...the list goes on. Every new account you create just adds to the pile.

This fatigue leads people straight into the behaviour that makes passwords so insecure: short passwords, small variations of the same password, and passwords written on sticky notes. It also costs the business. People drop off during the sign-up process, get locked out, and then contact support to reset passwords they've forgotten.

How Passkeys Solve These Problems

Passkeys remove the shared secret entirely. passkeys.dev describes them as intuitive, automatically unique, breach-resistant, and phishing-resistant.

Here's how that lines up with each problem:

The fundamental shift concerns where trust lives. With passwords, security relies on users’ ability to spot fraudulent sites and choose strong credentials. With passkeys, it's the browser and the operating system that enforce the rules, while the user just confirms their identity.

Prerequisites

To follow along, you should be comfortable with TypeScript and have some React experience. You don't need to know NestJS well, but it helps to know what a controller and a service are.

You'll also need these tools installed:

• Node.js version 22 or later
• PostgreSQL. On macOS, Postgres.app is the easiest option. pgAdmin is handy if you prefer a graphical tool.
• A device that supports passkeys. Almost any modern laptop or phone works: a Mac with Touch ID, a Windows PC with Windows Hello, or an Android phone or iPhone.

What Are Passkeys?

A passkey is a credential based on public key cryptography. When you create one, your device generates a key pair. The private key stays on your device, locked behind your fingerprint, face, or screen lock. The public key goes to the website, which stores it next to your account.

Passkeys are built on the Web Authentication API (WebAuthn), a W3C standard supported by all major browsers. The term "passkey" is the friendly name the industry settled on for WebAuthn credentials that can sync between devices. If you want a deeper introduction, passkeys.dev is an excellent resource.

One detail often surprises developers: your app can't choose between a fingerprint, facial recognition, or a PIN code. It's the operating system that decides, based on the device's capabilities and the settings configured by the user.

Here's what users will typically see:

What your server can do is insist that some local check happened. You'll see how in a moment.

How Passkey Authentication Works

Both sign-up and sign-in follow the same three-step pattern:

1. The server generates a random challenge and sends it to the browser along with some options.
2. The browser asks the device to verify the user and sign the challenge.
3. The browser sends the signed response back, and the server validates it.

During sign-up (WebAuthn refers to this as "registration"), the device creates a new key pair and returns the public key. The server then validates the response and stores the public key.

During sign-in (authentication), the device signs the new challenge with the existing private key. The server then validates the signature using the public key it had previously saved.

Two more concepts come up throughout the code:

The relying party ID (RP ID) is the domain your passkeys belong to, such as example.com. In development, it's localhost. The browser will simply refuse to use a passkey on any other domain, which is what gives passkeys their resistance to phishing.

The user verification (UV) flag is a bit within the signed response. It's only set by the device when the user has actually completed the fingerprint, face, or screen lock check. Your server looks at this flag to ensure that it wasn't just some random user who tapped a key or clicked a button.

Project Structure

The project has two separate apps in one repository:

passwordless-auth/
├── client/   # Next.js frontend, runs on port 3000
└── server/   # NestJS API, runs on port 4000

You'll build the server first, since the frontend depends on its endpoints.

How to Set Up the NestJS Backend

Start by creating a new NestJS project with the Nest CLI:

npx @nestjs/cli new server
cd server

Then install the dependencies for WebAuthn, the database, configuration, and JSON Web Tokens (JWTs):

npm install @simplewebauthn/server @nestjs/typeorm typeorm pg @nestjs/config @nestjs/jwt @nestjs/passport passport passport-jwt

Create the Database

Create an empty database called auth. From the terminal, run:

createdb -h localhost -U postgres auth

If you prefer pgAdmin, right-click Databases, choose Create, then Database, and name it auth.

If you skip this step, NestJS will fail on startup with error: database "auth" does not exist. TypeORM can create tables for you, but it won't create the database itself.

Add Environment Variables

Create a .env file in the server folder:

JWT_SECRET=replace-with-a-long-random-string

WEBAUTHN_RP_ID=localhost
WEBAUTHN_ORIGIN=http://localhost:3000

DB_HOST=localhost
DB_PORT=5432
DB_USERNAME=postgres
DB_PASSWORD=your-database-password
DB_NAME=auth

WEBAUTHN_RP_ID is the domain only, without a protocol or port. WEBAUTHN_ORIGIN is the exact URL of your frontend. The server will reject any response that comes from a different origin.

Browsers only allow WebAuthn on HTTPS sites or on localhost, so this setup works in development without certificates.

Connect to PostgreSQL

Create src/auth/config/database.config.ts to group the database settings:

import { registerAs } from '@nestjs/config';

export default registerAs('database', () => ({
  type: 'postgres',
  host: process.env.DB_HOST,
  port: parseInt(process.env.DB_PORT, 10),
  username: process.env.DB_USERNAME,
  password: process.env.DB_PASSWORD,
  database: process.env.DB_NAME,
  entities: [__dirname + '/../**/*.entity{.ts,.js}'],
  synchronize: process.env.NODE_ENV !== 'production',
}));

While you're in the config folder, add src/auth/config/jwt.config.ts for the token settings:

import { registerAs } from '@nestjs/config';

export default registerAs('jwt', () => ({
  secret: process.env.JWT_SECRET,
  expiresIn: '1h',
}));

The synchronize option tells TypeORM to create and update tables based on your entities. It's convenient in development, but you should switch to migrations before going to production.

Then wire everything up in src/app.module.ts:

import { Module } from '@nestjs/common';
import { ConfigModule, ConfigService } from '@nestjs/config';
import { TypeOrmModule } from '@nestjs/typeorm';
import { AuthModule } from './auth/auth.module';
import databaseConfig from './auth/config/database.config';
import jwtConfig from './auth/config/jwt.config';
import { User, Authenticator } from './auth/entities/auth.entity';

@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true,
      load: [databaseConfig, jwtConfig],
    }),
    TypeOrmModule.forRootAsync({
      imports: [ConfigModule],
      useFactory: (configService: ConfigService) => ({
        type: 'postgres',
        host: configService.get('database.host'),
        port: configService.get('database.port'),
        username: configService.get('database.username'),
        password: configService.get('database.password'),
        database: configService.get('database.database'),
        entities: [User, Authenticator],
        synchronize: configService.get('database.synchronize'),
      }),
      inject: [ConfigService],
    }),
    AuthModule,
  ],
})
export class AppModule {}

Finally, enable CORS in src/main.ts so the frontend on port 3000 can call the API on port 4000:

import { NestFactory } from '@nestjs/core';
import { ValidationPipe } from '@nestjs/common';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  app.useGlobalPipes(new ValidationPipe());
  app.enableCors({
    origin: true,
    credentials: true,
    allowedHeaders: ['Content-Type', 'Authorization'],
  });
  await app.listen(4000);
  console.log('App running on port 4000');
}
bootstrap();

origin: true accepts requests from any origin, which keeps local development simple. Before you deploy, replace it with your frontend's URL.

How to Define the Database Entities

You need two tables here. The User table contains the account, and the Authenticator table contains the passkeys. One user can have multiple passkeys (for example, one on their laptop and one on their phone).

Create src/auth/entities/auth.entity.ts:

import {
  Entity,
  Column,
  PrimaryGeneratedColumn,
  ManyToOne,
  OneToMany,
  CreateDateColumn,
  UpdateDateColumn,
} from 'typeorm';
import type {
  CredentialDeviceType,
  Base64URLString,
} from '@simplewebauthn/server';

@Entity()
export class User {
  @PrimaryGeneratedColumn('uuid')
  id: string;

  @Column({ unique: true })
  email: string;

  @Column({ unique: true })
  webauthnId: Base64URLString;

  @Column({ type: 'varchar', nullable: true })
  currentChallenge?: string | null;

  @OneToMany(() => Authenticator, (authenticator) => authenticator.user)
  authenticators: Authenticator[];

  @CreateDateColumn()
  createdAt: Date;

  @UpdateDateColumn()
  updatedAt: Date;
}

@Entity()
export class Authenticator {
  @PrimaryGeneratedColumn('uuid')
  id: string;

  @Column({ unique: true })
  credentialId: Base64URLString;

  @Column({ type: 'bytea' })
  credentialPublicKey: Uint8Array;

  @ManyToOne(() => User, (user) => user.authenticators, { onDelete: 'CASCADE' })
  user: User;

  @Column()
  webauthnUserId: Base64URLString;

  @Column({ type: 'bigint' })
  counter: number;

  @Column({
    type: 'varchar',
    length: 32,
  })
  deviceType: CredentialDeviceType;

  @Column()
  backedUp: boolean;

  @Column('simple-array', { nullable: true })
  transports?: string[];

  @CreateDateColumn()
  createdAt: Date;

  @UpdateDateColumn()
  updatedAt: Date;
}

Let's take a closer look at a couple of these fields.

First, webauthnId is the user handle that gets stored on the device together with the passkey. The WebAuthn spec says it shouldn't contain personal information, so you'll fill it with random bytes instead of the email.

Next, currentChallenge holds the challenge the server is waiting for. It's set when you generate options and cleared after a successful verification. Notice the string | null type. That matters, and you'll see why in the security section.

counter is a signature counter. Some authenticators will increment it on every use, which allows the server to detect a cloned device. Synced passkeys will typically leave the counter at zero, and SimpleWebAuthn supports both scenarios.

deviceType and backedUp tell you whether the passkey can sync across devices and whether it's currently backed up (for example, to iCloud Keychain).

And finally, transports records how the browser can get to the authenticator (built into the device, over USB, over Bluetooth, or via a phone).

How to Register a Passkey on the Server

Create src/auth/auth.service.ts. Start with the class setup:

import {
  Injectable,
  UnauthorizedException,
  ConflictException,
  Logger,
} from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import { randomBytes } from 'crypto';
import { JwtService } from '@nestjs/jwt';
import { InjectRepository } from '@nestjs/typeorm';
import { Repository } from 'typeorm';
import { User, Authenticator } from './entities/auth.entity';
import {
  generateRegistrationOptions,
  generateAuthenticationOptions,
  verifyRegistrationResponse,
  verifyAuthenticationResponse,
} from '@simplewebauthn/server';
import type {
  AuthenticationResponseJSON,
  PublicKeyCredentialCreationOptionsJSON,
  PublicKeyCredentialRequestOptionsJSON,
  RegistrationResponseJSON,
} from '@simplewebauthn/server';

@Injectable()
export class AuthService {
  private readonly logger = new Logger(AuthService.name);
  private readonly rpName = 'Passwordless Auth';
  private readonly rpID: string;
  private readonly origin: string;

  constructor(
    @InjectRepository(User)
    private readonly userRepository: Repository<User>,
    @InjectRepository(Authenticator)
    private readonly authenticatorRepository: Repository<Authenticator>,
    private readonly jwtService: JwtService,
    private readonly configService: ConfigService,
  ) {
    this.rpID = this.configService.get<string>('WEBAUTHN_RP_ID');
    this.origin = this.configService.get<string>('WEBAUTHN_ORIGIN');
  }

rpName is the human-readable name of your app. Users will see it in the operating system's passkey prompt and later in their password manager.

Generate Registration Options

The first method finds or creates the user, then asks SimpleWebAuthn for registration options. Add it inside the class:

async generateRegistrationOptions(
    email: string,
): Promise<PublicKeyCredentialCreationOptionsJSON> {
  let user = await this.userRepository.findOne({ where: { email } });

  if (!user) {
    user = this.userRepository.create({
      email,
      webauthnId: randomBytes(32).toString('base64url'),
    });
    await this.userRepository.save(user);
  }

  const authenticators = await this.authenticatorRepository.find({
    where: { user: { id: user.id } },
  });

  if (authenticators.length > 0) {
    throw new ConflictException(
      'An account with this email already exists. Please sign in.',
    );
  }

  const options = await generateRegistrationOptions({
    rpName: this.rpName,
    rpID: this.rpID,
    userID: Buffer.from(user.webauthnId, 'base64url'),
    userName: user.email,
    attestationType: 'none',
    authenticatorSelection: {
      residentKey: 'required',
      userVerification: 'required',
    },
    excludeCredentials: authenticators.map((authenticator) => ({
      id: authenticator.credentialId,
      transports: authenticator.transports,
    })),
  });

  // Save the current challenge
  user.currentChallenge = options.challenge;
  await this.userRepository.save(user);

  return options;
}

The authenticatorSelection block is where you decide what kind of passkey you want.

residentKey: 'required' asks for a discoverable credential. That's what makes it a true passkey (the credential is stored on the device or in the user's password manager and can then sync to their other devices).

userVerification: 'required' tells the device that it needs to verify the user (that is, check their fingerprint, face, or screen lock). Without that, some of the authenticators would just do a presence check and not actually verify the user.

What's missing is an authenticator attachment option. If you set it to 'platform', that would effectively lock users into using the sensor on their current device. If you leave it out, then they can use their phone via QR code or a hardware security key (which is what passkeys.dev recommends).

attestationType: 'none' means you're not asking the device to attest to its make and model. Most consumer apps don't need that at all, and asking for it can in fact trigger additional privacy prompts.

excludeCredentials lists the passkeys the user already has so the device won't create a duplicate on an authenticator that's already registered. Given the check immediately above it, that list is always empty in this case. It becomes useful later on when you allow signed-in users to add further passkeys.

The check for existing authenticators is also important. This endpoint doesn't require the user to be signed in, so you can't just allow it to add a passkey to an account that already has one. Otherwise, anyone who knows your email address could attach their own passkey to your account.

Verify the Registration Response

After the user confirms on their device, the browser sends back a response. The second method verifies it and stores the new passkey:

async verifyRegistration(email: string, response: RegistrationResponseJSON) {
  const user = await this.userRepository.findOne({
    where: { email },
    select: ['id', 'email', 'currentChallenge', 'webauthnId'],
  });

  if (!user) {
    throw new UnauthorizedException('User not found');
  }

  const verification = await verifyRegistrationResponse({
    response,
    expectedChallenge: user.currentChallenge,
    expectedOrigin: this.origin,
    expectedRPID: this.rpID,
    requireUserVerification: true,
  });

  const { verified, registrationInfo } = verification;

  if (verified && registrationInfo) {
    const { credential, credentialDeviceType, credentialBackedUp } =
      registrationInfo;

    const newAuthenticator = this.authenticatorRepository.create({
      credentialId: credential.id,
      credentialPublicKey: credential.publicKey,
      counter: credential.counter,
      user: user,
      webauthnUserId: user.webauthnId,
      deviceType: credentialDeviceType,
      backedUp: credentialBackedUp,
      transports: response.response.transports,
    });

    await this.authenticatorRepository.save(newAuthenticator);

    user.currentChallenge = null;
    await this.userRepository.save(user);

    return {
      verified,
      user: { id: user.id, email: user.email },
    };
  }

  throw new UnauthorizedException('Registration verification failed');
}

verifyRegistrationResponse is what does the hard work in this code. It checks that the challenge matches the one you saved, that the response came from your origin and RP ID, and that the signature is valid. With requireUserVerification: true it'll also reject the response if the UV flag isn't set. That flag is your proof that a fingerprint, face, or screen lock check took place.

If all goes well, you'll save the credential ID and the public key and then clear the challenge so it can't be reused.

How to Sign In with a Passkey on the Server

Sign-in works the same way: generate options, then verify the response.

Generate Authentication Options

async generateAuthenticationOptions(
    email: string,
): Promise<PublicKeyCredentialRequestOptionsJSON> {
  const user = await this.userRepository.findOne({ where: { email } });

  if (!user) {
    throw new UnauthorizedException('User not found');
  }

  const authenticators = await this.authenticatorRepository.find({
    where: { user: { id: user.id } },
  });

  if (authenticators.length === 0) {
    throw new UnauthorizedException(
      'No passkey registered for this account. Please sign up.',
    );
  }

  const options = await generateAuthenticationOptions({
    rpID: this.rpID,
    allowCredentials: authenticators.map((authenticator) => ({
      id: authenticator.credentialId,
      transports: authenticator.transports,
    })),
    userVerification: 'required',
  });

  // Save the current challenge
  user.currentChallenge = options.challenge;
  await this.userRepository.save(user);

  return options;
}

allowCredentials lists the passkeys this user owns. The browser uses that list to find the right one on the device, and the transports hint helps it decide whether to look locally, on a security key, or on a phone.

Verify the Authentication Response

async verifyAuthentication(
  email: string,
  response: AuthenticationResponseJSON,
) {
  const user = await this.userRepository.findOne({
    where: { email },
    select: ['id', 'email', 'currentChallenge'],
  });

  if (!user) {
    throw new UnauthorizedException('User not found');
  }

  const authenticator = await this.authenticatorRepository.findOne({
    where: { credentialId: response.id, user: { id: user.id } },
  });

  if (!authenticator) {
    throw new UnauthorizedException('Authenticator not found');
  }

  const verification = await verifyAuthenticationResponse({
    response,
    expectedChallenge: user.currentChallenge,
    expectedOrigin: this.origin,
    expectedRPID: this.rpID,
    credential: {
      id: authenticator.credentialId,
      publicKey: new Uint8Array(authenticator.credentialPublicKey),
      counter: Number(authenticator.counter),
      transports: authenticator.transports,
    },
    requireUserVerification: true,
  });

  const { verified } = verification;

  if (verified) {
    authenticator.counter = verification.authenticationInfo.newCounter;
    authenticator.backedUp =
      verification.authenticationInfo.credentialBackedUp;
    await this.authenticatorRepository.save(authenticator);

    user.currentChallenge = null;
    await this.userRepository.save(user);

    // Generate JWT token
    const payload = { sub: user.id, email: user.email };
    return {
      accessToken: this.jwtService.sign(payload),
      user: { id: user.id, email: user.email },
    };
  }

  throw new UnauthorizedException('Authentication verification failed');
}

The lookup uses both the credential ID and the user ID. Don't drop the user condition. I'll explain why in the security section.

The Number() call around the counter is there because the pg driver returns bigint columns as strings. SimpleWebAuthn expects a number.

Once the signature has been verified, you increment the counter, clear the challenge, and issue a JWT. From that point on, the app treats the user exactly as it would any user who has signed in with a password. The only difference is that a password wasn't used.

How to Expose the Auth Endpoints

Create src/auth/auth.controller.ts. It has one route for each step of the sign-up and sign-in flows, plus a protected route that lists a user's passkeys:

import { Controller, Post, Body, Get, Query, UseGuards } from '@nestjs/common';
import { AuthService } from './auth.service';
import { JwtAuthGuard } from './guards/jwt-auth.guard';

@Controller('auth')
export class AuthController {
  constructor(private readonly authService: AuthService) {}

  @Post('register/options')
  async getRegistrationOptions(
    @Body() body: { email: string },
  ): Promise<PublicKeyCredentialCreationOptionsJSON> {
    return this.authService.generateRegistrationOptions(body.email);
  }

  @Post('register/verify')
  async verifyRegistration(
    @Body() body: { email: string; response: any },
  ) {
    return this.authService.verifyRegistration(body.email, body.response);
  }

  @Post('login/options')
  async getAuthenticationOptions(
    @Body() body: { email: string },
  ): Promise<PublicKeyCredentialRequestOptionsJSON> {
    return this.authService.generateAuthenticationOptions(body.email);
  }

  @Post('login/verify')
  async verifyAuthentication(
    @Body() body: { email: string; response: any },
  ) {
    return this.authService.verifyAuthentication(body.email, body.response);
  }

  @Get('authenticators')
  @UseGuards(JwtAuthGuard)
  async getAuthenticators(@Query('email') email: string) {
    return this.authService.getAuthenticators(email);
  }
}

The response body is typed as any here because the service methods already declare the exact SimpleWebAuthn types they expect.

How to Protect Routes with a JWT

The last route usesJwtAuthGuard, so only signed-in users can call it. It's backed by a small service method. Add it to AuthService:

async getAuthenticators(email: string) {
  const user = await this.userRepository.findOne({ where: { email } });
  if (!user) {
    throw new UnauthorizedException('User not found');
  }
  const authenticators = await this.authenticatorRepository.find({
    where: { user: { id: user.id } },
  });
  return authenticators;
}

Next, create the Passport strategy that reads and validates the token in src/auth/strategies/jwt.strategy.ts:

import { Injectable } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import { PassportStrategy } from '@nestjs/passport';
import { ExtractJwt, Strategy } from 'passport-jwt';

@Injectable()
export class JwtStrategy extends PassportStrategy(Strategy) {
  constructor(private configService: ConfigService) {
    super({
      jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
      ignoreExpiration: false,
      secretOrKey: configService.get('JWT_SECRET'),
    });
  }

  async validate(payload: any) {
    return { userId: payload.sub, email: payload.email };
  }
}

Then create the guard in src/auth/guards/jwt-auth.guard.ts. It wraps Passport's built-in guard and returns clearer error messages:

import {
  ExecutionContext,
  Injectable,
  UnauthorizedException,
} from '@nestjs/common';
import { AuthGuard } from '@nestjs/passport';
import { JsonWebTokenError, TokenExpiredError } from 'jsonwebtoken';

@Injectable()
export class JwtAuthGuard extends AuthGuard('jwt') {
  constructor() {
    super();
  }

  handleRequest(err: any, user: any, info: any) {
    if (info instanceof TokenExpiredError) {
      throw new UnauthorizedException('Token has expired');
    }

    if (info instanceof JsonWebTokenError) {
      throw new UnauthorizedException('Invalid token');
    }

    if (err || !user) {
      throw new UnauthorizedException('Authentication failed');
    }

    return user;
  }

  // Optional: Override canActivate if you need custom logic before JWT validation
  async canActivate(context: ExecutionContext): Promise<boolean> {
    const request = context.switchToHttp().getRequest();

    const authHeader = request.headers.authorization;
    if (!authHeader) {
      throw new UnauthorizedException('No token provided');
    }

    const [type] = authHeader.split(' ');
    if (type !== 'Bearer') {
      throw new UnauthorizedException('Invalid token format');
    }
    return super.canActivate(context) as Promise<boolean>;
  }
}

How to Register the Auth Module

Finally, bring everything together in src/auth/auth.module.ts:

import { Module } from '@nestjs/common';
import { ConfigModule, ConfigService } from '@nestjs/config';
import { JwtModule } from '@nestjs/jwt';
import { TypeOrmModule } from '@nestjs/typeorm';
import { AuthController } from './auth.controller';
import { AuthService } from './auth.service';
import { User, Authenticator } from './entities/auth.entity';
import { JwtStrategy } from './strategies/jwt.strategy';

@Module({
  imports: [
    TypeOrmModule.forFeature([User, Authenticator]),
    JwtModule.registerAsync({
      imports: [ConfigModule],
      useFactory: async (configService: ConfigService) => ({
        secret: configService.get('JWT_SECRET'),
        signOptions: {
          expiresIn: '1d',
        },
      }),
      inject: [ConfigService],
    }),
  ],
  controllers: [AuthController],
  providers: [AuthService, JwtStrategy],
})
export class AuthModule {}

The signOptions here control the tokens the service issues, so each sign-in is valid for one day.

Start the server:

npm run start:dev

TypeORM will create the user and authenticator tables in your auth database. You can open pgAdmin and refresh the Tables node to see them.

How to Set Up the Next.js Frontend

From the root of the project, create a Next.js app with TypeScript, Tailwind CSS, the App Router, and a src folder:

npx create-next-app@latest client --typescript --tailwind --app --src-dir
cd client
npm install @simplewebauthn/browser axios

Add a .env file in the client folder that points to the API:

NEXT_PUBLIC_API_URL=http://localhost:4000

Then create a small API client in client/src/services/api.ts:

/* eslint-disable @typescript-eslint/no-explicit-any */
import axios from 'axios';

const api = axios.create({
  baseURL: process.env.NEXT_PUBLIC_API_URL,
  headers: {
    'Content-Type': 'application/json',
  },
});

export const webAuthnApi = {
  getRegistrationOptions: async (email: string) => {
    const response = await api.post('/auth/register/options', { email });
    return response.data;
  },

  verifyRegistration: async (email: string, response: any) => {
    const res = await api.post('/auth/register/verify', { email, response });
    return res.data;
  },

  getAuthenticationOptions: async (email: string) => {
    const response = await api.post('/auth/login/options', { email });
    return response.data;
  },

  verifyAuthentication: async (email: string, response: any) => {
    const res = await api.post('/auth/login/verify', { email, response });
    return res.data;
  },
};

// Add request interceptor to include JWT token
api.interceptors.request.use((config) => {
  const token = localStorage.getItem('token');
  if (token) {
    config.headers.Authorization = `Bearer ${token}`;
  }
  return config;
});

export default api;

The interceptor at the bottom attaches the JWT to every request once the user has signed in, which is what the protected /auth/authenticators route expects.

How to Build the Sign Up Page

The frontend side of WebAuthn is surprisingly short. SimpleWebAuthn's startRegistration function takes the options from your server, calls the browser's WebAuthn API, and returns a response in a JSON format your server understands.

Create client/src/app/signup/page.tsx:

/* eslint-disable @typescript-eslint/no-explicit-any */
'use client';

import React, { useState } from 'react';
import { startRegistration, browserSupportsWebAuthn } from '@simplewebauthn/browser';
import { webAuthnApi } from '@/services/api';
import { getPasskeyErrorMessage } from '@/services/passkey';
import Link from 'next/link';
import { useRouter } from 'next/navigation';

export default function SignupPage() {
  const [email, setEmail] = useState('');
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState('');
  const router = useRouter();

  const handleRegistration = async (e: React.FormEvent) => {
    e.preventDefault();
    setLoading(true);
    setError('');

    if (!browserSupportsWebAuthn()) {
      setError('This browser does not support passkeys.');
      setLoading(false);
      return;
    }

    try {
      const options = await webAuthnApi.getRegistrationOptions(email);

      const regResult = await startRegistration({ optionsJSON: options });

      const verificationResult = await webAuthnApi.verifyRegistration(email, regResult);

      if (verificationResult.verified) {
        router.push('/welcome');
      }
    } catch (err: any) {
      console.error('Registration error:', err);
      setError(getPasskeyErrorMessage(err, 'Registration failed. Please try again.'));
    } finally {
      setLoading(false);
    }
  };

  return (
    <main className="min-h-screen flex items-center justify-center bg-gray-300">
      <div className="bg-white p-8 rounded-lg shadow-sm w-full max-w-md">
        <div className="space-y-6">
          <div className="text-center">
            <h1 className="text-3xl font-bold tracking-tight">Sign up</h1>
            <p className="text-sm text-gray-600 mt-2">Create your account</p>
          </div>

          <form onSubmit={handleRegistration} className="space-y-4">
            <div className="space-y-2">
              <label htmlFor="email" className="block text-sm font-medium text-gray-700">
                Email
              </label>
              <input
                id="email"
                type="email"
                required
                value={email}
                onChange={(e) => setEmail(e.target.value)}
                className="w-full px-3 py-2 border border-gray-200 rounded-md text-sm placeholder:text-gray-400 focus:outline-none focus:ring-2 focus:ring-blue-500 focus:border-transparent"
                placeholder="Type your email"
              />
            </div>

            {error && (
              <div className="text-sm text-red-600">
                {error}
              </div>
            )}

            <button
              type="submit"
              disabled={loading}
              className="w-full flex justify-center py-2.5 px-4 border border-transparent rounded-md shadow-sm text-sm font-medium text-white bg-[#3B97B6] hover:bg-[#2d7591] focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-blue-500 disabled:opacity-50 transition-colors"
            >
              {loading ? 'Creating passkey...' : 'Create a passkey'}
            </button>
            <p className="text-xs text-center text-gray-500">
              You'll confirm with your fingerprint, face, or screen lock.
            </p>
          </form>

          <div className="text-center text-sm">
            <span className="text-gray-600">Already have an account?</span>{' '}
            <Link
              href="/signin"
              className="text-[#3B97B6] hover:text-[#2d7591] font-medium transition-colors"
            >
              Sign in
            </Link>
          </div>
        </div>
      </div>
    </main>
  );
}

The handleRegistration function follows the three steps from earlier. You fetch options from the server, hand them tostartRegistration, and send the result back for verification.

The call to startRegistration is where the magic happens. The browser opens the operating system's passkey dialog, and the user confirms with Touch ID, Face ID, Windows Hello, or their phone. Your code just waits for the promise to resolve.

Note the { optionsJSON: options } argument. Older versions of SimpleWebAuthn accepted the options directly, and many tutorials still show it that way. Version 13 still supports the old style but logs a warning, so use the object form.

How to Build the Sign In Page

The Sign in page mirrors the Sign up page. Create client/src/app/signin/page.tsx, copy the sign up page into it, and change the headings and the link at the bottom so they point to /signup. Then import startAuthentication instead of startRegistration, and replace the submit handler with this one:

const handleAuthentication = async (e: React.FormEvent) => {
  e.preventDefault();
  setLoading(true);
  setError('');

  if (!browserSupportsWebAuthn()) {
    setError('This browser does not support passkeys.');
    setLoading(false);
    return;
  }

  try {
    const options = await webAuthnApi.getAuthenticationOptions(email);

    const authResult = await startAuthentication({ optionsJSON: options });

    const verificationResult = await webAuthnApi.verifyAuthentication(email, authResult);

    if (verificationResult.accessToken) {
      localStorage.setItem('token', verificationResult.accessToken);
      router.push('/welcome');
    }
  } catch (err: any) {
    console.error('Authentication error:', err);
    setError(getPasskeyErrorMessage(err, 'Authentication failed. Please try again.'));
  } finally {
    setLoading(false);
  }
};

Remember to pass handleAuthentication to the form's onSubmit. You can see the finished page in the GitHub repository.

When verification succeeds, the server returns a JWT, and the page stores it before redirecting. Storing tokens in localStorage keeps this demo simple. In a production app, a httpOnly cookie set by the server is a safer choice because JavaScript running on the page can't read it.

How to Show Helpful Error Messages

When something goes wrong during a passkey ceremony, the browser throws a DOMException with a name that tells you what happened. The raw messages aren't very friendly, so it's a good idea to translate the common ones.

Create client/src/services/passkey.ts:

/* eslint-disable @typescript-eslint/no-explicit-any */

// Turn errors from the browser's WebAuthn API and our backend into readable messages
export function getPasskeyErrorMessage(err: any, fallback: string): string {
  if (err?.response?.data?.message) {
    return err.response.data.message;
  }
  switch (err?.name) {
    case 'NotAllowedError':
      // User cancelled the fingerprint/face/screen-lock prompt, or it timed out
      return 'The passkey prompt was cancelled or timed out. Please try again.';
    case 'InvalidStateError':
      // A passkey for this account already exists on this authenticator
      return 'This device already has a passkey for this account. Please sign in instead.';
    case 'NotSupportedError':
      return 'This device does not support passkeys.';
    case 'SecurityError':
      return 'Passkeys are not allowed on this domain. Check the WebAuthn RP ID and origin settings.';
    default:
      return fallback;
  }
}

NotAllowedError is the one you'll see most. It fires when the user closes the prompt, waits too long, or fails the biometric check. SecurityError usually means your RP ID doesn't match the domain the page is running on, which is a configuration problem rather than a user problem.

How to Test Your App

Start both apps in separate terminals:

# Terminal 1
cd server
npm run start:dev

# Terminal 2
cd client
npm run dev

Go to http://localhost:3000/signup, enter your email, and click the button. Your device will show the prompt about the passkey. On a Mac with Touch ID, you'll be asked to touch the sensor. Otherwise, you'll need to fill the form with your MacBook user password. On Windows, Windows Hello will ask for your face, fingerprint, or PIN. If you choose to use another device, the browser shows a QR code that you can scan with your phone.

After you confirm, you land on the welcome page. Now go to /signin, enter the same email, and confirm again. This time the server returns a JWT.

If you don't have a passkey-enabled device available, Chrome has a built-in virtual authenticator. Open DevTools, click the three-dot menu, then go to More tools and choose WebAuthn. Enable the virtual authenticator environment and add an authenticator with "Supports user verification" checked. Chrome will then simulate a passkey device for you.

You can also open pgAdmin and look at the authenticator table. You'll see the credential ID, the public key stored as bytes, and the device type. There's no password and nothing secret in there.

Security Mistakes to Avoid

Passkeys are secure by design, but the server code around them still has to be right. I ran into each of the issues below while building this project. Some of them don't throw any errors, which is what makes them dangerous.

Encoding the Credential ID Twice

In recent versions of SimpleWebAuthn, including version 14 used here, credential.id is already a base64url string. My first version of the code did this:

// Wrong: encodes an already-encoded string
credentialId: Buffer.from(credential.id).toString('base64url'),

Buffer.from treats the string as UTF-8 text, so the result is a base64url encoding of a base64url string. Registration succeeds, but sign-in can never find the credential because the browser sends the original ID. Store credential.id as it is.

Clearing the Challenge with undefined

Every challenge should be used only once. This line looks like it clears it:

user.currentChallenge = undefined;

But TypeORM skips undefined properties when it saves an entity, so the old challenge stays in the database. Someone who captured a valid response could replay it. Set the value to null instead, and make sure the column type allows it.

Looking Up a Credential Without Checking Its Owner

It's tempting to find the authenticator by credential ID alone:

// Wrong: any user's passkey matches
where: { credentialId: response.id }

But here's the problem: the attacker asks for sign-in options for your email, signs your challenge with their own passkey, and the server sees their passkey, validates the signature against their public key, and then issues a token for your account. Always include the user in the lookup as per the earlier example.

Letting Sign Up Add Passkeys to Existing Accounts

The registration endpoint is public. If it's going to add a passkey to an account that matches the email, then anyone who knows your email can register their own passkey and sign in as you.

Don't allow registration if the account already has a passkey. If you want people to be able to add more passkeys, then that can be a separate feature which requires them to be signed in.

Asking for Verification Without Requiring It

If you request userVerification: 'preferred', the device is allowed to skip the fingerprint or PIN check. If you then verify with requireUserVerification: true, which is SimpleWebAuthn's default, users with those devices will get confusing failures. Pick 'required' on both sides so the options and the verification agree.

Where to Go From Here

The app you've built covers the fundamental passkey flows. But there are a couple of enhancements you could make if you wanted to go further.

Passkey autofill (also known as conditional UI) will cause the browser to suggest the saved passkey directly in the email field, just as it will suggest a saved password. SimpleWebAuthn supports this via the useBrowserAutofill option of startAuthentication.

Users will also want to add passkeys for their other devices and remove old ones. You'd build that as a pair of endpoints behind your JWT guard.

Finally, challenges should expire. A simple way to do this is to store a timestamp alongside currentChallenge and then reject anything older than a few minutes. In a larger app, you'd probably store the challenges in a session or a cache (for example, Redis) rather than on the user record.

Conclusion

In this tutorial, you've built a complete passwordless authentication system using passkeys. You've got a full NestJS API that can generate WebAuthn challenges, verify the signed responses using SimpleWebAuthn, and store the public keys in PostgreSQL. You've also got a Next.js frontend that allows users to sign up and sign in using their fingerprint, their face, or their device's screen lock.

You've now learned how the challenge and signature flow works, why the user verification flag is important, and why the server can't decide which biometric method the user will see. You've also seen a number of rather subtle bugs that can result in a sign-in failure or even an account takeover, and how to avoid them.

Passwords aren't going away any time soon, but passkeys are already supported on pretty much every device that your users have. You now know how to add them to your own apps.

The full source code is available on GitHub. Go ahead and clone it, break it, and make it your own. If you found this tutorial useful in any way, then please do pass it on to someone who’s about to have the same question.

WebAuthn changes the shape of the system. The private key stays on the user's device. Your server stores a public key, a credential ID, and a counter. Each registration or login signs a fresh challenge. The browser, the authenticator, and your backend all take part in the ceremony.

This guide walks you through the full path in Node.js. You'll set up the backend, wire registration and login, store passkeys correctly, replace long-lived bearer auth with short server sessions, support backup devices, and add step-up verification for risky actions.

Warning: WebAuthn works in secure contexts. Use localhost for local development, and use HTTPS everywhere else.

Table of Contents

• Why JWT Alone Falls Short

• What WebAuthn Changes

• Initialize the Project

• Install Dependencies

• Define the Data Model

• Build the Server Foundation

• Registration Ceremony

• Authentication Ceremony

• What Replaces the Long-Lived JWT

• Multi-Device and Recovery Logic

• Step-Up Authentication for Sensitive Actions

• Recap

• Try it Yourself

• Final Words

Prerequisites

To follow along and get the most out of this guide, you should have:

• Basic knowledge of JavaScript and Node.js.

• Basic knowledge of TypeScript and Express.

• Basic frontend to backend flow. You should be able to follow fetch() requests from the browser to the server and back.

• A modern browser and a passkey-capable authenticator, such as Touch ID, Face ID, Windows Hello, Android biometrics, or a security key.

• Local testing on localhost. The demo uses localhost as the relying party ID and origin during development.

• No prior WebAuthn knowledge required. The article explains the registration and authentication flow step by step.

Why JWT Alone Falls Short

JWTs are not the villain.

The weak point is the usual deployment pattern around JWTs. Teams often place long-lived tokens in places attackers love, then trust those tokens for too long.

The failure path usually looks like this:

• Your server issues a reusable bearer token.

• The browser stores it.

• Malware, XSS, session theft, or a fake login flow grabs it.

• The attacker replays it.

• Your backend sees a valid token and treats the request as real.

That pattern falls apart fast on high-risk routes. Admin actions, money movement, payout approval, email change, API key creation, or destructive writes deserve stronger proof.

WebAuthn gives you stronger proof because the secret never leaves the authenticator.

In the above diagram, the left side (reusable JWT path) shows the risk of reusable tokens. A server issues a JWT after login. The browser stores the token. An attacker steals the token and sends requests. The backend accepts the token until expiration. Replay becomes possible.

On the right side (WebAuthn path), the flow changes. The server sends a fresh challenge for each login. Your device signs the challenge using a private key stored inside the authenticator. The server verifies the signature before creating a short session.

The key point is simple: JWTs rely on a stored bearer secret, while WebAuthn relies on device-bound cryptographic proof created for a single challenge.

What WebAuthn Changes

WebAuthn uses asymmetric cryptography.

The authenticator creates a key pair. The private key stays on the device. Your backend stores the public key and uses it later to verify signatures. During login, your server sends a fresh challenge. The device signs it, and your backend verifies the result against the stored public key.

That changes three things at once:

• The browser never receives a reusable password secret.

• A stolen public key is useless for login.

• Each ceremony depends on a fresh server challenge.

On the web, passkeys ride on top of WebAuthn. A passkey might live on the local device, a synced platform account, or a physical security key. In practice, your app still deals with the same core objects: credential ID, public key, transports, counter, device type, and backup state.

Initialize the Project

So far, we've talked about why WebAuthn matters and how it changes the login experience. Now it's time to build a small project so you can see the whole flow working end to end.

In this demo, you'll create a simple Node.js app where a user can register a passkey, sign in with that passkey, and then access protected routes through a short-lived session. The idea here is not to build a polished full-stack product. The idea is to build the core backend flow clearly, so you can understand how registration, login, sessions, and step-up verification connect to each other.

Before we start, make sure Node.js and npm are installed on your machine. You can install Node.js from the official website, or use nvm if you prefer managing multiple Node versions.

node -v
npm -v

The expected output is a Node LTS version and an npm version number.

Next, create a new project folder and initialize the basic structure:

mkdir webauthn-node-demo
cd webauthn-node-demo
npm init -y
npx tsc --init
mkdir src

Install Dependencies

Now that your project is initialized, install the required packages.

1. TypeScript and tsx: TypeScript types the backend while tsx runs TypeScript files during development.

npm install -D typescript tsx @types/node
npx tsc -v
npx tsx --version

1. Express and session management: Express handles the HTTP routes, and express-session stores short-lived server session state.

npm install express express-session @types/express @types/express-session

1. SimpleWebAuthn:@simplewebauthn/server generates registration options and verifies responses. @simplewebauthn/browser starts browser-side flows.

npm install @simplewebauthn/server @simplewebauthn/browser

Open your package.json and update the "scripts" block to include these commands:

{
    "scripts": {
        "dev": "tsx watch src/app.ts",
        "build": "tsc",
        "start": "node dist/app.js"
    }
}

Define the Data Model

Before we write the routes, we need to decide how this app will store passkeys.

With password-based login, you usually store a password hash. With WebAuthn, you store something different. After a user registers a passkey, your server needs to keep the credential data required to verify future login attempts. That includes things like the credential ID, public key, counter, and some metadata about the authenticator.

This is why the data model matters from the beginning. Registration and authentication both depend on this stored data, so it's worth making the structure clear before we move deeper into the flow.

A good way to think about it is this. A user can have one or more passkeys, and each passkey should be stored as its own record linked to that user.

Create a new file named src/app.ts. We'll build the backend in this file, and we'll start by defining the data model at the top.

// src/app.ts
type Passkey = {
    id: string;
    publicKey: Uint8Array;
    counter: number;
    deviceType: "singleDevice" | "multiDevice";
    backedUp: boolean;
    transports?: string[];
};

type User = {
    id: string;
    email: string;
    webAuthnUserID: Uint8Array;
    passkeys: Passkey[];
};

const users = new Map<string, User>();

function findUserByEmail(email: string) {
    return [...users.values()].find((user) => user.email === email);
}

What matters here:

• id identifies the credential later.

• publicKey verifies future signatures.

• counter helps detect cloned or misbehaving authenticators.

• deviceType and backedUp give you useful recovery signals.

• webAuthnUserID should be a stable binary value, stored once per user.

Tip: If your database returns Buffer or another binary wrapper for publicKey, convert it back to Uint8Array before verification.

Build the Server Foundation

Next, append the core Express app and relying party settings to src/app.ts:

// src/app.ts
import express from "express";
import session from "express-session";
import { randomBytes, randomUUID } from "node:crypto";
import {
    generateAuthenticationOptions,
    generateRegistrationOptions,
    verifyAuthenticationResponse,
    verifyRegistrationResponse,
    type WebAuthnCredential,
} from "@simplewebauthn/server";

const rpName = "Node Auth Lab";
const rpID = "localhost";
const origin = "http://localhost:3000";

declare module "express-session" {
    interface SessionData {
        currentChallenge?: string;
        pendingUserId?: string;
        userId?: string;
        stepUpUntil?: number;
    }
}

const app = express();

app.use(express.json());

app.use(
    session({
        secret: "replace-this-in-production",
        resave: false,
        saveUninitialized: false,
        cookie: {
            httpOnly: true,
            sameSite: "lax",
            secure: false,
            maxAge: 10 * 60 * 1000,
        },
    }),
);

This gives you the shared state you need for:

• registration challenge tracking

• authentication challenge tracking

• logged-in session state

• short step-up windows for risky actions

Registration Ceremony

Registration is the part where a user's device creates a new passkey and connects it to their account.

You will often see the word ceremony in WebAuthn documentation. In simple terms, it refers to the full exchange between your server, the browser, and the authenticator during registration or login. So when we say registration ceremony, we simply mean the full process of creating and verifying a new passkey.

There are three parts involved here:

• Your backend prepares the registration options and challenge.

• The browser starts the WebAuthn request.

• Then the authenticator, such as a phone, laptop, or security key, creates the key pair and returns the result.

In the above diagram, the registration ceremony links a new passkey to your account. The browser asks the server for registration options. The server generates a challenge and returns a JSON configuration. Next, the browser starts the WebAuthn ceremony. Your authenticator creates a new key pair after biometric or security key verification. The private key stays inside the device. Then the browser sends the attestation response to the server.

Verification happens next. The server checks challenge, origin, and relying party ID. After validation, the server stores credential ID, public key, counter value, device type, and backup state. The account now holds a passkey.

Now that the overall flow is clear, let's build it step by step. We'll start by returning registration options from the backend.

1. Return Registration Options from the Backend

This endpoint creates a new user if needed, generates the registration options, and stores the challenge server-side.

Append the following route to your src/app.ts file:

// src/app.ts
app.post("/auth/register/options", async (req, res) => {
    const { email } = req.body;

    if (!email) {
        return res.status(400).json({ error: "Email is required" });
    }

    let user = findUserByEmail(email);

    if (!user) {
        user = {
            id: randomUUID(),
            email,
            webAuthnUserID: randomBytes(32),
            passkeys: [],
        };

        users.set(user.id, user);
    }

    const options = await generateRegistrationOptions({
        rpName,
        rpID,
        userName: user.email,
        userDisplayName: user.email,
        userID: user.webAuthnUserID,
        attestationType: "none",
        excludeCredentials: user.passkeys.map((passkey) => ({
            id: passkey.id,
            transports: passkey.transports,
        })),
        authenticatorSelection: {
            residentKey: "preferred",
            userVerification: "preferred",
        },
    });

    req.session.currentChallenge = options.challenge;
    req.session.pendingUserId = user.id;

    res.json(options);
});

A few decisions here matter:

• attestationType: 'none' keeps the flow lighter unless you need richer device provenance.

• excludeCredentials stops duplicate registration of the same authenticator.

• userVerification: 'preferred' lets the browser lean toward biometrics or local device unlock.

2. Start Registration in the Browser

On the browser side, you ask your backend for options, then pass them into startRegistration().

Now, create a new file at src/browser.ts to handle the client-side WebAuthn interactions. Add the following function:

// src/browser.ts
import { startRegistration } from "@simplewebauthn/browser";

export async function registerPasskey(email: string) {
    const optionsResp = await fetch("/auth/register/options", {
        method: "POST",
        headers: {
            "Content-Type": "application/json",
        },
        body: JSON.stringify({ email }),
    });

    const optionsJSON = await optionsResp.json();

    const registrationResponse = await startRegistration({ optionsJSON });

    const verifyResp = await fetch("/auth/register/verify", {
        method: "POST",
        headers: {
            "Content-Type": "application/json",
        },
        body: JSON.stringify(registrationResponse),
    });

    return verifyResp.json();
}

Note: Browsers can't run TypeScript or bare npm imports directly. In a real application, you would import src/browser.ts into your frontend framework (React, Vue, and so on) or bundle it using a tool like Vite, Webpack, or esbuild before serving it to the client.

Under the hood, the browser now speaks to the authenticator. That might trigger Face ID, Touch ID, Windows Hello, Android biometrics, or a physical security key prompt.

3. Verify the Registration Response and Save the Passkey

Once the browser sends the response back, verify it against the challenge and relying party details you stored earlier.

Append this verification route to src/app.ts:

// src/app.ts
app.post("/auth/register/verify", async (req, res) => {
    const user = users.get(req.session.pendingUserId ?? "");

    if (!user || !req.session.currentChallenge) {
        return res.status(400).json({ verified: false });
    }

    let verification;

    try {
        verification = await verifyRegistrationResponse({
            response: req.body,
            expectedChallenge: req.session.currentChallenge,
            expectedOrigin: origin,
            expectedRPID: rpID,
        });
    } catch (error) {
        return res.status(400).json({
            verified: false,
            error:
                error instanceof Error ? error.message : "Registration failed",
        });
    }

    if (!verification.verified || !verification.registrationInfo) {
        return res.status(400).json({ verified: false });
    }

    const { credential, credentialDeviceType, credentialBackedUp } =
        verification.registrationInfo;

    user.passkeys.push({
        id: credential.id,
        publicKey: credential.publicKey,
        counter: credential.counter,
        transports: credential.transports,
        deviceType: credentialDeviceType,
        backedUp: credentialBackedUp,
    });

    req.session.currentChallenge = undefined;
    req.session.pendingUserId = undefined;

    res.json({ verified: true });
});

At this point, the user has no password hash in the hot path. The authenticator now holds the private key. Your server stores only what it needs for later verification.

Authentication Ceremony

Authentication is the part where the user proves they still have the passkey they registered earlier. Just like registration, this process is also called a ceremony in WebAuthn. Here, the goal is not to create a new credential. The goal is to verify an existing one in a secure way.

There are four parts involved here:

• Your server creates a fresh challenge.

• The browser passes that challenge to the authenticator.

• The authenticator signs it using the private key stored on the device.

• Then the server verifies the response using the public key it stored during registration.

In the above diagram, login occurs through a challenge-response process. The browser first asks the server for authentication options. The server generates a new challenge and returns the allowed credential list. Your browser then triggers the authenticator. The authenticator signs the challenge using the private key stored on the device. The browser sends the signed assertion to the backend.

Verification follows. The server validates signature, challenge, origin, and credential ID. The stored counter updates. A short session is issued after verification. Login depends on device proof instead of reusable credentials.

With that flow in mind, let's move into the implementation. We'll begin by returning authentication options from the backend.

1. Return Authentication Options

Fetch the user, list allowed credentials, and store the new challenge.

// src/app.ts
app.post("/auth/login/options", async (req, res) => {
    const { email } = req.body;
    const user = findUserByEmail(email);

    if (!user) {
        return res.status(404).json({ error: "User not found" });
    }

    const options = await generateAuthenticationOptions({
        rpID,
        allowCredentials: user.passkeys.map((passkey) => ({
            id: passkey.id,
            transports: passkey.transports,
        })),
        userVerification: "preferred",
    });

    req.session.currentChallenge = options.challenge;
    req.session.pendingUserId = user.id;

    res.json(options);
});

2. Start Authentication in the Browser

The browser receives the options, then starts the ceremony. Add the login function to your src/browser.ts file:

// src/browser.ts
import { startAuthentication } from "@simplewebauthn/browser";

export async function loginWithPasskey(email: string) {
    const optionsResp = await fetch("/auth/login/options", {
        method: "POST",
        headers: {
            "Content-Type": "application/json",
        },
        body: JSON.stringify({ email }),
    });

    const optionsJSON = await optionsResp.json();

    const authenticationResponse = await startAuthentication({ optionsJSON });

    const verifyResp = await fetch("/auth/login/verify", {
        method: "POST",
        headers: {
            "Content-Type": "application/json",
        },
        body: JSON.stringify(authenticationResponse),
    });

    return verifyResp.json();
}

3. Verify the Assertion and Update the Counter

This is the moment where the backend decides whether the login is real.

// src/app.ts
app.post("/auth/login/verify", async (req, res) => {
    const user = users.get(req.session.pendingUserId ?? "");

    if (!user || !req.session.currentChallenge) {
        return res.status(400).json({ verified: false });
    }

    const passkey = user.passkeys.find((item) => item.id === req.body.id);

    if (!passkey) {
        return res
            .status(400)
            .json({ verified: false, error: "Passkey not found" });
    }

    const credential: WebAuthnCredential = {
        id: passkey.id,
        publicKey: passkey.publicKey,
        counter: passkey.counter,
        transports: passkey.transports,
    };

    let verification;

    try {
        verification = await verifyAuthenticationResponse({
            response: req.body,
            expectedChallenge: req.session.currentChallenge,
            expectedOrigin: origin,
            expectedRPID: rpID,
            credential,
            requireUserVerification: true,
        });
    } catch (error) {
        return res.status(400).json({
            verified: false,
            error:
                error instanceof Error
                    ? error.message
                    : "Authentication failed",
        });
    }

    if (!verification.verified) {
        return res.status(400).json({ verified: false });
    }

    passkey.counter = verification.authenticationInfo.newCounter;

    req.session.userId = user.id;
    req.session.currentChallenge = undefined;
    req.session.pendingUserId = undefined;

    res.json({ verified: true });
});

Two details here matter more than they first appear:

• requireUserVerification: true forces a stronger ceremony for the verification step.

• newCounter should overwrite your stored counter after each successful login.

That counter update is one of the few signals you have for spotting cloned or broken authenticators.

What Replaces the Long-lived JWT

Don't run this full WebAuthn flow, then issue a week-long bearer token and call the job done. That throws away the best part of the design.

A better model is:

• WebAuthn proves identity

• the server creates a short session

• the browser receives only an HTTP-only session cookie

• risky actions ask for a fresh WebAuthn assertion again

A tiny route guard shows the idea:

// src/app.ts
function requireSession(
    req: express.Request,
    res: express.Response,
    next: express.NextFunction,
) {
    if (!req.session.userId) {
        return res.status(401).json({ error: "Unauthorized" });
    }

    next();
}

app.get("/me", requireSession, (req, res) => {
    const user = users.get(req.session.userId ?? "");

    if (!user) {
        return res.status(404).json({ error: "User not found" });
    }

    res.json({
        id: user.id,
        email: user.email,
        passkeys: user.passkeys.length,
    });
});

This keeps the post-login browser state smaller and less reusable. The browser carries only a session cookie. The server owns the session state and its lifetime.

Tip: Short sessions plus fresh WebAuthn for risky actions is a stronger shape than one long bearer token with broad scope.

Multi-Device and Recovery Logic

Strong auth fails fast if the first lost phone locks the user out forever. You need a real backup story from day one.

The clean pattern looks like this:

• register one platform passkey on the user's main device

• register one extra credential, such as a security key or another trusted device

• verify a contact channel during account setup

• expose passkey management in account settings

• store device metadata so users see what is registered

In the above diagram, the left side shows the recovery strategy. You start with a primary passkey on your main device. Then you add another trusted authenticator such as a second device or hardware security key. A recovery channel should exist. Device inventory helps track active credentials, and lost devices must be revoked quickly.

The right side focuses on step up authentication. Sensitive actions require fresh verification. Examples include payouts, email change, API key generation, or destructive operations. When such an action begins, the server issues a new challenge. Your authenticator signs again. Access lasts for a short step up window before new verification becomes required.

A simple product rule helps here. Don't hide the second passkey flow inside a deep settings page. Put "Add another passkey" right after the first successful registration.

Passkeys also sync across major platform ecosystems. That helps the user experience, but your backend should still treat each registered credential as a first-class record with its own ID, public key, counter, device type, and backup state.

For account recovery, keep the bar high. Recovery should not become the weakest path in the whole system. Emailed magic links, recovery codes, and support-driven recovery all need rate limits, audit trails, and strict checks.

Step-up Authentication for Sensitive Actions

Logging in once should not grant silent permission for every dangerous route.

Step-up auth means this:

• the user is already signed in

• they try a sensitive action

• the server demands a fresh WebAuthn ceremony

• the app grants a short window for that one class of actions

You can use step-up auth for:

• payout approval

• credential management

• email or phone change

• API key creation

• organization deletion

• role elevation

• access to billing controls

Start by issuing new authentication options with strict user verification.

// src/app.ts
app.post("/auth/step-up/options", requireSession, async (req, res) => {
    const user = users.get(req.session.userId ?? "");

    if (!user) {
        return res.status(404).json({ error: "User not found" });
    }

    const options = await generateAuthenticationOptions({
        rpID,
        allowCredentials: user.passkeys.map((passkey) => ({
            id: passkey.id,
            transports: passkey.transports,
        })),
        userVerification: "required",
    });

    req.session.currentChallenge = options.challenge;

    res.json(options);
});

Then verify the response and issue a short step-up window.

// src/app.ts
app.post("/auth/step-up/verify", requireSession, async (req, res) => {
    const user = users.get(req.session.userId ?? "");
    const passkey = user?.passkeys.find((item) => item.id === req.body.id);

    if (!user || !passkey || !req.session.currentChallenge) {
        return res.status(400).json({ verified: false });
    }

    let verification;
    try {
        verification = await verifyAuthenticationResponse({
            response: req.body,
            expectedChallenge: req.session.currentChallenge,
            expectedOrigin: origin,
            expectedRPID: rpID,
            credential: {
                id: passkey.id,
                publicKey: passkey.publicKey,
                counter: passkey.counter,
                transports: passkey.transports,
            },
            requireUserVerification: true,
        });
    } catch (error) {
        return res.status(400).json({
            verified: false,
            error: error instanceof Error ? error.message : "Step-up failed",
        });
    }

    if (!verification.verified) {
        return res.status(400).json({ verified: false });
    }

    passkey.counter = verification.authenticationInfo.newCounter;
    req.session.stepUpUntil = Date.now() + 5 * 60 * 1000;
    req.session.currentChallenge = undefined;

    res.json({ verified: true });
});

A tiny guard handles the rest.

// src/app.ts
function requireRecentStepUp(
    req: express.Request,
    res: express.Response,
    next: express.NextFunction,
) {
    if (!req.session.stepUpUntil || req.session.stepUpUntil < Date.now()) {
        return res.status(403).json({ error: "Fresh verification required" });
    }

    next();
}

app.post("/billing/payout", requireSession, requireRecentStepUp, (req, res) => {
    res.json({ ok: true });
});

This is where WebAuthn stops being a login feature and starts becoming part of your authorization model.

Now that all your routes and guards are built, append the server start command to the very bottom of src/app.ts to bring the backend to life:

// src/app.ts
const PORT = 3000;
app.listen(PORT, () => {
    console.log(`Server listening on http://localhost:${PORT}`);
});

Recap

You started with a common weak pattern: a reusable token trusted for too long. Then you replaced the core proof model:

• the device keeps the private key

• the server stores the public key and counter

• each ceremony signs a fresh challenge

• the app uses short server sessions after verification

• risky routes trigger fresh step-up authentication

That's the real shift.

WebAuthn is not a cosmetic login upgrade. It changes where trust lives. Once you move from reusable bearer proof to device-bound cryptographic proof, your Node.js auth stack starts to behave like a modern security system instead of a thin session wrapper.

Try it Yourself

The full source code is available on GitHub. Clone the repository here and follow the setup guide in the README to test the biometric login flow locally.

Final Words

If you found the information here valuable, feel free to share it with others who might benefit from it.

I’d really appreciate your thoughts – mention me on X @sumit_analyzen or on Facebook @sumit.analyzen, watch my coding tutorials, or simply connect with me on LinkedIn.

You can also checkout my official website www.sumitsaha.me for more details about me.