Passkeys y Autenticacion sin Contrasenas: Guia Completa 2026

1# Instalar dependencias
2npm install @simplewebauthn/server @simplewebauthn/browser
3npm install -D @simplewebauthn/types

1// app/api/auth/register/options/route.ts
2import {
3  generateRegistrationOptions,
4  type GenerateRegistrationOptionsOpts,
5} from '@simplewebauthn/server';
6
7const RP_NAME = 'Mi App Segura';
8const RP_ID = 'miapp.com';
9
10export async function POST(request: Request) {
11  const { userId, userEmail } = await request.json();
12
13  // Obtener passkeys existentes del usuario (para excluirlas)
14  const existingCredentials = await db.credential.findMany({
15    where: { userId },
16    select: { credentialId: true, transports: true },
17  });
18
19  const opts: GenerateRegistrationOptionsOpts = {
20    rpName: RP_NAME,
21    rpID: RP_ID,
22    userName: userEmail,
23    userDisplayName: userEmail,
24    // No pedir de nuevo passkeys ya registradas
25    excludeCredentials: existingCredentials.map((c) => ({
26      id: c.credentialId,
27      transports: c.transports,
28    })),
29    authenticatorSelection: {
30      residentKey: 'preferred',
31      userVerification: 'preferred',
32    },
33    attestationType: 'none', // No necesitamos attestation en la mayoria de casos
34  };
35
36  const options = await generateRegistrationOptions(opts);
37
38  // Guardar el challenge en sesion para verificar despues
39  await saveChallenge(userId, options.challenge);
40
41  return Response.json(options);
42}

1// app/api/auth/register/verify/route.ts
2import {
3  verifyRegistrationResponse,
4  type VerifiedRegistrationResponse,
5} from '@simplewebauthn/server';
6
7export async function POST(request: Request) {
8  const body = await request.json();
9  const { userId } = body;
10
11  // Recuperar el challenge guardado
12  const expectedChallenge = await getChallenge(userId);
13  if (!expectedChallenge) {
14    return Response.json({ error: 'Challenge expirado' }, { status: 400 });
15  }
16
17  let verification: VerifiedRegistrationResponse;
18  try {
19    verification = await verifyRegistrationResponse({
20      response: body.credential,
21      expectedChallenge,
22      expectedOrigin: 'https://miapp.com',
23      expectedRPID: 'miapp.com',
24    });
25  } catch (error) {
26    console.error('Error de verificacion:', error);
27    return Response.json({ error: 'Verificacion fallida' }, { status: 400 });
28  }
29
30  const { verified, registrationInfo } = verification;
31
32  if (verified && registrationInfo) {
33    // Guardar la credencial en base de datos
34    await db.credential.create({
35      data: {
36        credentialId: registrationInfo.credential.id,
37        publicKey: Buffer.from(registrationInfo.credential.publicKey),
38        counter: registrationInfo.credential.counter,
39        transports: body.credential.response.transports ?? [],
40        userId,
41      },
42    });
43
44    return Response.json({ verified: true });
45  }
46
47  return Response.json({ error: 'No verificado' }, { status: 400 });
48}

1// lib/passkey-client.ts
2import {
3  startRegistration,
4  startAuthentication,
5} from '@simplewebauthn/browser';
6
7export async function registerPasskey(userId: string, email: string) {
8  // 1. Obtener opciones del servidor
9  const optionsRes = await fetch('/api/auth/register/options', {
10    method: 'POST',
11    headers: { 'Content-Type': 'application/json' },
12    body: JSON.stringify({ userId, userEmail: email }),
13  });
14  const options = await optionsRes.json();
15
16  // 2. Crear la credencial con el authenticator del dispositivo
17  const credential = await startRegistration({ optionsJSON: options });
18
19  // 3. Enviar la credencial al servidor para verificacion
20  const verifyRes = await fetch('/api/auth/register/verify', {
21    method: 'POST',
22    headers: { 'Content-Type': 'application/json' },
23    body: JSON.stringify({ userId, credential }),
24  });
25
26  return verifyRes.json();
27}
28
29export async function loginWithPasskey() {
30  // 1. Obtener opciones de autenticacion
31  const optionsRes = await fetch('/api/auth/login/options', {
32    method: 'POST',
33  });
34  const options = await optionsRes.json();
35
36  // 2. El navegador solicita la verificacion biometrica/PIN
37  const assertion = await startAuthentication({ optionsJSON: options });
38
39  // 3. Verificar en el servidor
40  const verifyRes = await fetch('/api/auth/login/verify', {
41    method: 'POST',
42    headers: { 'Content-Type': 'application/json' },
43    body: JSON.stringify(assertion),
44  });
45
46  return verifyRes.json();
47}
48
49// Verificar si el navegador soporta WebAuthn
50export function isWebAuthnSupported(): boolean {
51  return (
52    typeof window !== 'undefined' &&
53    typeof window.PublicKeyCredential !== 'undefined'
54  );
55}
56
57// Verificar si soporta Conditional UI (autofill)
58export async function supportsConditionalUI(): Promise<boolean> {
59  if (!isWebAuthnSupported()) return false;
60  return PublicKeyCredential.isConditionalMediationAvailable?.() ?? false;
61}

1// components/LoginForm.tsx
2'use client';
3
4import { useEffect, useState } from 'react';
5import { startAuthentication } from '@simplewebauthn/browser';
6
7export function LoginForm() {
8  const [email, setEmail] = useState('');
9  const [isConditionalAvailable, setConditionalAvailable] = useState(false);
10
11  useEffect(() => {
12    // Iniciar autenticacion condicional al cargar la pagina
13    async function initConditionalUI() {
14      const available =
15        await PublicKeyCredential.isConditionalMediationAvailable?.();
16      if (!available) return;
17      setConditionalAvailable(true);
18
19      try {
20        const optionsRes = await fetch('/api/auth/login/options', {
21          method: 'POST',
22        });
23        const options = await optionsRes.json();
24
25        // useBrowserAutofill: true activa Conditional UI
26        const assertion = await startAuthentication({
27          optionsJSON: options,
28          useBrowserAutofill: true,
29        });
30
31        const verifyRes = await fetch('/api/auth/login/verify', {
32          method: 'POST',
33          headers: { 'Content-Type': 'application/json' },
34          body: JSON.stringify(assertion),
35        });
36
37        if (verifyRes.ok) {
38          window.location.href = '/dashboard';
39        }
40      } catch (e) {
41        // El usuario cancelo o no selecciono una passkey
42        console.log('Conditional UI cancelada:', e);
43      }
44    }
45
46    initConditionalUI();
47  }, []);
48
49  return (
50    <form>
51      <input
52        type="email"
53        value={email}
54        onChange={(e) => setEmail(e.target.value)}
55        autoComplete="username webauthn"
56        placeholder="[email protected]"
57      />
58      {/* Fallback para login tradicional */}
59      <input type="password" autoComplete="current-password" />
60      <button type="submit">Iniciar sesion</button>
61    </form>
62  );
63}

1// Manejo correcto de errores en el cliente
2async function handlePasskeyLogin() {
3  try {
4    const result = await loginWithPasskey();
5    if (result.verified) {
6      router.push('/dashboard');
7    }
8  } catch (error) {
9    if (error instanceof Error) {
10      if (error.name === 'NotAllowedError') {
11        // Usuario cancelo el dialogo o timeout
12        showMessage('Autenticacion cancelada. Intenta de nuevo.');
13      } else if (error.name === 'AbortError') {
14        // Otra ceremonia WebAuthn interrumpio esta
15        showMessage('Operacion interrumpida.');
16      } else {
17        showMessage('Error inesperado. Usa tu contrasena como alternativa.');
18        showPasswordFallback();
19      }
20    }
21  }
22}