Skip to main content

Obtener opciones para autenticación WebAuthn (sin JWT)

Endpoint: POST /auth/authentication/options

Obtiene las opciones necesarias para iniciar el proceso de autenticación con una credencial WebAuthn/FIDO2 previamente registrada. Este endpoint NO requiere autenticación JWT y está diseñado para ser usado durante el proceso de login.

📝 Cuerpo de la solicitud​

{
  "email": "usuario@ejemplo.com"
}
  • email: Correo electrónico del usuario que desea autenticarse

📋 Respuestas​

✅ 200 OK​

  • Opciones de autenticación generadas

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

❌ 400 Bad Request​

  • Email no proporcionado

    {
      "message": "Email is required"
    }

❌ 404 Not Found​

  • Usuario no encontrado o sin credenciales

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

📊 Campos de respuesta​

Configuración de autenticación​

  • challenge: Desafío criptográfico único para esta sesión de autenticación
  • timeout: Tiempo límite en milisegundos para completar la autenticación (60 segundos)
  • rpId: Identificador del dominio/aplicación
  • userVerification: Nivel de verificación de usuario requerido

Credenciales permitidas (allowCredentials)​

  • id: ID de la credencial codificado en base64
  • type: Tipo de credencial (siempre "public-key")
  • transports: Métodos de transporte soportados por la credencial

🔄 Flujo de autenticación WebAuthn (Login)​

  1. Obtener opciones: Llamar a este endpoint con el email del usuario
  2. Solicitar autenticación: Usar las opciones con navigator.credentials.get() en el frontend
  3. Verificar autenticación: Enviar la respuesta a /auth/webauthn/authentication/verify

💻 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​

USB​

  • Llaves de seguridad conectadas por USB
  • YubiKey y similares

NFC​

  • Llaves de seguridad con comunicación NFC
  • Autenticación tocando el dispositivo

Internal​

  • Autenticadores integrados en el dispositivo
  • TouchID, Windows Hello, autenticación biométrica

Bluetooth​

  • Llaves de seguridad Bluetooth
  • Dispositivos móviles como autenticadores

🔒 Diferencias con /auth/webauthn/authentication/options​

Este endpoint (/auth/authentication/options) es diferente 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
ContextoProceso de autenticaciónUsuario ya autenticado

📝 Notas​

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

🔗 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​

  • Timeout: Usuario tardó demasiado en responder
  • NotAllowed: Usuario canceló la operación
  • Security: Error de seguridad o configuración

🔐 Consideraciones de seguridad​

  • Este endpoint es público pero limitado por email del usuario
  • Rate limiting aplicado para prevenir enumeración de usuarios
  • No expone información sensible sobre credenciales
  • Challenge único por solicitud para prevenir ataques de replay

Uso recomendado: Este endpoint debe ser usado exclusivamente durante el proceso de login cuando el usuario quiere autenticarse con WebAuthn en lugar de email/contraseña.