Saltar al contenido principal

Verificar y guardar credencial WebAuthn

Verifica una credencial creada con navigator.credentials.create() y, si es válida, la guarda para futuros logins con WebAuthn/FIDO2.

🔐 Requiere autenticación JWT

Debes enviar un token JWT válido en el header:

Authorization: Bearer <accessToken>

✅ Paso final del registro WebAuthn

Este endpoint valida el challenge, el origen y la estructura de la credencial. Si todo es correcto, almacena la credencial (clave pública, contador y metadata) para permitir autenticación WebAuthn en el futuro.

POST/auth/webauthn/registration/verify

Verifica y guarda una nueva credencial WebAuthn del usuario autenticado

📋 Parámetros

credentialobjectrequerido

Objeto credencial completo generado por navigator.credentials.create()

namestring

Nombre personalizado para identificar la credencial (opcional)

📤 Respuesta

{
"verified": true,
"credentialId": "credential-uuid",
"name": "YubiKey de Juan",
"createdAt": "2025-01-20T14:45:00.000Z"
}

Contexto de Uso​

Flujo de registro WebAuthn:

  1. Obtener opciones desde /auth/webauthn/registration/options
  2. Crear credencial en frontend con navigator.credentials.create({ publicKey: options })
  3. Enviar la credencial a este endpoint para verificar y guardar

Request Body​

{
  "credential": {
    "id": "credential-id",
    "rawId": "raw-credential-id",
    "response": {
      "attestationObject": "attestation-object-base64",
      "clientDataJSON": "client-data-json-base64"
    },
    "type": "public-key"
  },
  "name": "YubiKey de Juan"
}

Tipos de Respuesta​

Respuesta Exitosa​

Credencial verificada y guardada (200)

{
  "verified": true,
  "credentialId": "credential-uuid",
  "name": "YubiKey de Juan",
  "createdAt": "2025-01-20T14:45:00.000Z"
}

Errores​

Errores de validación (400)

Credencial inválida (formato):

{
  "verified": false,
  "error": "Invalid credential format"
}

Challenge expirado o inválido:

{
  "verified": false,
  "error": "Invalid or expired challenge"
}

Credencial ya registrada:

{
  "verified": false,
  "error": "Credential already registered"
}

No autorizado (401)

Token ausente o inválido.

{
  "statusCode": 401,
  "message": "Unauthorized"
}

Proceso de Verificación​

Validaciones realizadas

  1. Challenge: coincide con el generado previamente
  2. Origen: la credencial fue creada para el dominio correcto (RP ID / origin)
  3. Formato: estructura del objeto credential
  4. Unicidad: la credencial no debe existir previamente
  5. Attestation: procesamiento según configuración (si aplica)

Datos almacenados

  • ID de credencial (identificador único)
  • Clave pública para futuras verificaciones
  • Contador de uso (detección de clonación)
  • Metadatos del autenticador y del usuario
  • Nombre personalizado (si se proporcionó)

Ejemplo de Implementación (Frontend)​

// Después de obtener options de /auth/webauthn/registration/options
const credential = await navigator.credentials.create({
  publicKey: options
});

// Verificar credencial
const verifyResponse = await fetch('/auth/webauthn/registration/verify', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    credential,
    name: 'Mi YubiKey' // Opcional
  })
});

const result = await verifyResponse.json();

if (result.verified) {
  console.log('Credencial registrada exitosamente');
}

Tipos de Credenciales Soportadas​

Llaves de seguridad (FIDO2)

  • YubiKey (todas las versiones FIDO2)
  • Google Titan
  • Feitian
  • Otras llaves certificadas FIDO2/WebAuthn

Autenticación biométrica

  • TouchID (Apple)
  • Windows Hello
  • Android Biometrics
  • Autenticadores integrados compatibles

Notas​

Notas

  • La credencial debe crearse con opciones de /auth/webauthn/registration/options
  • El campo name es opcional pero recomendado para gestionar múltiples credenciales
  • Una vez registrada, la credencial puede usarse para autenticación WebAuthn
  • Las credenciales registradas aparecerán en /auth/webauthn/credentials (ver documentación)

Endpoints Relacionados​

Consejos de Implementación​

Buenas prácticas

  • Manejar errores de usuario (cancelación, timeout)
  • Mostrar feedback visual durante el proceso
  • Permitir nombres descriptivos para múltiples credenciales
  • Verificar soporte WebAuthn antes de ofrecer la opción