Saltar al contenido principal

Obtener opciones para autenticación WebAuthn

Endpoint público para iniciar el flujo de login con WebAuthn/FIDO2 obteniendo las publicKey options necesarias para navigator.credentials.get(). No requiere JWT.

🔓 Endpoint público (sin JWT)

Este endpoint está diseñado para usarse durante el proceso de login. Genera un challenge y devuelve las opciones necesarias para autenticar al usuario con una credencial WebAuthn previamente registrada.

POST/auth/authentication/options

Obtiene opciones de autenticación WebAuthn para login (sin JWT)

📋 Parámetros

emailstringrequerido

Correo electrónico del usuario que desea autenticarse

📤 Respuesta

{
"challenge": "base64-challenge-string",
"timeout": 60000,
"rpId": "localhost",
"allowCredentials": [
  {
    "id": "credential-id-base64",
    "type": "public-key",
    "transports": ["usb", "nfc"]
  },
  {
    "id": "another-credential-id-base64",
    "type": "public-key",
    "transports": ["internal"]
  }
],
"userVerification": "preferred"
}

Contexto de Uso​

Este endpoint se usa como Paso 1 del login con WebAuthn:

  1. Enviar email para obtener opciones (publicKey)
  2. Ejecutar navigator.credentials.get({ publicKey: options }) en frontend
  3. Enviar la respuesta al endpoint de verificación: /auth/webauthn/authentication/verify

Request Body​

{
  "email": "usuario@ejemplo.com"
}

Tipos de Respuesta​

Respuesta Exitosa​

Opciones generadas (200)

El servidor devuelve las opciones necesarias para iniciar la autenticación en el navegador.

{
  "challenge": "base64-challenge-string",
  "timeout": 60000,
  "rpId": "localhost",
  "allowCredentials": [
    {
      "id": "credential-id-base64",
      "type": "public-key",
      "transports": ["usb", "nfc"]
    },
    {
      "id": "another-credential-id-base64",
      "type": "public-key",
      "transports": ["internal"]
    }
  ],
  "userVerification": "preferred"
}

Errores​

Email requerido (400)

No se proporcionó el email.

{
  "message": "Email is required"
}

Usuario no encontrado o sin credenciales (404)

El usuario no existe o no tiene credenciales WebAuthn registradas.

{
  "message": "No WebAuthn credentials found for user"
}

Campos de Respuesta​

Configuración de autenticación

  • challenge: desafío criptográfico único para la sesión
  • timeout: límite para completar la operación (ms) — típico 60000
  • rpId: identificador del relying party (dominio/aplicación)
  • userVerification: nivel de verificación requerido (ej. preferred)

allowCredentials

Lista de credenciales permitidas para el usuario:

  • id: ID de la credencial en base64
  • type: siempre "public-key"
  • transports: métodos soportados (usb, nfc, internal, ble)

Ejemplo de Implementación (Frontend)​

// 1) Obtener opciones del servidor (SIN token de autorización)
const response = await fetch('/auth/authentication/options', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ email: 'usuario@ejemplo.com' })
});
const options = await response.json();

// 2) Solicitar autenticación WebAuthn
const credential = await navigator.credentials.get({
  publicKey: options
});

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

Tipos de Transporte​

Transports soportados

  • usb: llaves físicas USB (YubiKey, etc.)
  • nfc: llaves NFC (autenticación por proximidad)
  • internal: autenticadores integrados (TouchID, Windows Hello, biometría)
  • ble: llaves Bluetooth / móviles como autenticadores

Diferencias con /auth/webauthn/authentication/options​

Este endpoint (/auth/authentication/options) es distinto del endpoint autenticado /auth/webauthn/authentication/options:

Característica/auth/authentication/options/auth/webauthn/authentication/options
Autenticación JWT❌ No requerida✅ Requerida
Uso principalLogin inicialGestión de credenciales
ContextoUsuario aún no autenticadoUsuario ya autenticado

Notas​

Notas de implementación

  • No requiere autenticación JWT (es parte del proceso de login)
  • Las opciones expiran típicamente en 60 segundos
  • Si el usuario no tiene credenciales WebAuthn, retorna 404
  • Diseñado específicamente para el flujo de login con WebAuthn

Consideraciones de Seguridad​

Protecciones recomendadas

  • Endpoint público pero limitado por email del usuario
  • Aplicar rate limiting para prevenir enumeración de usuarios
  • No exponer metadata sensible de las credenciales
  • Challenge único por solicitud para prevenir ataques de replay

Endpoints Relacionados​

Consejos de Implementación​

Detección de soporte​

if (window.PublicKeyCredential) {
  // WebAuthn es soportado
  // Mostrar opción de login con WebAuthn
} else {
  // Fallback a otros métodos de autenticación
}

Manejo de errores (cliente)​

  • Timeout: el usuario tardó demasiado en responder
  • NotAllowedError: el usuario canceló la operación
  • SecurityError: error de configuración o políticas del navegador