Saltar al contenido principal

Obtener opciones para registro WebAuthn

Endpoint: POST /auth/webauthn/registration/options

Obtiene las opciones necesarias para iniciar el proceso de registro de una nueva credencial WebAuthn/FIDO2, como llaves de seguridad o autenticación biométrica.

🔐 Requiere autenticación JWT​

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

Authorization: Bearer <accessToken>

📋 Respuestas​

✅ 200 OK​

  • Opciones de registro generadas

    {
      "rp": {
        "name": "SwapBits",
        "id": "localhost"
      },
      "user": {
        "id": "user-id-base64",
        "name": "usuario@ejemplo.com",
        "displayName": "usuario@ejemplo.com"
      },
      "challenge": "base64-challenge-string",
      "pubKeyCredParams": [
        {"type": "public-key", "alg": -7},
        {"type": "public-key", "alg": -257}
      ],
      "timeout": 60000,
      "attestation": "none",
      "authenticatorSelection": {
        "userVerification": "preferred",
        "requireResidentKey": false
      }
    }

❌ 401 Unauthorized​

  • Sin token válido

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

📊 Campos de respuesta​

Relying Party (rp)​

  • name: Nombre de la aplicación que aparecerá en el autenticador
  • id: Identificador único del dominio/aplicación

Usuario (user)​

  • id: ID único del usuario codificado en base64
  • name: Email o nombre de usuario
  • displayName: Nombre que se mostrará en el autenticador

Configuración de credencial​

  • challenge: Desafío criptográfico único para esta sesión de registro
  • pubKeyCredParams: Algoritmos de clave pública soportados
  • timeout: Tiempo límite en milisegundos para completar el registro (60 segundos)
  • attestation: Tipo de attestation requerida ("none" para mayor compatibilidad)

Selección de autenticador​

  • userVerification: Preferencia de verificación de usuario ("preferred")
  • requireResidentKey: Si requiere llaves residentes (false para mayor compatibilidad)

🔄 Flujo de registro WebAuthn​

  1. Obtener opciones: Llamar a este endpoint para recibir opciones de registro
  2. Crear credencial: Usar las opciones con navigator.credentials.create() en el frontend
  3. Verificar credencial: Enviar la credencial generada a /auth/webauthn/registration/verify

💻 Ejemplo de implementación frontend​

// 1. Obtener opciones del servidor
const response = await fetch('/auth/webauthn/registration/options', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  }
});
const options = await response.json();

// 2. Crear credencial WebAuthn
const credential = await navigator.credentials.create({
  publicKey: options
});

// 3. Enviar al servidor para verificación
// (ver webauthn-registration-verify.md)

🛡️ Características de seguridad​

  • Challenge único: Cada solicitud genera un challenge criptográfico único
  • Timeout limitado: Las opciones expiran en 60 segundos
  • Algoritmos seguros: Soporte para ES256 y RS256
  • Verificación flexible: Configuración que maximiza compatibilidad de dispositivos

📝 Notas​

  • Las opciones generadas son válidas por 60 segundos
  • Compatible con llaves FIDO2/WebAuthn estándar (YubiKey, etc.)
  • Soporte para autenticación biométrica (TouchID, Windows Hello, etc.)
  • No requiere que el usuario tenga credenciales WebAuthn previamente registradas

🔗 Endpoints relacionados​

Siguiente paso: Usar las opciones recibidas para crear una credencial WebAuthn en el frontend y luego verificarla con /auth/webauthn/registration/verify.