MagicAuth Blog
FIDO2/WebAuthn Developer Implementation Guide

FIDO2/WebAuthn Developer Implementation Guide: Complete Tutorial with Code Examples

Implementing FIDO2/WebAuthn passkey authentication in 2025 is easier than ever. This comprehensive developer guide walks you through production-ready implementation with complete code examples for JavaScript, Node.js, and Python, following W3C WebAuthn Level 3 specifications and current best practices.

Auth Team
Auth Team
December 2025 · 12 min read

Understanding FIDO2 and WebAuthn

Try MagicAuth

Experience the technology discussed in this article.

Learn More →

FIDO2 represents the latest authentication specifications from the FIDO Alliance, designed to eliminate password dependency through phishing-resistant, public-key cryptography. The framework comprises two core components: the WebAuthn API (a W3C web standard) and the Client to Authenticator Protocol (CTAP), which enables external authenticators to communicate with browsers and platforms.

WebAuthn specifically defines the JavaScript API that web applications use to create and verify credentials. When properly implemented, it provides authentication that is simultaneously more secure than passwords (resistant to phishing, credential stuffing, and password database breaches) and more user-friendly (biometric login, no memorization required).

The security model relies on asymmetric cryptography: during registration, the authenticator generates a unique public-private key pair for each website. The public key is stored on the server, while the private key never leaves the user's device. During authentication, the server issues a challenge that only the holder of the private key can correctly sign—proving possession without transmitting secrets over the network.

Prerequisites for Implementation

Before implementing FIDO2/WebAuthn, ensure your development environment meets these requirements:

  • HTTPS: WebAuthn only functions over secure connections. Development on localhost works without SSL, but production requires valid certificates.
  • Browser Support: Chrome 119+, Safari 17+, Firefox 120+, Edge 119+ all support WebAuthn Level 3. Over 95% of global users have compatible browsers.
  • Server-Side Library: Use established libraries rather than implementing cryptographic verification manually. For Node.js, @simplewebauthn/server v9.0+ is recommended. For Python, py_webauthn v2.0+ provides robust implementation.
  • Database Storage: You'll need to store user public keys, credential IDs, and authenticator metadata persistently.

The implementation examples in this guide use modern JavaScript for the client side and Node.js with the SimpleWebAuthn library for the server. The patterns translate directly to other backend languages with appropriate FIDO2 libraries, similar to how platforms like MagicAuth implement authentication across different technology stacks.

Registration Flow: Creating Passkeys

Passkey registration follows a challenge-response pattern initiated by the server. Here's the complete client-side implementation: 

// Client-side registration (browser JavaScript)
async function registerPasskey(username) {
  try {
    // 1. Request registration options from server
    const optionsResponse = await fetch('/auth/register/options', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ username })
    });

    const options = await optionsResponse.json();

    // 2. Convert base64url strings to ArrayBuffers
    options.challenge = base64urlToBuffer(options.challenge);
    options.user.id = base64urlToBuffer(options.user.id);

    // 3. Call WebAuthn API to create credential
    const credential = await navigator.credentials.create({
      publicKey: options
    });

    // 4. Prepare response for server verification
    const attestationResponse = {
      id: credential.id,
      rawId: bufferToBase64url(credential.rawId),
      type: credential.type,
      response: {
        clientDataJSON: bufferToBase64url(
          credential.response.clientDataJSON
        ),
        attestationObject: bufferToBase64url(
          credential.response.attestationObject
        ),
        transports: credential.response.getTransports()
      }
    };

    // 5. Send to server for verification
    const verifyResponse = await fetch('/auth/register/verify', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(attestationResponse)
    });

    if (verifyResponse.ok) {
      console.log('Passkey registered successfully!');
      return true;
    }
  } catch (error) {
    console.error('Registration failed:', error);
    return false;
  }
}

// Utility functions for encoding conversion
function base64urlToBuffer(base64url) {
  const base64 = base64url.replace(/-/g, '+').replace(/_/g, '/');
  const binary = atob(base64);
  const bytes = new Uint8Array(binary.length);
  for (let i = 0; i < binary.length; i++) {
    bytes[i] = binary.charCodeAt(i);
  }
  return bytes.buffer;
}

function bufferToBase64url(buffer) {
  const bytes = new Uint8Array(buffer);
  let binary = '';
  for (let i = 0; i < bytes.byteLength; i++) {
    binary += String.fromCharCode(bytes[i]);
  }
  return btoa(binary)
    .replace(/\+/g, '-')
    .replace(/\//g, '_')
    .replace(/=/g, '');
}

The server-side implementation generates registration options and verifies the attestation response: 

// Server-side registration (Node.js with SimpleWebAuthn)
import {
  generateRegistrationOptions,
  verifyRegistrationResponse
} from '@simplewebauthn/server';

// Configuration
const RP_NAME = 'Your App Name';
const RP_ID = 'yourdomain.com'; // Must match domain exactly
const ORIGIN = 'https://yourdomain.com';

// Generate registration options
app.post('/auth/register/options', async (req, res) => {
  const { username } = req.body;

  // Check if user exists, create if needed
  let user = await db.findUserByUsername(username);
  if (!user) {
    user = await db.createUser({
      id: crypto.randomBytes(32), // 32-byte random user ID
      username: username
    });
  }

  // Generate challenge and options
  const options = await generateRegistrationOptions({
    rpName: RP_NAME,
    rpID: RP_ID,
    userID: user.id,
    userName: username,
    timeout: 60000, // 60 seconds
    attestationType: 'none', // 'none', 'indirect', or 'direct'
    authenticatorSelection: {
      authenticatorAttachment: 'platform', // 'platform' or 'cross-platform'
      residentKey: 'required', // 'required' for passkeys
      userVerification: 'required' // Require biometric/PIN
    },
    supportedAlgorithmIDs: [-7, -257] // ES256, RS256
  });

  // Store challenge for verification
  await db.saveChallenge(user.id, options.challenge);

  res.json(options);
});

// Verify registration response
app.post('/auth/register/verify', async (req, res) => {
  const body = req.body;

  // Retrieve user and challenge
  const user = await db.findUserByCredentialId(body.id);
  const expectedChallenge = await db.getChallenge(user.id);

  try {
    const verification = await verifyRegistrationResponse({
      response: body,
      expectedChallenge,
      expectedOrigin: ORIGIN,
      expectedRPID: RP_ID,
      requireUserVerification: true
    });

    if (verification.verified) {
      // Store credential for future authentication
      await db.saveCredential({
        userId: user.id,
        credentialId: verification.registrationInfo.credentialID,
        publicKey: verification.registrationInfo.credentialPublicKey,
        counter: verification.registrationInfo.counter,
        transports: body.response.transports
      });

      res.json({ verified: true });
    } else {
      res.status(400).json({ error: 'Verification failed' });
    }
  } catch (error) {
    console.error('Registration verification error:', error);
    res.status(500).json({ error: error.message });
  }
});

Authentication Flow: Verifying Passkeys

Authentication follows a similar challenge-response pattern, but instead of creating credentials, it proves possession of an existing private key: 

// Client-side authentication (browser JavaScript)
async function authenticatePasskey(username) {
  try {
    // 1. Request authentication options from server
    const optionsResponse = await fetch('/auth/login/options', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ username })
    });

    const options = await optionsResponse.json();

    // 2. Convert base64url challenge to ArrayBuffer
    options.challenge = base64urlToBuffer(options.challenge);

    // Convert allowCredentials if present
    if (options.allowCredentials) {
      options.allowCredentials = options.allowCredentials.map(cred => ({
        ...cred,
        id: base64urlToBuffer(cred.id)
      }));
    }

    // 3. Call WebAuthn API to get assertion
    const assertion = await navigator.credentials.get({
      publicKey: options
    });

    // 4. Prepare response for server verification
    const authResponse = {
      id: assertion.id,
      rawId: bufferToBase64url(assertion.rawId),
      type: assertion.type,
      response: {
        clientDataJSON: bufferToBase64url(
          assertion.response.clientDataJSON
        ),
        authenticatorData: bufferToBase64url(
          assertion.response.authenticatorData
        ),
        signature: bufferToBase64url(assertion.response.signature),
        userHandle: assertion.response.userHandle
          ? bufferToBase64url(assertion.response.userHandle)
          : null
      }
    };

    // 5. Send to server for verification
    const verifyResponse = await fetch('/auth/login/verify', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(authResponse)
    });

    if (verifyResponse.ok) {
      const { sessionToken } = await verifyResponse.json();
      localStorage.setItem('authToken', sessionToken);
      return true;
    }
  } catch (error) {
    console.error('Authentication failed:', error);
    return false;
  }
}

Server-side authentication verification: 

// Server-side authentication (Node.js with SimpleWebAuthn)
import {
  generateAuthenticationOptions,
  verifyAuthenticationResponse
} from '@simplewebauthn/server';

// Generate authentication options
app.post('/auth/login/options', async (req, res) => {
  const { username } = req.body;

  // Find user and their credentials
  const user = await db.findUserByUsername(username);
  if (!user) {
    return res.status(404).json({ error: 'User not found' });
  }

  const userCredentials = await db.getCredentialsByUserId(user.id);

  const options = await generateAuthenticationOptions({
    rpID: RP_ID,
    timeout: 60000,
    allowCredentials: userCredentials.map(cred => ({
      id: cred.credentialId,
      type: 'public-key',
      transports: cred.transports
    })),
    userVerification: 'required'
  });

  // Store challenge for verification
  await db.saveChallenge(user.id, options.challenge);

  res.json(options);
});

// Verify authentication response
app.post('/auth/login/verify', async (req, res) => {
  const body = req.body;

  // Find credential and user
  const credential = await db.findCredentialById(body.id);
  if (!credential) {
    return res.status(404).json({ error: 'Credential not found' });
  }

  const user = await db.findUserById(credential.userId);
  const expectedChallenge = await db.getChallenge(user.id);

  try {
    const verification = await verifyAuthenticationResponse({
      response: body,
      expectedChallenge,
      expectedOrigin: ORIGIN,
      expectedRPID: RP_ID,
      authenticator: {
        credentialID: credential.credentialId,
        credentialPublicKey: credential.publicKey,
        counter: credential.counter
      },
      requireUserVerification: true
    });

    if (verification.verified) {
      // Update counter to prevent replay attacks
      await db.updateCredentialCounter(
        credential.id,
        verification.authenticationInfo.newCounter
      );

      // Create session
      const sessionToken = await createSessionToken(user.id);

      res.json({
        verified: true,
        sessionToken
      });
    } else {
      res.status(400).json({ error: 'Verification failed' });
    }
  } catch (error) {
    console.error('Authentication verification error:', error);
    res.status(500).json({ error: error.message });
  }
});

Database Schema for Credentials

Proper credential storage is critical for WebAuthn implementation. Here's a recommended schema: 

-- Users table
CREATE TABLE users (
  id BYTEA PRIMARY KEY,              -- 32-byte random ID
  username VARCHAR(255) UNIQUE NOT NULL,
  created_at TIMESTAMP DEFAULT NOW()
);

-- Credentials table
CREATE TABLE credentials (
  id SERIAL PRIMARY KEY,
  user_id BYTEA REFERENCES users(id) ON DELETE CASCADE,
  credential_id BYTEA UNIQUE NOT NULL,  -- From authenticator
  public_key BYTEA NOT NULL,            -- COSE-encoded public key
  counter BIGINT NOT NULL DEFAULT 0,    -- Signature counter
  transports TEXT[],                    -- ['internal', 'usb', etc.]
  backup_eligible BOOLEAN DEFAULT false,
  backup_state BOOLEAN DEFAULT false,
  device_type VARCHAR(50),              -- 'platform' or 'cross-platform'
  created_at TIMESTAMP DEFAULT NOW(),
  last_used_at TIMESTAMP
);

CREATE INDEX idx_credentials_user ON credentials(user_id);
CREATE INDEX idx_credentials_credential_id ON credentials(credential_id);

-- Challenges table (temporary storage)
CREATE TABLE challenges (
  user_id BYTEA REFERENCES users(id) ON DELETE CASCADE,
  challenge TEXT NOT NULL,
  created_at TIMESTAMP DEFAULT NOW(),
  expires_at TIMESTAMP DEFAULT NOW() + INTERVAL '2 minutes'
);

CREATE INDEX idx_challenges_user ON challenges(user_id);
CREATE INDEX idx_challenges_expires ON challenges(expires_at);

Security Best Practices

Production WebAuthn implementations must adhere to specific security requirements to prevent attacks and ensure phishing resistance:

1. Origin and RP ID Validation

Always verify that the origin and Relying Party ID match your expected values exactly. The browser automatically enforces that credentials are origin-bound, but server-side validation provides defense in depth: 

// Strict origin validation
const ALLOWED_ORIGINS = ['https://yourdomain.com'];
const RP_ID = 'yourdomain.com';

function validateOrigin(clientDataJSON) {
  const clientData = JSON.parse(
    Buffer.from(clientDataJSON, 'base64url')
  );

  if (!ALLOWED_ORIGINS.includes(clientData.origin)) {
    throw new Error('Origin mismatch');
  }

  return clientData;
}

2. Challenge Uniqueness and Expiration

Generate cryptographically random challenges (minimum 16 bytes, recommend 32 bytes) and enforce strict expiration (maximum 2 minutes). Never reuse challenges: 

async function generateChallenge(userId) {
  // Generate 32-byte random challenge
  const challenge = crypto.randomBytes(32).toString('base64url');

  // Store with 2-minute expiration
  await db.saveChallenge({
    userId,
    challenge,
    expiresAt: new Date(Date.now() + 120000) // 2 minutes
  });

  return challenge;
}

async function verifyChallenge(userId, providedChallenge) {
  const stored = await db.getChallenge(userId);

  if (!stored) {
    throw new Error('Challenge not found');
  }

  if (Date.now() > stored.expiresAt) {
    await db.deleteChallenge(userId);
    throw new Error('Challenge expired');
  }

  if (stored.challenge !== providedChallenge) {
    throw new Error('Challenge mismatch');
  }

  // Challenges are single-use
  await db.deleteChallenge(userId);
  return true;
}

3. Counter Verification

Authenticators increment a signature counter with each use to prevent cloned credentials. Always verify the counter increases: 

async function verifyCounter(credentialId, newCounter) {
  const credential = await db.getCredential(credentialId);

  // Counter must increase (or be zero for new batch of signatures)
  if (newCounter > 0 && newCounter <= credential.counter) {
    // Possible cloned authenticator detected
    await db.flagCredentialAsSuspicious(credentialId);
    throw new Error('Counter did not increase');
  }

  // Update stored counter
  await db.updateCredentialCounter(credentialId, newCounter);
  return true;
}

4. User Verification Requirement

For maximum security, require user verification (biometric or PIN) rather than just user presence (touching the authenticator): 

// Registration options requiring user verification
const registrationOptions = {
  // ... other options
  authenticatorSelection: {
    userVerification: 'required', // Not 'preferred' or 'discouraged'
    residentKey: 'required'       // For passwordless flow
  }
};

// Verify the UV flag was set
function verifyUserVerification(authenticatorData) {
  const flags = authenticatorData[32]; // Flags byte
  const userVerified = (flags & 0x04) !== 0; // UV flag

  if (!userVerified) {
    throw new Error('User verification not performed');
  }
}

Cross-Platform Compatibility

Modern passkey implementations support credential syncing across devices through platform providers (Apple iCloud Keychain, Google Password Manager, etc.). Configure your implementation to support both platform and cross-platform authenticators: 

// Support both platform and roaming authenticators
const registrationOptions = {
  // ... other options
  authenticatorSelection: {
    // Don't specify authenticatorAttachment to allow both types
    residentKey: 'required',
    userVerification: 'required'
  },
  // Support common algorithms
  supportedAlgorithmIDs: [
    -7,   // ES256 (ECDSA with SHA-256)
    -257, // RS256 (RSA with SHA-256)
    -8,   // EdDSA
    -37,  // PS256 (RSA-PSS with SHA-256)
  ]
};

Error Handling and User Experience

Robust error handling ensures users understand authentication failures and can take corrective action: 

async function registerWithErrorHandling(username) {
  try {
    await registerPasskey(username);
    showSuccess('Passkey created successfully!');
  } catch (error) {
    if (error.name === 'NotAllowedError') {
      showError('Registration cancelled or timed out. Please try again.');
    } else if (error.name === 'InvalidStateError') {
      showError('This device already has a passkey for this account.');
    } else if (error.name === 'NotSupportedError') {
      showError('Passkeys are not supported on this browser.');
    } else if (error.name === 'SecurityError') {
      showError('Security error. Ensure you are using HTTPS.');
    } else {
      console.error('Registration error:', error);
      showError('Registration failed. Please try again.');
    }
  }
}

Testing Your Implementation

Thorough testing across platforms ensures compatibility. Test on:

  • Desktop browsers: Chrome, Safari, Firefox, Edge on Windows, macOS, Linux
  • Mobile devices: iOS Safari, Android Chrome
  • Authenticator types: Built-in (Touch ID, Face ID, Windows Hello), USB security keys (YubiKey), Bluetooth/NFC authenticators
  • Error scenarios: Network failures, expired challenges, cancelled flows, concurrent registrations

Use the official WebAuthn demo at webauthn.io to verify your browser compatibility, and consider automated testing tools like Selenium with WebDriver BiDi for continuous integration testing.

Production Deployment Checklist

Before deploying WebAuthn to production, verify these requirements:

  • HTTPS configured: Valid SSL certificate for all environments
  • RP ID matches domain: No subdomain mismatches
  • Database indexes: On credential_id, user_id, and challenge lookups
  • Challenge cleanup: Automated job to delete expired challenges
  • Monitoring: Track registration/authentication success rates, error types, browser/platform distribution
  • Fallback authentication: Alternative method for users without compatible devices (though 95%+ support exists)
  • Documentation: User-facing help articles explaining passkey setup and usage

Integration with Existing Systems

WebAuthn integrates cleanly with existing authentication infrastructure. You can implement progressive enhancement—offering passkeys alongside traditional passwords initially, then transitioning to passkey-first or passkey-only once adoption reaches critical mass.

Many platforms like MagicAuth demonstrate how passwordless authentication can coexist with legacy systems during transition periods, while services like rCAPTCHA provide additional security layers for risk-based authentication flows.

For applications requiring additional engagement mechanisms, consider integrating reward systems (similar to Rewarders) to incentivize passkey adoption, or collaborative tools (like Journaleus) that benefit from frictionless authentication.

Resources and Next Steps

This guide provides production-ready WebAuthn implementation patterns for 2025. For deeper technical details, consult these resources:

  • W3C WebAuthn Specification: The official Level 3 specification (October 2024)
  • FIDO Alliance Documentation: Comprehensive implementation guides and certification programs
  • SimpleWebAuthn Library: Well-maintained Node.js implementation with extensive documentation
  • py_webauthn: Production-ready Python library for backend verification
  • WebAuthn.io: Official demo and testing platform

With these tools and patterns, implementing FIDO2/WebAuthn passkey authentication becomes straightforward—delivering enhanced security and improved user experience that drives the passwordless future of authentication.

MagicAuth Blog
MagicAuth Blog

Insights on passwordless authentication, WebAuthn, and modern security

More from this blog →

Explore Our Network

rCAPTCHA - Bot Detection MagicAuth - Passwordless Rewarders - Earn Rewards Free Scrum Poker

Part of the Journaleus Network

Responses

No responses yet. Be the first to share your thoughts!