Saltar al contenido principal

Verificar y guardar credencial WebAuthn

Endpoint: POST /auth/webauthn/registration/verify

Verifica y guarda una nueva credencial WebAuthn/FIDO2 generada por el cliente usando las opciones obtenidas previamente.

🔐 Requiere autenticación JWT​

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

Authorization: Bearer <accessToken>

📝 Cuerpo de la solicitud​

{
  "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"
}

Parámetros:

  • credential: Objeto credencial completo generado por navigator.credentials.create()
  • name (opcional): Nombre personalizado para identificar esta credencial

📋 Respuestas​

✅ 200 OK​

  • Credencial verificada y guardada

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

❌ 400 Bad Request​

  • Credencial inválida

    {
      "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"
    }

❌ 401 Unauthorized​

  • Sin token válido

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

🔍 Proceso de verificación​

Validaciones realizadas​

  1. Challenge: Verifica que el challenge coincida con el generado previamente
  2. Origen: Confirma que la credencial fue creada para el dominio correcto
  3. Formato: Valida la estructura del objeto credencial
  4. Unicidad: Verifica que la credencial no esté ya registrada
  5. Attestation: Procesa la attestation si está presente

Datos almacenados​

  • ID de credencial: Identificador único de la credencial
  • Clave pública: Para futuras verificaciones de autenticación
  • Contador: Para detectar credenciales clonadas
  • Metadatos: Información del autenticador y 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: 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​

  • YubiKey: Todas las versiones FIDO2
  • Google Titan: Llaves de seguridad de Google
  • Feitian: Llaves de seguridad compatibles
  • Otras: Cualquier llave certificada FIDO2

Autenticación biométrica​

  • TouchID: En dispositivos Apple compatibles
  • Windows Hello: Huella dactilar y reconocimiento facial
  • Android: Autenticación biométrica nativa
  • Otros: Autenticadores integrados compatibles

📝 Notas​

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

🔗 Endpoints relacionados​

⚡ Consejos de implementación​

  • Maneja errores de usuario (cancelación, timeout)
  • Proporciona feedback visual durante el proceso
  • Permite nombres descriptivos para múltiples credenciales
  • Verifica soporte WebAuthn antes de mostrar la opción

Requisito previo: Debes haber obtenido opciones válidas de /auth/webauthn/registration/options antes de intentar verificar una credencial.