Saltar al contenido principal

Obtener opciones para registro WebAuthn

Genera las opciones necesarias para iniciar el registro de una nueva credencial WebAuthn/FIDO2 (llave de seguridad o autenticación biométrica) usando navigator.credentials.create().

🔐 Requiere autenticación JWT

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

Authorization: Bearer <accessToken>

🧾 Registro de una nueva credencial

Este endpoint genera el challenge y los parámetros publicKey para registrar un autenticador (FIDO2/WebAuthn). Luego, el frontend crea la credencial y la envía a verificación.

POST/auth/webauthn/registration/options

Obtiene opciones de registro WebAuthn para el usuario autenticado

📤 Respuesta

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

Contexto de Uso​

Flujo de registro WebAuthn:

  1. Obtener opciones (este endpoint)
  2. Crear credencial con navigator.credentials.create({ publicKey: options })
  3. Verificar y guardar enviando la respuesta a /auth/webauthn/registration/verify

Tipos de Respuesta​

Respuesta Exitosa​

Opciones de registro generadas (200)

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

Errores​

No autorizado (401)

Token ausente o inválido.

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

Campos de Respuesta​

Relying Party (rp)

  • name: nombre de la aplicación mostrado por el autenticador
  • id: identificador del dominio/aplicación (RP ID)

Usuario (user)

  • id: identificador del usuario codificado en base64
  • name: email o username
  • displayName: nombre visible en el autenticador

Configuración de credencial

  • challenge: desafío criptográfico único para esta sesión
  • pubKeyCredParams: algoritmos de clave pública soportados (ES256, RS256, etc.)
  • timeout: límite de tiempo (ms), típico 60000
  • attestation: usualmente "none" para mayor compatibilidad

Selección de autenticador

  • userVerification: preferencia de verificación del usuario (ej. preferred)
  • requireResidentKey: si requiere credenciales residentes (false para compatibilidad)

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​

Controles de seguridad

  • Challenge único: previene ataques de replay
  • Timeout limitado: típicamente 60 segundos
  • Algoritmos seguros: soporte para ES256 (-7) y RS256 (-257)
  • Configuración flexible: maximiza compatibilidad entre dispositivos

Notas​

Notas

  • Las opciones generadas son válidas típicamente por 60 segundos
  • Compatible con llaves FIDO2/WebAuthn (YubiKey, etc.)
  • Soporta autenticación biométrica (TouchID, Windows Hello, etc.)
  • No requiere credenciales WebAuthn previas: sirve para registrar una nueva

Endpoints Relacionados​