Next.js and WebAuthn: A Beginner’s Guide to Passwordless Authentication

Written by

learnmodernjavascript

in

In today’s digital landscape, securing user accounts is paramount. Traditional password-based authentication systems are vulnerable to various attacks, including phishing, credential stuffing, and brute-force attempts. This is where WebAuthn (Web Authentication) comes in. WebAuthn is a web standard that allows users to authenticate to web applications using cryptographic keys instead of passwords. This approach offers a significantly more secure and user-friendly experience, eliminating the need to remember complex passwords and reducing the risk of account compromise. This tutorial will guide you through implementing WebAuthn in a Next.js application, providing a practical and comprehensive understanding of this powerful authentication method.

Understanding WebAuthn

WebAuthn is a specification created by the World Wide Web Consortium (W3C) and the FIDO Alliance. It enables users to authenticate to web applications using a variety of authenticators, such as:

  • Security Keys: Physical USB or NFC devices that store cryptographic keys.
  • Platform Authenticators: Built-in authenticators on devices like laptops and smartphones (e.g., fingerprint sensors, facial recognition).
  • Roaming Authenticators: Authenticators that can be used across multiple devices (e.g., security keys).

WebAuthn relies on public-key cryptography. Each user has a private key, securely stored on the authenticator, and a public key, which is registered with the web application. When a user authenticates, the authenticator uses the private key to sign a challenge from the web application. The web application then verifies the signature using the user’s public key, confirming the user’s identity.

The benefits of WebAuthn are numerous:

  • Enhanced Security: Eliminates the risks associated with passwords, such as phishing and credential stuffing.
  • Improved User Experience: Simplifies the login process, making it faster and more convenient.
  • Phishing Resistance: WebAuthn authenticators are designed to be resistant to phishing attacks.
  • Strong Authentication: Provides strong, multi-factor authentication by default.

Setting Up Your Next.js Project

Before diving into the code, you’ll need a Next.js project. If you don’t have one already, create a new project using the following command:

npx create-next-app webauthn-nextjs-tutorial
cd webauthn-nextjs-tutorial

Next, install the necessary dependencies. We’ll be using the following packages:

  • @simplewebauthn/server: For server-side WebAuthn operations.
  • @simplewebauthn/browser: For client-side WebAuthn operations.
  • @noble/hashes: For cryptographic hashing.
npm install @simplewebauthn/server @simplewebauthn/browser @noble/hashes

Server-Side Implementation

The server-side implementation handles the registration and authentication processes. We’ll create API routes in Next.js to manage these operations.

1. Registration

Create a file named pages/api/register/start.js. This API route will initiate the registration process.

// pages/api/register/start.js
import { generateRegistrationOptions, verifyRegistrationResponse } from '@simplewebauthn/server';

export default async function handler(req, res) {
  if (req.method !== 'POST') {
    return res.status(405).json({ message: 'Method Not Allowed' });
  }

  const { username } = req.body;

  // 1. Generate registration options
  const options = await generateRegistrationOptions({
    rpName: 'My Next.js App',
    rpID: req.headers.host,
    userID: username, // Consider using a unique ID from your database
    userName: username,
    attestationType: 'none',
    authenticatorSelection: {
      authenticatorAttachment: 'platform',
      requireResidentKey: false,
      userVerification: 'required',
    },
  });

  // Store the challenge and user data for later verification
  // In a real application, you would store this in a database or session
  req.session.challenge = options.challenge;
  req.session.username = username;

  // Set the challenge as a cookie (for demo purposes)
  res.setHeader('Set-Cookie', [
    `challenge=${options.challenge}; Path=/; HttpOnly; Secure; SameSite=Strict`,
    `username=${username}; Path=/; HttpOnly; Secure; SameSite=Strict`,
  ]);

  res.status(200).json(options);
}

In this code:

  • We generate registration options using generateRegistrationOptions from @simplewebauthn/server.
  • We specify the relying party (RP) details (rpName and rpID).
  • We include the user’s username (you should use a unique ID in a production environment).
  • We store the challenge and user data in the session (for demo purposes – store in database in production).
  • We return the registration options to the client.

Create a file named pages/api/register/finish.js. This API route will finalize the registration process.

// pages/api/register/finish.js
import { verifyRegistrationResponse } from '@simplewebauthn/server';

export default async function handler(req, res) {
  if (req.method !== 'POST') {
    return res.status(405).json({ message: 'Method Not Allowed' });
  }

  const { username, credential } = req.body;

  // Retrieve the challenge and user data from storage
  const challenge = req.session.challenge;

  // Verify the registration response
  try {
    const { verified, registrationInfo } = await verifyRegistrationResponse(
      credential,
      { challenge, origin: `https://${req.headers.host}` }
    );

    if (verified) {
      // Registration successful! Store the credential ID and public key
      // In a real application, save registrationInfo to your database
      console.log('Registration successful:', registrationInfo);
      res.status(200).json({ message: 'Registration successful' });
    } else {
      console.error('Registration failed');
      res.status(400).json({ message: 'Registration failed' });
    }
  } catch (error) {
    console.error('Registration error:', error);
    res.status(500).json({ message: 'Internal Server Error' });
  }
}

In this code:

  • We retrieve the challenge from the session.
  • We verify the registration response using verifyRegistrationResponse.
  • If the verification is successful, we store the credential ID and public key in a database (in a real application).

2. Authentication

Create a file named pages/api/login/start.js. This API route will initiate the authentication process.

// pages/api/login/start.js
import { generateAuthenticationOptions } from '@simplewebauthn/server';

export default async function handler(req, res) {
  if (req.method !== 'POST') {
    return res.status(405).json({ message: 'Method Not Allowed' });
  }

  const { username } = req.body;

  // 1. Retrieve user's stored credentials from your database
  // (Replace this with your actual database query)
  const storedCredentials = {
    credentialId: 'YOUR_CREDENTIAL_ID',
    publicKey: 'YOUR_PUBLIC_KEY',
    counter: 0,
  };

  if (!storedCredentials) {
    return res.status(400).json({ message: 'User not found or no credentials' });
  }

  // 2. Generate authentication options
  const options = await generateAuthenticationOptions({
    rpID: req.headers.host,
    challenge: 'YOUR_CHALLENGE', // Generate a new challenge for each login attempt
    allowCredentials: [
      {
        id: storedCredentials.credentialId,
        type: 'public-key',
      },
    ],
    userVerification: 'required',
  });

  // Store the challenge for later verification
  // In a real application, you would store this in a database or session
  req.session.challenge = options.challenge;

  // Set the challenge as a cookie (for demo purposes)
  res.setHeader('Set-Cookie', [
    `challenge=${options.challenge}; Path=/; HttpOnly; Secure; SameSite=Strict`,
  ]);

  res.status(200).json(options);
}

In this code:

  • We retrieve the user’s stored credentials from your database (replace the placeholder with your database query).
  • We generate authentication options using generateAuthenticationOptions.
  • We specify the relying party (RP) details (rpID).
  • We include the allowed credentials (the user’s credential ID).
  • We store the challenge in the session (for demo purposes).
  • We return the authentication options to the client.

Create a file named pages/api/login/finish.js. This API route will finalize the authentication process.

// pages/api/login/finish.js
import { verifyAuthenticationResponse } from '@simplewebauthn/server';

export default async function handler(req, res) {
  if (req.method !== 'POST') {
    return res.status(405).json({ message: 'Method Not Allowed' });
  }

  const { credential } = req.body;

  // Retrieve the challenge from storage
  const challenge = req.session.challenge;

  // 1. Retrieve user's stored credentials from your database
  // (Replace this with your actual database query)
  const storedCredentials = {
    credentialId: 'YOUR_CREDENTIAL_ID',
    publicKey: 'YOUR_PUBLIC_KEY',
    counter: 0,
  };

  // Verify the authentication response
  try {
    const { verified, authenticationInfo } = await verifyAuthenticationResponse(
      credential,
      storedCredentials,
      {
        challenge,
        origin: `https://${req.headers.host}`,
      }
    );

    if (verified) {
      // Authentication successful! Update the counter in your database
      // In a real application, update the counter and login the user
      console.log('Authentication successful:', authenticationInfo);
      res.status(200).json({ message: 'Authentication successful' });
    } else {
      console.error('Authentication failed');
      res.status(400).json({ message: 'Authentication failed' });
    }
  } catch (error) {
    console.error('Authentication error:', error);
    res.status(500).json({ message: 'Internal Server Error' });
  }
}

In this code:

  • We retrieve the challenge from the session.
  • We retrieve the user’s stored credentials from your database (replace the placeholder with your database query).
  • We verify the authentication response using verifyAuthenticationResponse.
  • If the verification is successful, we update the counter in the database and log the user in (in a real application).

Client-Side Implementation

The client-side implementation handles the interaction with the WebAuthn API. We’ll create a simple React component to manage the registration and authentication flows.

Create a file named components/WebAuthn.js:

// components/WebAuthn.js
import { useEffect, useState } from 'react';
import { startRegistration, startAuthentication } from '@simplewebauthn/browser';

export default function WebAuthn() {
  const [username, setUsername] = useState('');
  const [registrationMessage, setRegistrationMessage] = useState('');
  const [authenticationMessage, setAuthenticationMessage] = useState('');

  const handleRegister = async () => {
    try {
      setRegistrationMessage('Registering...');
      // 1. Get registration options from the server
      const response = await fetch('/api/register/start', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ username }),
      });

      if (!response.ok) {
        throw new Error('Failed to start registration');
      }

      const registrationOptions = await response.json();

      // 2. Perform the registration
      const registration = await startRegistration(registrationOptions);

      // 3. Send the registration response to the server
      const finishResponse = await fetch('/api/register/finish', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ username, credential: registration }),
      });

      if (!finishResponse.ok) {
        throw new Error('Registration failed');
      }

      setRegistrationMessage('Registration successful!');
    } catch (error) {
      console.error('Registration error:', error);
      setRegistrationMessage(`Registration failed: ${error.message}`);
    }
  };

  const handleLogin = async () => {
    try {
      setAuthenticationMessage('Logging in...');

      // 1. Get authentication options from the server
      const response = await fetch('/api/login/start', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ username }),
      });

      if (!response.ok) {
        throw new Error('Failed to start authentication');
      }

      const authenticationOptions = await response.json();

      // 2. Perform the authentication
      const authentication = await startAuthentication(authenticationOptions);

      // 3. Send the authentication response to the server
      const finishResponse = await fetch('/api/login/finish', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ credential: authentication }),
      });

      if (!finishResponse.ok) {
        throw new Error('Authentication failed');
      }

      setAuthenticationMessage('Login successful!');
    } catch (error) {
      console.error('Authentication error:', error);
      setAuthenticationMessage(`Login failed: ${error.message}`);
    }
  };

  return (
    <div>
      <h2>WebAuthn Authentication</h2>
      <div>
        <label>Username:</label>
         setUsername(e.target.value)}
        />
      </div>
      <div>
        <button>Register</button>
        <p>{registrationMessage}</p>
      </div>
      <div>
        <button>Login</button>
        <p>{authenticationMessage}</p>
      </div>
    </div>
  );
}

In this code:

  • We import startRegistration and startAuthentication from @simplewebauthn/browser.
  • We create state variables for the username, registration message, and authentication message.
  • The handleRegister function initiates the registration flow:
  • It fetches registration options from the /api/register/start endpoint.
  • It calls startRegistration to prompt the user to register their authenticator.
  • It sends the registration response to the /api/register/finish endpoint.
  • The handleLogin function initiates the authentication flow:
  • It fetches authentication options from the /api/login/start endpoint.
  • It calls startAuthentication to prompt the user to authenticate with their authenticator.
  • It sends the authentication response to the /api/login/finish endpoint.

To use this component, import it into your page (e.g., pages/index.js):

// pages/index.js
import WebAuthn from '../components/WebAuthn';

export default function Home() {
  return (
    <div>
      <h1>Welcome to WebAuthn Demo</h1>
      
    </div>
  );
}

Running the Application

To run the application, execute the following command in your project directory:

npm run dev

Open your browser and navigate to http://localhost:3000. You should see the WebAuthn component with the username input and registration/login buttons.

Here’s how to test the application:

  1. Enter a username in the input field.
  2. Click the “Register” button. Your browser will prompt you to register a security key or use a platform authenticator (e.g., fingerprint, facial recognition).
  3. Follow the prompts to complete the registration.
  4. Click the “Login” button. Your browser will prompt you to authenticate with your registered authenticator.
  5. Follow the prompts to complete the login.

Common Mistakes and Troubleshooting

Here are some common mistakes and how to fix them:

  • Incorrect Origin: Ensure the origin parameter in the verifyRegistrationResponse and verifyAuthenticationResponse functions matches the URL of your application (e.g., https://localhost:3000).
  • Challenge Mismatch: The challenge used during registration and authentication must match. Make sure you store the challenge correctly and pass it to the server.
  • HTTPS Required: WebAuthn requires HTTPS. During development, you can use a tool like mkcert to generate a self-signed certificate. For production, you must use a valid SSL/TLS certificate.
  • Browser Compatibility: Ensure your browser supports WebAuthn. Most modern browsers (Chrome, Firefox, Safari, Edge) have excellent support.
  • Authenticator Issues: If you’re having trouble with a specific authenticator, try a different one or check the authenticator’s documentation.
  • CORS Errors: Make sure your API routes are configured to handle Cross-Origin Resource Sharing (CORS) correctly. You might need to install and configure a CORS middleware in your Next.js application.

Key Takeaways

  • WebAuthn provides a more secure and user-friendly alternative to traditional password-based authentication.
  • It relies on public-key cryptography and authenticators like security keys and platform authenticators.
  • The implementation involves server-side and client-side components.
  • Server-side handles registration and authentication logic, including generating and verifying challenges.
  • Client-side interacts with the WebAuthn API to manage the registration and authentication flows.
  • Properly handling the origin and challenges is crucial for successful implementation.

FAQ

Q: What are the advantages of using WebAuthn over passwords?

A: WebAuthn eliminates the need to remember passwords, making it more resistant to phishing and credential stuffing attacks. It also provides a better user experience by allowing users to authenticate with their existing devices (e.g., fingerprint, facial recognition) or security keys.

Q: What types of authenticators can be used with WebAuthn?

A: WebAuthn supports a variety of authenticators, including security keys (e.g., YubiKey), platform authenticators (e.g., fingerprint sensors, facial recognition on laptops and smartphones), and roaming authenticators.

Q: Is WebAuthn secure?

A: Yes, WebAuthn is a very secure authentication method. It uses public-key cryptography and relies on authenticators that store private keys securely. It is resistant to many common attacks, such as phishing and credential stuffing.

Q: Does WebAuthn require HTTPS?

A: Yes, WebAuthn requires HTTPS for security reasons. This ensures that the communication between the web application and the authenticator is secure.

Q: How can I store the credential ID and public key in a production environment?

A: In a production environment, you should store the credential ID and public key in a secure database, associated with the user’s account. This allows the server to retrieve the user’s credentials during the authentication process.

WebAuthn represents a significant advancement in web security, offering a more robust and user-friendly authentication experience. By following the steps outlined in this tutorial, you can integrate WebAuthn into your Next.js applications and provide your users with a more secure and convenient way to access their accounts. As the digital landscape continues to evolve, embracing technologies like WebAuthn will be crucial for protecting user data and maintaining trust. Remember to always prioritize security best practices and keep your application’s dependencies up-to-date to stay ahead of potential vulnerabilities. The move towards passwordless authentication is not just a trend; it’s a fundamental shift in how we secure our online identities, and understanding WebAuthn is a crucial step in that direction.

More posts