Web y desarrollo

Passkeys y WebAuthn en 2026: Guía práctica de implementación para desarrolladores web

Passkeys and WebAuthn in 2026: A Practical Implementation Guide for Web Developers

Los passkeys prometen iniciar sesión sin contraseña sin almacenar secretos de contraseña, pero implementar WebAuthn correctamente requiere más que simplemente llamar a una API del navegador. Aprende cómo el registro, la autenticación, la verificación del lado del servidor, las credenciales descubiertas y la recuperación de cuentas se integran en una aplicación web segura.

Passkeys y WebAuthn en 2026: Una guía práctica de implementación para desarrolladores web

Las contraseñas han sido el mecanismo de autenticación predeterminado para las aplicaciones web durante décadas. También son una fuente persistente de problemas de seguridad.

Los usuarios las reutilizan. Los atacantes las roban mediante phishing. Los servidores deben proteger los hashes de contraseñas, gestionar restablecimientos y defenderse contra ataques de relleno de credenciales (credential stuffing).

Las passkeys ofrecen un enfoque fundamentalmente diferente.

En lugar de pedir a los usuarios que recuerden un secreto compartido, las passkeys utilizan criptografía de clave pública y un autenticador controlado por el usuario. El navegador proporciona una interfaz estándar a través de WebAuthn, mientras que el servidor verifica la evidencia criptográfica de que se utilizó la credencial correcta.

La tecnología ya no es experimental. WebAuthn está ampliamente disponible en los navegadores modernos, y sus métodos de conveniencia JSON han simplificado considerablemente la integración.

Pero construir un inicio de sesión seguro con passkeys aún requiere un diseño cuidadoso del backend.

Esta guía explica la arquitectura, demuestra los flujos del lado del navegador e identifica las comprobaciones del lado del servidor que los desarrolladores no deben pasar por alto.

1. ¿Qué es exactamente una passkey?

Una passkey es una credencial FIDO detectable utilizada para autenticar a un usuario mediante criptografía de clave pública.

Durante el registro, un autenticador crea un par de claves criptográficas.

La clave privada permanece protegida por el autenticador o su ecosistema de gestión de credenciales. El sitio web recibe la clave pública correspondiente y la asocia con la cuenta del usuario.

Durante la autenticación, el servidor emite un desafío fresco. El autenticador firma datos asociados con ese desafío, y el servidor verifica la firma utilizando la clave pública almacenada.

No se envía ninguna contraseña reutilizable al sitio web.

Un autenticador puede ser un smartphone, una computadora que use Windows Hello, una llave de seguridad hardware o un gestor de credenciales que soporte passkeys sincronizadas.

No toda passkey se sincroniza entre dispositivos. Algunas credenciales permanecen ligadas al dispositivo, mientras que otras pueden ser respaldadas de forma segura y puestas a disposición a través de un proveedor de credenciales.

Las especificaciones FIDO están diseñadas para resistir el phishing vinculando las credenciales al dominio de la parte confiante (relying party). Los datos biométricos, cuando se usan, se manejan localmente en el dispositivo en lugar de enviarse al sitio web.

2. WebAuthn es la API del navegador detrás de las passkeys

WebAuthn es la API de la plataforma web que permite a los sitios web crear y usar credenciales de clave pública.

Dos métodos del navegador forman la base:

navigator.credentials.create()
navigator.credentials.get()

El primero crea una credencial. El segundo solicita autenticación usando una credencial existente.

Ambos métodos funcionan con la opción publicKey y requieren un contexto seguro, normalmente HTTPS.

Importante: el navegador no decide si el usuario está autenticado. Devuelve datos que el backend debe verificar.

Un aviso exitoso del navegador no es prueba de que se deba aceptar un inicio de sesión.

El servidor sigue siendo responsable de verificar el desafío, el origen, el identificador de la parte confiante (RP ID) y la evidencia criptográfica.

3. Comprender la arquitectura completa

Una implementación típica contiene cuatro componentes:

  • El frontend de la aplicación web, que invoca WebAuthn.
  • El backend de la aplicación, que genera desafíos y verifica respuestas.
  • El autenticador o proveedor de passkeys, que protege la clave privada.
  • La base de datos, que almacena metadatos de credenciales y claves públicas.

El flujo de registro es: la aplicación web solicita opciones de registro; el backend genera un desafío y datos de usuario; el navegador y el autenticador crean una credencial y un par de claves; y el backend verifica el resultado y almacena la clave pública.

El servidor nunca debe confiar en los datos de registro simplemente porque fueron devueltos por el navegador.

Un cliente malicioso puede enviar peticiones HTTP arbitrarias sin usar el frontend esperado en absoluto.

Por eso la verificación pertenece al servidor.

4. Generar opciones de registro en el servidor

Antes de llamar a WebAuthn, el backend genera un desafío de registro y opciones.

Un objeto de opciones representativo se ve así:

{
  "rp": {
    "name": "Example Application",
    "id": "example.com"
  },
  "user": {
    "id": "dXNlci0xMjM",
    "name": "alex@example.com",
    "displayName": "Alex"
  },
  "challenge": "SERVER_GENERATED_BASE64URL_CHALLENGE",
  "pubKeyCredParams": [
    {
      "type": "public-key",
      "alg": -7
    }
  ],
  "authenticatorSelection": {
    "residentKey": "required",
    "userVerification": "required"
  },
  "attestation": "none",
  "timeout": 300000
}

Esto es JSON ilustrativo, no una respuesta completa de producción.

Varios campos importan.

rp.id identifica la parte confiante. Por ejemplo, example.com puede usarse para subdominios apropiados de ese dominio, sujeto a las reglas de validación de RP ID de WebAuthn.

user.id debe ser un identificador de cuenta estable y opaco codificado como base64url para transporte JSON. No debe exponer información personal innecesaria.

challenge debe generarse usando una fuente aleatoria criptográficamente segura en el servidor.

residentKey: "required" solicita una credencial detectable, que es necesaria para la experiencia de passkey.

userVerification: "required" solicita verificación de usuario local, como un PIN del dispositivo o autenticación biométrica. El backend debe verificar después que la verificación realmente ocurrió.

La guía del lado del servidor de Google para registro describe estos campos y recomienda usar una librería WebAuthn mantenida para generar y validar datos de registro.

5. Crear la passkey en JavaScript

Los navegadores modernos proporcionan un método útil:

PublicKeyCredential.parseCreationOptionsFromJSON()

Convierte una representación JSON que contiene campos binarios codificados en base64url en la estructura esperada por WebAuthn.

Esto evita escribir lógica personalizada de conversión base64url-a-ArrayBuffer para cada campo.

Aquí hay una función simplificada de registro del lado del navegador:

async function registerPasskey() {
    const optionsResponse = await fetch(
        '/api/passkeys/register/options',
        {
            method: 'POST',
            credentials: 'same-origin',
            headers: {
                'Content-Type': 'application/json',
                'X-CSRF-Token': csrfToken
            }
        }
    );

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

    const optionsJson = await optionsResponse.json();

    const publicKey =
        PublicKeyCredential.parseCreationOptionsFromJSON(
            optionsJson
        );

    const credential = await navigator.credentials.create({
        publicKey
    });

    if (!credential) {
        throw new Error('No credential was created');
    }

    const verifyResponse = await fetch(
        '/api/passkeys/register/verify',
        {
            method: 'POST',
            credentials: 'same-origin',
            headers: {
                'Content-Type': 'application/json',
                'X-CSRF-Token': csrfToken
            },
            body: JSON.stringify(credential.toJSON())
        }
    );

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

    return await verifyResponse.json();
}

La variable csrfToken representa un token anti-CSRF proporcionado por la aplicación. El servidor debe validarlo. El ejemplo también asume que la página ya está asociada con un usuario autenticado de forma segura.

credential.toJSON() proporciona una representación amigable para JSON de la credencial devuelta, evitando otra capa de serialización binaria manual.

Estas conveniencias están disponibles en navegadores actuales, aunque las aplicaciones que soportan versiones antiguas de navegadores deben proporcionar manejo de compatibilidad.

El código anterior es solo el lado del navegador. No es una implementación completa de autenticación.

6. Qué debe verificar el servidor durante el registro

Cuando el navegador devuelve la nueva credencial, el backend debe validarla antes de almacenar nada.

Como mínimo, el proceso de verificación debe establecer que:

  1. El desafío devuelto coincide con el generado para este intento de registro.
  2. El desafío es fresco y no se ha consumido ya.
  3. El origen reportado coincide con un origen de aplicación explícitamente confiable.
  4. Los datos del autenticador corresponden al RP ID esperado.
  5. Se satisfacen las condiciones requeridas de presencia de usuario y verificación de usuario.
  6. La clave pública y el identificador de la credencial pueden extraerse y validarse.
  7. El registro está asociado con la cuenta autenticada correcta.

Dependiendo de la política de la aplicación, comprobaciones adicionales pueden incluir algoritmos soportados, unicidad de credencial y requisitos de atestación.

Un registro exitoso típicamente almacena:

Campo Propósito
credential_id Identifica la credencial
user_id La vincula a una cuenta
public_key Verifica firmas futuras
sign_count Rastrea datos de contador del autenticador
transports Pistas opcionales de transporte del autenticador
created_at Marca de tiempo de registro
last_used_at Gestión de cuentas y auditoría
backup_eligible / backup_state Metadatos opcionales relacionados con respaldo

La representación exacta en la base de datos depende de la librería de verificación y la aplicación.

No implementes análisis CBOR, verificación de atestación o validación de firma criptográfica desde cero a menos que tengas una razón convincente y la experiencia para mantenerla.

La especificación W3C define procedimientos detallados de verificación de registro y autenticación.

7. Autenticar a un usuario existente

La autenticación sigue una estructura similar pero no crea un nuevo par de claves.

El servidor genera un nuevo desafío y envía opciones de autenticación al navegador.

Para un inicio de sesión con passkey detectable, esas opciones podrían contener:

{
  "challenge": "NEW_SERVER_GENERATED_CHALLENGE",
  "rpId": "example.com",
  "userVerification": "required",
  "timeout": 300000
}

El navegador puede entonces solicitar una credencial:

async function authenticateWithPasskey() {
    const optionsResponse = await fetch(
        '/api/passkeys/login/options',
        {
            credentials: 'same-origin'
        }
    );

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

    const optionsJson = await optionsResponse.json();

    const publicKey =
        PublicKeyCredential.parseRequestOptionsFromJSON(
            optionsJson
        );

    const credential = await navigator.credentials.get({
        publicKey
    });

    if (!credential) {
        throw new Error('Authentication was cancelled');
    }

    const verifyResponse = await fetch(
        '/api/passkeys/login/verify',
        {
            method: 'POST',
            credentials: 'same-origin',
            headers: {
                'Content-Type': 'application/json'
            },
            body: JSON.stringify(credential.toJSON())
        }
    );

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

    return await verifyResponse.json();
}

Este ejemplo asume que el backend asocia el desafío emitido con una transacción de inicio de sesión anónima de corta duración, aplica limitación de tasa apropiada y establece una nueva sesión autenticada solo después de una verificación exitosa.

El servidor debe buscar el ID de credencial, verificar la aserción firmada con la clave pública almacenada, confirmar el desafío y el origen, y aplicar su política de verificación de usuario.

Solo entonces debe establecer la sesión del usuario.

parseRequestOptionsFromJSON() es parte de la API moderna de WebAuthn y elimina la necesidad de decodificar manualmente campos binarios en integraciones comunes del lado del navegador.

8. Añadir passkeys a formularios de inicio de sesión existentes con mediación condicional

Una de las características más útiles de WebAuthn es la mediación condicional, a veces llamada autocompletado de passkey.

En lugar de mostrar un diálogo de passkey separado inmediatamente, el navegador puede ofrecer una passkey disponible junto con otras credenciales guardadas cuando el usuario interactúa con un campo de inicio de sesión.

La entrada HTML puede usar:

<input
    type="text"
    name="username"
    autocomplete="username webauthn"
>

La aplicación puede verificar el soporte:

const supported =
    await PublicKeyCredential.isConditionalMediationAvailable();

if (supported) {
    // Request authentication with mediation: 'conditional'.
}

Al llamar a navigator.credentials.get(), la aplicación usa:

{
    publicKey,
    mediation: 'conditional'
}

Para autocompletado de credenciales detectables, las opciones del servidor no deben restringir la solicitud a una lista específica de IDs de credencial.

La mediación condicional es especialmente útil durante una migración gradual desde contraseñas porque los usuarios no necesitan recordar si una cuenta particular tiene una passkey.

El navegador puede presentar opciones apropiadas en la experiencia de inicio de sesión familiar.

9. Por qué las comprobaciones de desafío y origen son esenciales

Las passkeys son resistentes al phishing, pero eso no significa que una aplicación pueda ignorar su protocolo de autenticación.

El desafío protege contra ataques de repetición (replay attacks).

Sin un desafío fresco e impredecible, un atacante podría intentar reutilizar datos de autenticación de una sesión anterior.

Las comprobaciones de origen e RP ID aseguran que las credenciales se usan en el contexto del sitio web previsto.

Por ejemplo, una passkey creada para example.com no puede simplemente reutilizarse por un sitio de phishing similar como examp1e.com.

El navegador y el autenticador aplican partes importantes de este enlace de dominio, mientras que el backend valida independientemente la evidencia resultante.

Una buena implementación usa desafíos de corta duración, consume cada desafío una vez y nunca acepta orígenes arbitrarios solo porque comparten un nombre de host de apariencia familiar.

MDN recomienda generar desafíos en un entorno de confianza e invalidarlos después de un período corto, generalmente no más de unos diez minutos.

10. No malinterpretes los contadores de firma

Los autenticadores WebAuthn pueden incluir un contador de firma.

Históricamente, los contadores ayudaban a detectar autenticadores potencialmente clonados. Si un contador deja de aumentar inesperadamente, la parte confiante puede considerar eso una señal de riesgo.

Sin embargo, no todo autenticador mantiene un contador significativo.

Algunas credenciales siempre reportan cero. Las credenciales sincronizadas también pueden complicar la interpretación del contador porque múltiples dispositivos pueden usar copias de la misma credencial.

La especificación W3C trata explícitamente el comportamiento inesperado del contador como una posible señal, no como prueba definitiva de clonación.

Por lo tanto, los desarrolladores no deben rechazar ciegamente cada inicio de sesión cuyo contador sea cero o inalterado.

Usa el contador según el comportamiento del autenticador, la guía de la librería de verificación WebAuthn y la política de seguridad de la aplicación.

11. La recuperación de cuenta es parte de la seguridad de passkeys

Una implementación de passkeys está incompleta sin una estrategia de recuperación.

¿Qué pasa cuando un usuario pierde un dispositivo?

¿Y si elimina su única passkey?

¿Y si cambia de proveedor de credenciales o no puede acceder a una credencial sincronizada?

Un diseño sensato permite a los usuarios registrar múltiples passkeys y gestionarlas desde su configuración de cuenta.

La interfaz de gestión debe mostrar nombres de credenciales reconocibles, fechas de creación e información de uso reciente donde esté disponible.

Los usuarios deben poder revocar credenciales en las que ya no confíen.

Pero el mecanismo de recuperación merece especial cuidado.

Si un atacante puede eludir la autenticación de passkey usando un proceso de recuperación por email débil, la cuenta en general es tan segura solo como ese camino de recuperación.

Para cuentas de mayor riesgo, considera verificación de recuperación más fuerte, códigos de recuperación, autenticadores adicionales registrados y notificaciones sobre cambios sensibles en la cuenta.

La guía UX de passkeys de Google recomienda establecer un método de recuperación y soportar múltiples passkeys donde sea apropiado.

12. Errores comunes de implementación

Varios errores socavan repetidamente integraciones de passkeys que de otro modo serían prometedoras.

Tratar el éxito del navegador como autenticación del servidor. Una promesa navigator.credentials.get() resuelta no reemplaza la verificación criptográfica del lado del servidor.

Generar desafíos en JavaScript. Los desafíos deben venir de un servidor de confianza y vincularse a la transacción de autenticación apropiada.

Usar el RP ID incorrecto. El alcance de dominio es una característica de seguridad, no una configuración cosmética. Los entornos de producción, staging y desarrollo local requieren configuración deliberada.

Asumir que todas las passkeys se sincronizan. Las credenciales ligadas al dispositivo siguen siendo una parte importante del ecosistema.

Olvidar la revocación de credenciales. Los usuarios necesitan una forma de eliminar un autenticador perdido o comprometido de su cuenta.

Crear un respaldo débil. Un inicio de sesión resistente al phishing pierde gran parte de su valor si la recuperación de cuenta puede explotarse fácilmente.

Ignorar navegadores antiguos. Los métodos de conveniencia JSON modernos reducen la complejidad, pero las aplicaciones con requisitos de navegadores antiguos aún pueden necesitar código de compatibilidad.

Saltar la protección CSRF y de sesión. El registro y las operaciones de gestión de credenciales son cambios sensibles de cuenta. Necesitan las mismas protecciones que otras acciones de alto impacto en la cuenta.

Escribir verificación criptográfica personalizada innecesariamente. Una librería WebAuthn de servidor mantenida suele ser una opción más segura que implementar la especificación directamente.

13. ¿Debería cada sitio web reemplazar las contraseñas inmediatamente?

No necesariamente.

Las passkeys pueden mejorar tanto la usabilidad como la seguridad, pero la estrategia de migración importa.

Para una aplicación nueva, el registro sin contraseña puede ser un predeterminado razonable si el producto tiene un flujo de recuperación bien diseñado y soporta sus plataformas objetivo.

Para una aplicación existente con miles de usuarios, la adopción incremental suele ser más segura.

Comienza permitiendo a usuarios autenticados registrar passkeys en la configuración de cuenta.

Luego añade inicio de sesión con passkey junto al sistema de autenticación existente.

Introduce mediación condicional donde se soporte.

Mide éxito de registro, fallos de autenticación, compatibilidad de dispositivos y solicitudes de recuperación.

Finalmente, considera hacer de las passkeys el método de autenticación preferido una vez que la experiencia de usuario y los mecanismos de recuperación sean lo suficientemente maduros.

Un lanzamiento por fases también facilita identificar problemas específicos de navegador sin bloquear a usuarios legítimos.

14. Una lista de verificación de preparación para producción

Antes de habilitar passkeys en producción, verifica lo siguiente:

  • Todas las operaciones WebAuthn se ejecutan en un contexto seguro apropiado.
  • Los RP IDs y orígenes confiables están configurados explícitamente.
  • Los desafíos son aleatorios criptográficamente, de corta duración y de un solo uso.
  • El registro requiere autorización de cuenta apropiada.
  • La verificación del lado del servidor sigue la especificación WebAuthn.
  • Las claves públicas e identificadores de credencial se almacenan de forma segura.
  • El inicio de sesión establece una sesión solo después de verificación exitosa.
  • Los requisitos de verificación de usuario se aplican en el servidor.
  • La eliminación de credenciales y la recuperación de cuenta están protegidas.
  • Múltiples credenciales por cuenta son soportadas donde sea apropiado.
  • Los fallos de autenticación y cambios sensibles de cuenta son monitorizados.
  • Escenarios móvil, escritorio, cross-device y llave hardware son probados.

Estas comprobaciones importan más que si el frontend puede mostrar un aviso de inicio de sesión biométrico atractivo.

Conclusión: las passkeys son una arquitectura de autenticación, no solo una característica del navegador

WebAuthn hace la autenticación de clave pública accesible para aplicaciones web ordinarias.

Las APIs modernas del navegador han eliminado gran parte del trabajo de serialización que hacía la integración de passkeys engorrosa anteriormente.

Pero el navegador es solo una parte del sistema.

El trabajo real de implementación está en la gestión de desafíos, verificación del lado del servidor, almacenamiento de credenciales, configuración de dominio, recuperación de cuenta y viajes de usuario seguros.

Para desarrolladores construyendo aplicaciones modernas en PHP, JavaScript, Python u otros entornos de backend, las passkeys son cada vez más dignas de considerarse como una alternativa práctica a las contraseñas tradicionales.

El mejor punto de partida no es reemplazar un sistema de autenticación completo de la noche a la mañana.

Es implementar un flujo completo de registro e inicio de sesión, verificado correctamente, y luego construir una estrategia de migración segura alrededor de él.