Explicación de la mediación inmediata de WebAuthn

60-page Enterprise Passkey Whitepaper:
Learn how leaders get +80% passkey adoption. Trusted by Rakuten, Klarna & Oracle

Get free Whitepaper

La transición a las passkeys está creando una "paradoja de las passkeys": algunos usuarios tienen passkeys, mientras que muchos otros todavía usan contraseñas tradicionales. Esto lleva a pantallas de inicio de sesión sobrecargadas con múltiples botones: "Iniciar sesión con contraseña", "Iniciar sesión con Google" e "Iniciar sesión con Passkey". Esta fragmentación causa fricción. Un usuario podría hacer clic en "Iniciar sesión con Passkey" en un nuevo dispositivo solo para encontrarse con un confuso aviso de código QR porque su passkey no está disponible localmente. El problema principal es la incapacidad del sitio web para conocer el contexto del usuario antes de iniciar un flujo de autenticación.

Una solución es optar por un enfoque de "primero el identificador" y determinar el mejor método de inicio de sesión para el usuario. Otra posible solución es un único botón inteligente de "Iniciar sesión" que organice el flujo más fluido para cada usuario. Debería solicitar directamente una passkey si hay una disponible en el dispositivo, o recurrir elegantemente a otros métodos si no la hay.

Se ha anunciado una nueva función de WebAuthn que podría hacer esto posible: la mediación inmediata (mediation: 'immediate'). Al establecer esta propiedad en una llamada a la API de WebAuthn, los desarrolladores pueden construir una experiencia de inicio de sesión inteligente y unificada que resuelve la paradoja de las passkeys. Este artículo ofrece un análisis enfocado en desarrolladores sobre mediation: 'immediate', explorando qué es, cómo funciona y cómo implementarla.

Para entender la mediación inmediata, es útil conocer primero las otras opciones. La mediación del usuario en WebAuthn es la forma en que el navegador gestiona la interacción entre tu sitio web (el Relying Party) y el autenticador del usuario (p. ej., Face ID, YubiKey).

Este es el flujo clásico y explícito de WebAuthn. Cuando un Relying Party llama a navigator.credentials.get() sin especificar una preferencia de mediation, el navegador siempre presenta un diálogo modal. Este diálogo se superpone al contenido de la página, exigiendo la atención inmediata del usuario y pausando cualquier otra interacción con el sitio web.

• Caso de uso: Ideal para botones dedicados de "Iniciar sesión con Passkey" donde el usuario ha expresado claramente su intención.
• Limitación: Si el usuario no tiene una passkey en el dispositivo actual, se le muestra un flujo entre dispositivos (p. ej., código QR), lo que puede ser un callejón sin salida confuso.

Want to experiment with passkey flows? Try our Passkeys Debugger.

Try for Free

Introducido para ayudar a los usuarios en la transición a las passkeys, este modo es más sutil. Con mediation: 'conditional', la solicitud de WebAuthn se adjunta a un campo de entrada (p. ej., nombre de usuario) con el atributo autocomplete="webauthn". Cuando el usuario hace clic en el campo, la interfaz de autocompletar del navegador sugiere cualquier passkey disponible.

• Caso de uso: Ideal para mejorar progresivamente los formularios de inicio de sesión tradicionales, permitiendo a los usuarios descubrir y usar passkeys sin un botón separado.
• Limitación: Prioriza la privacidad de forma tan estricta que si el usuario no tiene una passkey o no interactúa con el aviso, la promesa de la llamada a la API nunca se resuelve. El sitio web no recibe ninguna señal, lo que hace imposible organizar una interfaz de fallback.

mediation: 'immediate' es la solución al problema del "botón único de inicio de sesión". Proporciona una forma fiable para que un sitio web compruebe la disponibilidad de una passkey antes de mostrar cualquier interfaz de usuario.

En lugar de decirle al usuario que se autentique con una passkey a través de un modal, la mediación immediate le pregunta al navegador: "¿Hay una passkey fácilmente disponible para este usuario en este dispositivo ahora mismo?"

Crucialmente, esta consulta solo verifica las credenciales disponibles localmente (p. ej., autenticadores en el dispositivo como Windows Hello o passkeys sincronizadas a través de un gestor de contraseñas). Está diseñada para evitar activar el flujo de código QR entre dispositivos, que es un punto de fricción común.

Want to try passkeys yourself in a passkeys demo?

Try Passkeys

El poder de esta función reside en su resultado claro y binario. La promesa devuelta por navigator.credentials.get() tendrá éxito o fallará, dando al desarrollador una señal clara.

• Vía 1 (Éxito): Existe una credencial. Si el navegador encuentra una passkey disponible localmente, omite la interfaz de usuario del sitio web e inmediatamente presenta su propio modal nativo, como un selector de cuentas. Si el usuario se autentica con éxito, la promesa se resuelve con el objeto PublicKeyCredential.
• Vía 2 (Fallo): No existe ninguna credencial. Si el navegador no encuentra credenciales disponibles localmente, no muestra ninguna interfaz de usuario. En su lugar, la promesa de navigator.credentials.get() se rechaza inmediatamente con una DOMException llamada NotAllowedError.

El NotAllowedError no es un error. Es más bien una característica. Es una señal fiable e instantánea de que el sitio web debe proceder con un método de autenticación de fallback. Esto permite a los desarrolladores usar un simple bloque try...catch: el bloque try intenta el flujo fluido de passkey, y el bloque catch escucha el NotAllowedError para renderizar un formulario de inicio de sesión tradicional. Resuelve elegantemente el problema del botón único de inicio de sesión creando un único punto de entrada que se adapta inteligentemente al contexto del usuario.

Elegir el modo de mediación correcto es una decisión crítica de UX. Esta tabla ofrece una comparación lado a lado.

Aquí tienes una guía práctica, paso a paso, para implementar mediation: 'immediate'.

Dado que mediation: 'immediate' es una nueva característica, una detección de características robusta es crucial.

// Feature detection is essential for progressive enhancement.
let immediateMediationAvailable = false;
 
if (window.PublicKeyCredential && PublicKeyCredential.getClientCapabilities) {
    try {
        const capabilities = await PublicKeyCredential.getClientCapabilities();
        // The 'immediateGet' capability signals browser support.
        immediateMediationAvailable = capabilities.immediateGet === true;
    } catch (e) {
        console.error("Error getting client capabilities:", e);
    }
}

Esta llamada debe ser activada por un gesto del usuario, como el clic en un botón.

// This function should be the event handler for your primary "Sign In" button.
async function handleSignInClick() {
    if (!immediateMediationAvailable) {
        // Fall back to showing a legacy login form if the feature isn't supported.
        showLegacyLoginForm();
        return;
    }
 
    try {
        // Fetch a fresh, random challenge from your server for each attempt.
        const challenge = await fetchChallengeFromServer();
 
        const publicKeyCredentialRequestOptions = {
            challenge: challenge, // The server-provided challenge as a Uint8Array
            rpId: "example.com",
            // The allowCredentials list MUST be empty for immediate mediation
            // to protect user privacy.
            allowCredentials: [],
        };
 
        const credential = await navigator.credentials.get({
            publicKey: publicKeyCredentialRequestOptions,
            // This is the key that enables the immediate mediation flow.
            mediation: "immediate",
        });
 
        // If the promise resolves, send the credential to your server for verification.
        await verifyCredentialOnServer(credential);
    } catch (error) {
        // The catch block is a critical part of the control flow.
        handleAuthError(error);
    }
}

El bloque catch es donde se materializa la "inteligencia" del botón único de inicio de sesión.

// Handling the NotAllowedError is the key to the fallback mechanism.
function handleAuthError(error) {
    // Check the 'name' property of the DOMException.
    if (error.name === "NotAllowedError") {
        // This is the expected signal to show the traditional login form.
        console.log("No local passkey found. Showing legacy login form.");
        showLegacyLoginForm();
    } else {
        // This handles other potential errors, like the user dismissing the prompt.
        console.error("Authentication error:", error);
    }
}

Para la experiencia más fluida, puedes pedirle al navegador que busque tanto passkeys como contraseñas guardadas en la misma solicitud añadiendo password: true.

// Combining passkeys and passwords for a truly unified sign-in experience.
const credential = await navigator.credentials.get({
    publicKey: publicKeyCredentialRequestOptions,
    password: true, // Ask the browser to include saved passwords.
    mediation: "immediate",
});
 
// The returned 'credential' object will either be a PublicKeyCredential
// or a PasswordCredential. Your server-side logic must handle both.

1. Solicitudes WebAuthn concurrentes: Una solicitud conditional pendiente (a menudo iniciada en la carga de la página) puede bloquear una nueva solicitud immediate. Considera usar un AbortController para cancelar cualquier solicitud pendiente antes de iniciar una nueva.
2. La restricción de allowCredentials: El array allowCredentials debe estar vacío. Proporcionar IDs de credenciales hará que la llamada falle. Esta es una salvaguarda de privacidad crucial para evitar que los sitios comprueben la presencia de usuarios específicos y conocidos.
3. El requisito del gesto del usuario: La llamada debe ser iniciada por un gesto del usuario (p. ej., un evento 'click'). Llamarla programáticamente en la carga de la página será bloqueado por los navegadores como medida de protección de la privacidad.

mediation: 'immediate' fue diseñada con una clara comprensión de sus contrapartidas de seguridad y privacidad.

La contrapartida principal es una "fuga de un bit". Al medir el tiempo de resolución de la promesa, un Relying Party puede inferir un bit de información: si la promesa se rechazó instantáneamente (no hay credencial local) o se retrasó (se mostró un aviso en la UI porque se encontró una credencial local). El propósito de esta fuga es permitir una mejor UX.

Los diseñadores anticiparon el potencial de abuso (p. ej., seguimiento de usuarios) e integraron varias salvaguardas no negociables:

1. Gesto de usuario obligatorio: La llamada a la API debe ser activada por una acción del usuario, como un clic. Esto evita que un sitio sondee silenciosamente en busca de cuentas al cargar la página y hace que el fingerprinting a gran escala sea impracticable.
2. Desactivado en modo privado/incógnito: La función no está permitida en los modos de navegación privada para evitar vincular la actividad de un usuario entre sesiones normales y privadas.
3. Lista allowCredentials prohibida: El array allowCredentials debe estar vacío. Esto evita que un sitio use esta función para comprobar si un usuario conocido específico está de visita.
4. Solo en contexto de origen (first-party): La función no está permitida en contextos de terceros (p. ej., un iframe de otro origen) para evitar el seguimiento entre sitios.

Estas mitigaciones aseguran que las garantías de seguridad fundamentales de WebAuthn permanezcan intactas. La ceremonia de autenticación en sí no cambia y sigue siendo resistente al phishing.

mediation: 'immediate' es una característica avanzada de la especificación WebAuthn Nivel 3, y su despliegue está en curso. A mediados de 2025, una estrategia de mejora progresiva es esencial.

Mientras que mediation: 'immediate' proporciona una gran herramienta de bajo nivel para un botón de inicio de sesión más inteligente, es importante distinguirla de una solución más amplia de "Passkey Intelligence", como la que ofrece Corbado. Ambas buscan resolver la paradoja de las passkeys y aumentar la adopción, pero lo hacen de diferentes maneras.

Passkey Intelligence va un paso más allá al recopilar y evaluar datos a lo largo del tiempo. Esto permite intervenciones de usuario más sofisticadas y oportunas. Por ejemplo, un backend de Passkey Intelligence puede detectar:

• Un usuario que se autentica con éxito con una contraseña en un nuevo dispositivo compatible con passkeys y le sugiere que añada una passkey para la próxima vez.
• Un usuario que completa un inicio de sesión "híbrido" entre dispositivos y sugiere inmediatamente que registre el nuevo dispositivo.
• Un usuario que no logra iniciar sesión en un nuevo dispositivo y ofrece la creación de passkeys como una opción de recuperación o configuración (reparación automática).

Este enfoque basado en datos es independiente del soporte del navegador para mediation: 'immediate', lo que significa que puede proporcionar un flujo de inicio de sesión más inteligente para todos tus usuarios, ahora mismo.

Lo mejor de ambos mundos

En última instancia, estos dos enfoques no son mutuamente excluyentes; son complementarios. La solución ideal los combina:

1. Usar un servicio de Passkey Intelligence como el cerebro de tu proceso de inicio de sesión.
2. El servicio puede entonces usar mediation: 'immediate' como una de sus señales en los navegadores compatibles para realizar una comprobación inicial rápida.
3. Basándose en el resultado —o en la falta de soporte para la función— el servicio de inteligencia puede usar sus datos históricos más ricos para organizar el fallback perfecto, ya sea mostrando un campo de contraseña u ofreciendo un aviso de creación de passkey justo a tiempo.

Al combinar la velocidad nativa de mediation: 'immediate' con la información profunda de un backend de Passkey Intelligence, puedes proporcionar la experiencia de inicio de sesión más fluida, adaptativa y efectiva posible, guiando suavemente a cada usuario hacia un futuro sin contraseñas.

La mediación inmediata es una gran mejora para la experiencia de inicio de sesión. Proporciona la inteligencia necesaria para eliminar puntos comunes de fricción y confusión para los usuarios durante la transición a las passkeys.

• Reduce la confusión del usuario: Al habilitar un único botón de "Iniciar sesión", la mediación immediate elimina la carga cognitiva para el usuario. Ya no tienen que recordar qué método de autenticación configuraron o elegir de una lista sobrecargada de opciones. El proceso de inicio de sesión se vuelve más simple e intuitivo.
• Evita los abandonos del inicio de sesión con passkey: Una razón común por la que los usuarios abandonan un inicio de sesión con passkey es la aparición inesperada de un código QR para un flujo entre dispositivos. Debido a que mediation: 'immediate' solo busca credenciales locales, evita este estado confuso por completo. En lugar de que el usuario abandone el flujo, la aplicación recibe una señal clara (NotAllowedError) para recurrir elegantemente a otro método, lo que resulta en un recorrido más fluido.
• Crea un flujo fluido e inteligente: El beneficio principal es una experiencia de inicio de sesión inteligente. La aplicación puede preguntar al navegador si un inicio de sesión con passkey fluido es posible antes de comprometerse con una UI. Este enfoque de "Preguntar, no imponer" asegura que los usuarios solo vean avisos que son relevantes para ellos. Hace que el inicio de sesión se sienta inteligente y adaptativo, reforzando la conveniencia de las passkeys y fomentando su uso continuado.

La mediación inmediata es una nueva función de WebAuthn que resuelve la experiencia de inicio de sesión fragmentada del período de transición a las passkeys. Permite la creación de un único botón inteligente de "Iniciar sesión" que se adapta al contexto del usuario, eliminando la confusión y la fricción. Aunque introduce una contrapartida de privacidad calculada, incluye salvaguardas robustas para mitigar los riesgos sin comprometer la seguridad fundamental de WebAuthn.

Para los desarrolladores, el camino a seguir es la mejora progresiva. Construir una experiencia base sólida y añadir la mediación immediate por encima para los navegadores compatibles. Adoptar esta característica es un movimiento estratégico para acelerar la adopción de passkeys, mejorar la seguridad, reducir los costos operativos y mejorar la conversión.

Implementar estos flujos de autenticación avanzados puede ser complejo. La plataforma de Passkey Empresarial de Corbado abstrae esta complejidad. Nuestra infraestructura se encarga de la orquestación óptima del flujo —incluyendo la mediación condicional e immediate— permitiendo a tu equipo desplegar una experiencia de autenticación de vanguardia y sin fricciones con confianza.