Prueba de origen: Mediación inmediata de WebAuthn para un acceso sin problemas

José Luis Zapata

Fecha de publicación: 19 de agosto de 2025

La mediación inmediata de WebAuthn es una nueva capacidad web diseñada para optimizar los flujos de acceso del usuario. En esta prueba de origen, se proporciona una descripción general de la función, sus beneficios y los detalles de implementación, y se te invita a participar y ayudar a definir el futuro de la autenticación web.

Fondo

La autenticación en la Web suele generar fricción y complicar el acceso de los usuarios. Los flujos de WebAuthn existentes, si bien son potentes, tienen problemas con los botones de "Acceder", especialmente cuando las credenciales no están disponibles de inmediato, lo que genera alternativas de formularios estándar.

Ejemplo de flujo de mediación inmediata

Esta nueva función presenta un flujo de acceso sin complicaciones, similar a las APIs de preferImmediatelyAvailableCredentials en dispositivos móviles. Simplifica el acceso, a menudo antes de los formularios de acceso estándar, ya que reduce las dificultades y mejora la experiencia del usuario.

Cómo funciona

La mediación inmediata de WebAuthn permite una experiencia de acceso más directa y eficiente. Permite que el navegador ofrezca credenciales disponibles al instante o que indique de inmediato su ausencia sin solicitar la autenticación con llave de seguridad o entre dispositivos, lo que simplifica la implementación para los desarrolladores.

El tipo de mediación immediate

Presentamos un tipo de mediación immediate para las solicitudes de navigator.credentials.get(). Cuando se establece esta opción, la promesa se rechaza con NotAllowedError si no se encuentran credenciales disponibles de forma local. Si hay credenciales, el navegador controla el proceso de autenticación de forma normal.

Esta flexibilidad permite que los sitios adapten su flujo de acceso y proporcionen métodos alternativos de forma correcta cuando no hay credenciales disponibles de inmediato.

Es importante destacar que los navegadores aún pueden devolver NotAllowedError para proteger la privacidad y la seguridad de los usuarios, y evitar problemas como la huella digital o el seguimiento.

Detección de características

Puedes detectar si la mediación inmediata está disponible con PublicKeyCredential.getClientCapabilities(). Los desarrolladores pueden verificar la capacidad immediateGet en el objeto capabilities que se devolvió.

async function checkImmediateMediationAvailability() {
  try {
    const capabilities = await PublicKeyCredential.getClientCapabilities();
    if (capabilities.immediateGet && window.PasswordCredential) {
      console.log("Immediate Mediation with passwords supported.");
    } else if (capabilities.immediateGet) {
      console.log("Immediate Mediation without passwords supported.");
    } else { console.log("Immediate Mediation unsupported."); }
  } catch (error) {
    console.error("Error getting client capabilities:", error);
  }
}

Nota: Para ayudar con una mayor compatibilidad del navegador, hay un polyfill para getClientCapabilities() disponible en el repositorio de GitHub de polyfills de WebAuthn.

Ejemplo de implementación

Para usar la API, llama a navigator.credentials.get() con mediation: 'immediate'. Te recomendamos que incluyas password: true en la solicitud, ya que es probable que la mayoría de los usuarios tengan una contraseña guardada y puedan beneficiarse de esta experiencia de inmediato.

button.addEventListener('click', async (event) => {
  event.preventDefault();
  event.stopPropagation();
  const cred = await navigator.credentials.get({
    password: true,
    publicKey: {
      challenge, // Your server-generated challenge
      rpId: 'example.com' // Your Relying Party ID
    },
    mediation: 'immediate',
  });
});

Los desarrolladores deben controlar el NotAllowedError en un bloque catch para proporcionar una experiencia de acceso alternativa correcta.

Flujo paso a paso para la mediación inmediata

La mediación inmediata de WebAuthn admite dos casos de uso principales para optimizar el acceso del usuario: habilitar un botón dedicado "Acceder con llave de acceso" que suprime las opciones de resguardo no deseadas y facilitar un flujo de acceso dinámico que ofrece credenciales de forma proactiva antes de una acción crítica para el usuario.

Caso de uso 1: Acceso explícito con el botón de acceso

En este caso, se proporciona un botón de acceso exclusivo, lo que garantiza una experiencia del usuario limpia sin mensajes inesperados ni la necesidad de pasar por una página de acceso.

Flujo que muestra que Chrome ofrece credenciales ya guardadas cuando el usuario hace clic en el botón de acceso.
  1. El usuario inicia el acceso: El usuario hace clic en un botón "Acceder". Luego, la parte que confía llama a navigator.credentials.get() con mediation: "immediate".
  2. El navegador solicita la selección de credenciales (si están disponibles): El navegador verifica si hay llaves de acceso disponibles localmente o contraseñas solicitadas. Si encuentra alguna, inmediatamente presenta una IU modal para que el usuario elija una cuenta. Las cuentas se clasifican por la marca de tiempo del último uso y, luego, alfabéticamente. Nota: Si se encuentran contraseñas y llaves de acceso de varios administradores de contraseñas para la misma cuenta, el navegador prioriza las llaves de acceso. Cuando existen varias llaves de acceso para la misma cuenta de diferentes proveedores, se prioriza la última llave de acceso que se usó.
  3. Acceso exitoso: El usuario selecciona la llave de acceso en la IU del navegador. Si el navegador requiere verificación, le pedirá al usuario que verifique su identidad con el método que configuró anteriormente (como un PIN, un ingreso biométrico o un patrón). El acceso se completa correctamente.
  4. Ruta de resguardo: Sin llave de acceso o rechazo del usuario: Si no hay llaves de acceso locales o contraseñas solicitadas disponibles para el sitio, o si el usuario rechaza la IU del navegador, este arroja un NotAllowedError a la parte que confía, y no muestra ninguna IU para las opciones de llave de seguridad o entre dispositivos. Luego, la parte que confía puede continuar con su página de acceso estándar o ofrecer mecanismos de autenticación alternativos.

Caso de uso 2: Flujo de acceso implícito antes de una acción del usuario

Este escenario permite una experiencia de acceso proactiva, ya que ofrece llaves de acceso y contraseñas antes de que el usuario realice una acción que requiera un estado autenticado, como finalizar la compra.

Flujo que muestra que Chrome ofrece credenciales ya guardadas cuando el usuario realiza una acción que requiere que acceda.
  1. El usuario inicia una acción que requiere acceso: El usuario hace clic en un botón para realizar una acción que requiere que haya accedido (por ejemplo, un botón "Finalizar compra"). Luego, la parte que confía llama a navigator.credentials.get() con mediation: "immediate".

  2. El navegador solicita la selección de credenciales (si están disponibles): El navegador verifica si hay llaves de acceso o contraseñas disponibles de forma local. Si las encuentra, muestra de inmediato una IU modal para que el usuario elija una cuenta. Las cuentas se clasifican por la marca de tiempo del último uso, luego, alfabéticamente, y se eliminan los duplicados para mostrar una sola entrada por cuenta. Nota: Cuando se encuentran contraseñas y llaves de acceso de varios administradores de contraseñas para la misma cuenta, el navegador prioriza las llaves de acceso. Cuando existen varias llaves de acceso para la misma cuenta de diferentes proveedores, se prioriza la última llave de acceso que se usó.

  3. Acceso exitoso: El usuario selecciona una credencial en la IU del navegador. Si el navegador requiere verificación, le pedirá al usuario que verifique su identidad con el método que configuró anteriormente (como un PIN, un ingreso biométrico o un patrón). El acceso se completa correctamente.

  4. Ruta de resguardo: Sin credenciales o si el usuario descarta la IU: Si no hay credenciales locales disponibles para el sitio o si el usuario descarta la IU del navegador, este arroja un NotAllowedError a la parte que confía y no muestra ninguna IU. La experiencia de acceso del usuario no cambiará. Luego, la parte que confía puede pedirle al usuario más detalles (por ejemplo, su dirección de correo electrónico) o mostrar mecanismos de autenticación alternativos, como un formulario de contraseña, una verificación por SMS o una solicitud modal de WebAuthn que admita autenticadores multidispositivo.

Beneficios

La mediación inmediata de WebAuthn ofrece varias ventajas clave para los desarrolladores y los usuarios:

  • Acceso sin inconvenientes: Proporciona una experiencia de acceso más fluida y con menos inconvenientes para los usuarios que tienen llaves de acceso o contraseñas disponibles de inmediato guardadas en su navegador o administrador de contraseñas.
  • Acceso inteligente: La API habilita un flujo de acceso cuando el usuario desea realizar actividades que requieren que acceda a su cuenta. Estos se adaptan de forma inteligente al estado de las credenciales del usuario. Ofrece autenticación inmediata cuando es posible, lo que evita redireccionamientos innecesarios y optimiza el flujo.
  • Administración de credenciales mejorada: Cuando varios administradores de contraseñas ofrecen credenciales para la misma cuenta, el navegador selecciona de forma inteligente la opción más adecuada, lo que simplifica la administración de credenciales para los usuarios.
  • Menos confusión para el usuario: Al presentar las credenciales conocidas directamente, la función minimiza la confusión del usuario que suele asociarse con varias opciones de acceso o formularios estándar.
  • Respaldo fluido: Garantiza un respaldo fluido a las páginas de acceso estándar para los usuarios sin credenciales inmediatas, lo que significa que su experiencia no cambia con respecto a los flujos actuales.

Privacidad y seguridad

La mediación inmediata de WebAuthn permite que los sitios identifiquen la presencia de credenciales disponibles de inmediato antes de que un usuario autorice explícitamente un intento de acceso. Para proteger la privacidad del usuario y evitar posibles usos inadecuados, implementamos varias medidas fundamentales:

  • Requisito de gesto del usuario: La llamada a la API requiere un gesto del usuario (cualquier activación transitoria del usuario). Esto dificulta que los sitios realicen sondeos y tomas de huellas digitales silenciosos.
  • Sesiones privadas y de incógnito: En las sesiones privadas o de incógnito, cualquier solicitud de mediación inmediata arroja NotAllowedError.
  • Restricciones en las listas de allowCredentials: Las solicitudes que usan listas de allowCredentials arrojan NotAllowedError. Esto evita que los sitios infieran el historial de interacción del usuario o realicen un seguimiento de los usuarios en diferentes sesiones.
  • Cancelación: No es válido establecer el parámetro signal en una solicitud con mediación inmediata. Esto evita que los sitios descarten de forma programática cualquier IU del navegador.

Probar

Te recomendamos que experimentes con la mediación inmediata de WebAuthn.

Estado en Chrome

Esta función está avanzando en el ciclo de desarrollo de Chromium:

  • Escritorio: Prueba para desarrolladores en Chrome 136, con una prueba de origen de Chrome 139 a 141.
  • Android: Versión de prueba para desarrolladores en Chrome 140.

Para pruebas locales

Para probar la mediación inmediata de WebAuthn de forma local, haz lo siguiente:

  1. Descarga Chrome 139: Obtén y abre la versión más reciente de Chrome en tu computadora.
  2. Habilita la marca de mediación inmediata: Navega a chrome://flags/#web-authentication-immediate-get en la barra de direcciones y habilita la marca "Web Authentication Immediate Get".
  3. Prepara las credenciales: Asegúrate de tener llaves de acceso y contraseñas utilizables guardadas:
    • Contraseñas guardadas en el Administrador de contraseñas de Google
    • Llaves de acceso guardadas en el Administrador de contraseñas de Google (requiere acceder y sincronizar Chrome con una Cuenta de Google), Windows Hello o Llavero de iCloud

Para pruebas públicas (prueba de origen)

Para probar la mediación inmediata de WebAuthn con la prueba de origen en un entorno público, haz lo siguiente:

  1. Regístrate: Visita la página de pruebas de origen de Chrome y regístrate en la prueba"WebAuthn immediate mediation".
  2. Agrega el token a los encabezados HTTP: Incluye el token de prueba de origen proporcionado en los encabezados HTTP de tu sitio: HTML Origin-Trial: [YOUR_TRIAL_TOKEN]

Nota: También puedes proporcionar tus tokens de forma programática con JavaScript.

Situaciones de prueba

Proporcionamos una implementación de referencia y te recomendamos que compiles tu propio prototipo para probar diferentes situaciones.

  • Demostración de referencia: Puedes probar la implementación de referencia en https://deephand.github.io/webauthn-immediate-demo/.
    • Implementa un prototipo: Cuando implementes un prototipo en tu sitio, asegúrate de realizar la llamada navigator.credentials.get() con mediation: 'immediate' después de que el usuario haga clic (por ejemplo, en un botón "Acceder" o en cualquier interacción que requiera que el usuario haya accedido).
  • Flujo 1: Acceso sin contraseña ni llave de acceso: Si no tienes contraseñas ni llaves de acceso disponibles para el sitio, hacer clic en "Acceder" te lleva directamente a la página de acceso estándar, sin que aparezca la IU del navegador.
  • Flujo 2: Accede con una llave de acceso local disponible de inmediato: Si tienes una llave de acceso guardada para el sitio, hacer clic en "Acceder" debería activar la IU de mediación inmediata, que ofrece la llave de acceso para su selección.
  • Flujo 3: Accede con una llave de acceso o contraseña local: Si tienes guardadas llaves de acceso y contraseñas, habilita la opción "Solicitar contraseña" (estableciendo password: true en tu código). Cuando hagas clic en "Acceder", deberían aparecer las opciones de llave de acceso y contraseña en la IU de mediación inmediata.