Saltar al contenido principal

Obtener opciones para autenticación WebAuthn

Obtiene las opciones necesarias para iniciar el proceso de autenticación con una credencial WebAuthn/FIDO2 previamente registrada usando navigator.credentials.get().

🔑 Inicio de autenticación WebAuthn

Este endpoint genera un challenge y devuelve las opciones publicKey requeridas para que el frontend solicite autenticación mediante WebAuthn/FIDO2.

POST/auth/webauthn/authentication/options

Obtiene opciones de autenticación WebAuthn para credenciales previamente registradas

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

Flujo típico:

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

Request Body​

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

Tipos de Respuesta​

Respuesta Exitosa​

Opciones generadas (200)

Opciones listas para consumir en el frontend con navigator.credentials.get():

{
  "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 asociadas.

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

Campos de Respuesta​

Configuración de autenticación

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

allowCredentials

Lista de credenciales permitidas:

  • id: identificador de credencial en base64
  • type: siempre "public-key"
  • transports: medios soportados por la credencial (usb, nfc, internal, ble)

Ejemplo de Implementación (Frontend)​

// 1) Obtener opciones del servidor
const response = await fetch('/auth/webauthn/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

Notas​

Notas

  • No requiere autenticación JWT (parte del proceso de login, según el flujo actual)
  • Solo muestra credenciales del usuario especificado
  • Las opciones expiran típicamente en 60 segundos
  • Si el usuario no tiene credenciales WebAuthn, retorna 404

Endpoints Relacionados​

Consejos de Implementación​

Detección de soporte​

if (window.PublicKeyCredential) {
  // WebAuthn es soportado
} 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 seguridad o configuración