Sugerencias de credenciales de clave pública de WebAuthn / Sugerencias de User-Agent

WebAuthn y las passkeys están ganando un fuerte impulso y cada vez más adopción. Además, desde un punto de vista técnico, el estándar WebAuthn está evolucionando rápidamente. Las sugerencias de credenciales de clave pública de WebAuthn (también llamadas User-Agent Hints) son la última incorporación a la API de autenticación web, con el objetivo de mejorar la forma en que los desarrolladores implementan la autenticación con passkeys en sus aplicaciones.

En este artículo, responderemos las siguientes preguntas:

• ¿Qué son las sugerencias de credenciales de clave pública de WebAuthn?
• ¿Por qué necesitamos las sugerencias de credenciales de clave pública de WebAuthn?
• ¿Cómo funcionan las sugerencias de credenciales de clave pública de WebAuthn?
• ¿Cuáles son las limitaciones y los casos recomendados para usar las sugerencias de credenciales de clave pública de WebAuthn en nuestros proyectos?

Comencemos por analizar primero la motivación.

Hoy en día, existen diferentes lugares donde podemos crear y almacenar una passkey:

• Gestores de contraseñas de terceros (password manager) (p. ej., 1Password, Dashlane, Bitwarden, KeePassXC)
• Administrador de contraseñas de Google / Perfil de Chrome
• Llavero de iCloud / Contraseñas de Apple
• Windows Hello
• Otro smartphone (iOS, Android) o tablet (iPadOS, Android)
• Llave de seguridad de hardware (security key) (p. ej., YubiKey)

Para el usuario, esto puede ofrecer flexibilidad y libertad de elección. Sin embargo, algunas aplicaciones y escenarios requieren restringir algunas de estas opciones, por ejemplo, si queremos permitir únicamente llaves de seguridad de hardware debido a mayores requisitos de seguridad.

Para influir en esa creación y almacenamiento de passkeys, teníamos la propiedad authenticatorAttachment.

Subscribe to our Passkeys Substack for the latest news.

Subscribe

authenticatorAttachment permite a las relying parties restringir dónde se puede crear la passkey.

platform indica un autenticador que está integrado en el dispositivo que ejecuta WebAuthn. WebAuthn se comunica con él utilizando métodos de transporte específicos de esa plataforma, como las API específicas de la plataforma. Una credencial de clave pública vinculada a un autenticador de plataforma se denomina credencial de plataforma. De la lista anterior, los siguientes gestores de credenciales / ubicaciones podrían almacenar credenciales de plataforma:

• Gestores de contraseñas de terceros (password manager) (p. ej., 1Password, Dashlane, Bitwarden, KeePassXC)
• Administrador de contraseñas de Google / Perfil de Chrome
• Llavero de iCloud / Contraseñas de Apple
• Windows Hello

Windows 11 y Chrome:

macOS 15 (Sequoia) y Chrome:

Al hacer clic en Cancelar, aparece el siguiente modal:

macOS 15 (Sequoia) y Safari:

cross-platform indica un autenticador que es externo al dispositivo que ejecuta WebAuthn (autenticador itinerante) porque se puede usar en múltiples dispositivos. WebAuthn interactúa con él utilizando protocolos de transporte multiplataforma como Bluetooth o NFC. Una credencial de clave pública asociada con un autenticador itinerante se denomina credencial itinerante. De la lista anterior, los siguientes gestores de credenciales / ubicaciones podrían almacenar credenciales multiplataforma:

• Otro smartphone (iOS, Android) o tablet (iPadOS, Android)
• Llave de seguridad de hardware (security key) (p. ej., YubiKey)

Windows 11 y Chrome:

macOS 15 (Sequoia) y Chrome:

macOS 15 (Sequoia) y Safari:

Sin especificar indica que se puede usar tanto un autenticador de plataforma como un autenticador multiplataforma. Aquí, el usuario puede elegir dónde le gustaría almacenar las passkeys.

Windows 11 y Chrome:

macOS 15 (Sequoia) y Chrome:

macOS 15 (Sequoia) y Safari:

Al hacer clic en Cancelar, aparece el siguiente modal:

authenticatorAttachment se usó durante bastante tiempo. Sin embargo, también era inflexible con respecto a nuevos desarrollos como la autenticación entre dispositivos (a través de códigos QR y Bluetooth). En este caso, una passkey también se almacena, por ejemplo, en el Administrador de contraseñas de Google (credencial de plataforma), pero la relying party la activa con cross-platform. Además de eso, el control de una relying party para influir en el tipo de passkey que se debe usar en una ceremonia de inicio de sesión (no de registro) solo se podía realizar modificando el valor transports de una credencial.

Ahí es donde entran en juego las sugerencias de credenciales de clave pública de WebAuthn.

Become part of our Passkeys Community for updates & support.

Join

Las sugerencias de credenciales de clave pública de WebAuthn son un nuevo parámetro introducido en la API de autenticación web (oficialmente en WebAuthn Level 3). Proporcionan una guía a los navegadores sobre el tipo de autenticador que un usuario probablemente usará durante el proceso de autenticación. Esto ayuda a ofrecer una experiencia de usuario más ágil e intuitiva al enfocar la interfaz de usuario del navegador en las opciones más relevantes.

Los tres tipos de sugerencias

Las sugerencias vienen en tres tipos:

1. security-key: Indica que se espera que el usuario use una llave de seguridad de hardware (p. ej., YubiKey).
2. client-device: Sugiere que el usuario usará un autenticador de plataforma adjunto al dispositivo cliente (como Touch ID en macOS, Face ID en iOS o Windows Hello en Windows).
3. hybrid: Implica que el usuario podría usar un smartphone o tablet para la autenticación entre dispositivos a través de un código QR y Bluetooth.

Estas sugerencias no son requisitos estrictos de la relying party, sino que sirven como guía para mejorar la experiencia del usuario como pistas para el navegador.

A continuación, se muestran capturas de pantalla para macOS Sequoia (Edge + Chrome) y Windows 10 (Chrome) con authenticatorAttachment no especificado y la sugerencia de User-agent de WebAuthn establecida en security-key.

Aquí vemos otra limitación: la sugerencia security-key no se respeta en Windows 10, al menos no directamente. El flujo es básicamente el mismo que para la sugerencia client-device.

Al hacer clic en Cancelar, aparece el siguiente modal:

A continuación, se muestran capturas de pantalla para macOS Sequoia (Edge + Chrome) y Windows 10 (Chrome) con authenticatorAttachment no especificado y la sugerencia de User-agent de WebAuthn establecida en client-device.

Al hacer clic en Cancelar, aparece el siguiente modal:

Al hacer clic en Cancelar, aparece el siguiente modal:

Al hacer clic en Cancelar, aparece el siguiente modal:

A continuación, se muestran capturas de pantalla para macOS Sequoia (Edge + Chrome) y Windows 10 (Chrome) con authenticatorAttachment no especificado y la sugerencia de User-agent de WebAuthn establecida en hybrid.

Con la introducción de las sugerencias, los desarrolladores ahora pueden proporcionar un array de preferencias en orden de prioridad decreciente, ofreciendo más flexibilidad.

El siguiente fragmento de código le dice al navegador que es probable que el usuario se autentique usando una llave de seguridad de hardware, enfocando la interfaz de usuario en consecuencia.

Para compatibilidad con user agents más antiguos, cuando esta sugerencia se usa en PublicKeyCredentialCreationOptions, el authenticatorAttachment debe establecerse en cross-platform.

const credential = await navigator.credentials.create({
  publicKey: {
    challenge: /* your challenge here */,
    hints: ['security-key'],
    authenticatorSelection: {
      authenticatorAttachment: 'cross-platform'
    }
  }
});

La sugerencia security es particularmente valiosa en casos de alta seguridad donde el sitio web / relying party solo quiere permitir llaves de seguridad de hardware y empuja al usuario en esa dirección.

En este ejemplo, la sugerencia indica que el usuario podría usar el autenticador de plataforma integrado del dispositivo actual.

Para compatibilidad con user agents más antiguos, cuando esta sugerencia se usa en PublicKeyCredentialCreationOptions, el authenticatorAttachment debe establecerse en platform.

const credential = await navigator.credentials.create({
  publicKey: {
    challenge: /* your challenge here */,
    residentKey: true,
    hints: ['client-device'],
    authenticatorSelection: {
      authenticatorAttachment: 'platform'
    }
  }
});

Establecer la sugerencia client-device es beneficioso si hay varias passkeys asociadas a una cuenta de usuario y algunas de ellas podrían estar disponibles en el dispositivo que inicia sesión, mientras que otras están almacenadas en dispositivos diferentes. Si el sistema (inteligencia de passkeys) detecta que el usuario que intenta iniciar sesión tiene con alta probabilidad una passkey local disponible, entonces esta sugerencia se puede establecer en las PublicKeyCredentialRequestOptions, ahorrándole al usuario un clic para seleccionar la passkey correcta.

En este ejemplo, la sugerencia indica que el usuario podría usar un smartphone o un dispositivo similar para la autenticación.

Para compatibilidad con user agents más antiguos, cuando esta sugerencia se usa en PublicKeyCredentialCreationOptions, el authenticatorAttachment debe establecerse en cross-platform.

const credential = await navigator.credentials.create({
  publicKey: {
    challenge: /* your challenge here */,
    residentKey: true,
    hints: ['hybrid'],
    authenticatorSelection: {
      authenticatorAttachment: 'cross-platform'
    }
  }
});

La sugerencia hybrid puede ser útil si el usuario tiene varias llaves y el sistema (inteligencia de passkeys) detecta que en el dispositivo actual probablemente no hay una passkey local disponible. Para mejorar la experiencia de usuario y ahorrar un clic, podemos establecer esta sugerencia de User-agent de WebAuthn y solicitar directamente al usuario la autenticación entre dispositivos (a través de código QR y Bluetooth). Además, si intentamos construir un sistema de passkeys mobile-first, entonces establecer esta sugerencia tiene mucho sentido.

Para experimentar con las diferentes opciones, recomendamos echar un vistazo al Passkeys Debugger.

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

Try for Free

Es crucial entender cómo las sugerencias de credenciales de clave pública de WebAuthn interactúan con otros parámetros de WebAuthn como authenticatorAttachment y credential transports.

En primer lugar, es importante tener en cuenta que estas sugerencias no son requisitos estrictos. No vinculan al user-agent (navegador), sino que sirven como guía para proporcionar la mejor experiencia aprovechando la información contextual que tenemos sobre la solicitud. Esto significa que los navegadores pueden optar por considerar las sugerencias, pero no están obligados a seguirlas estrictamente.

Las sugerencias se proporcionan como un array en orden de preferencia decreciente. Este orden determina cómo el navegador debe priorizarlas:

• La primera sugerencia tiene prioridad: Si dos sugerencias son contradictorias, el navegador da prioridad a la primera.
• Sugerencias superpuestas: Si una sugerencia más específica podría no ser reconocida por todos los navegadores, podemos incluir otras menos específicas después para una compatibilidad más amplia.
• Sugerencias duplicadas: Si la misma sugerencia aparece más de una vez, cualquier aparición posterior se ignora.

Ejemplo:

hints: ['security-key', 'hybrid', 'client-device']

En este array:

1. El navegador prioriza primero security-key.
2. Si no es aplicable, considera hybrid.
3. Por último, examina client-device (autenticadores de plataforma en el dispositivo cliente).

Las sugerencias pueden contradecir la información contenida en authenticatorAttachment y credential transports. Cuando esto ocurre, las sugerencias tienen prioridad. Esto ofrece más flexibilidad en comparación con el uso estricto anterior de authenticatorAttachment, que limitaba el autenticador a platform o cross-platform.

Ejemplo con parámetros contradictorios:

const credential = await navigator.credentials.create({
  publicKey: {
    challenge: /* your challenge here */,
    hints: ['hybrid'],
    authenticatorSelection: {
      authenticatorAttachment: 'platform' // Contradice la sugerencia
    }
  }
});

En este caso:

• Sugerencia: Indica una preferencia por autenticadores híbridos.
• authenticatorAttachment: Especifica platform, que normalmente limita los autenticadores al dispositivo cliente.
• Resultado: El navegador prioriza la sugerencia sobre authenticatorAttachment, centrándose en las opciones híbridas.

Actualmente, las sugerencias de credenciales de clave pública de WebAuthn solo están disponibles en Chrome (desde la versión 128). A día de hoy, Edge y Safari han indicado planes para integrar esta función, mientras que Firefox aún no ha confirmado su calendario de lanzamiento.

Es importante recordar que en Chrome, el parámetro authenticatorAttachment sigue siendo respetado por ahora. Esto significa que hoy en día el authenticatorAttachment es el factor decisivo, sin importar qué sugerencia se establezca. Sin embargo, esperamos que en futuras versiones de Chrome, las sugerencias de credenciales de clave pública se conviertan en el enfoque preferido y único.

Aunque la última versión de Chrome soporta las sugerencias de User-Agent de WebAuthn, estas sugerencias no son respetadas por Windows 11 y Windows Hello / Seguridad de Windows. La razón subyacente es que la interfaz de usuario está controlada por el propio sistema operativo (Windows Hello / Seguridad de Windows).

Además, para una passkey que está almacenada en el Administrador de contraseñas de Google y sincronizada con Windows 11, las sugerencias de User-Agent de WebAuthn no se respetan, ya que la autenticación local final en Windows 11 ocurre con Windows Hello / Seguridad de Windows. Con la próxima sincronización de passkeys en Windows 11 a través de cuentas de Microsoft, también esperamos mejoras para Windows 11 y las sugerencias de User-Agent de WebAuthn.

Sin embargo, en Windows 10, las sugerencias de User-Agent de WebAuthn sí se respetan, ya que la interfaz de usuario de WebAuthn es manejada por Chrome y no por Windows Hello / Seguridad de Windows. No obstante, durante nuestras pruebas, no vimos un efecto para security-key. Cuando se estableció esta sugerencia, el flujo se parecía al de client-device.

Las sugerencias de credenciales de clave pública de WebAuthn (user-agent) aportan una serie de beneficios tanto para los desarrolladores como para los usuarios. La función aún es nueva y todavía no se ha implementado en todos los navegadores y sistemas operativos (a fecha de octubre de 2024).

Es importante ser consciente de las limitaciones actuales que vienen especialmente con Windows 11. En Windows 11, la interfaz de usuario de passkeys es manejada por Windows Hello (el modal de seguridad de Windows Hello) y esto actualmente prevalece sobre el soporte de Chrome / Edge para las sugerencias de User-Agent de WebAuthn. Esto también se aplica a las passkeys que se sincronizan desde el Administrador de contraseñas de Google a Windows (aquí, las sugerencias tampoco tienen efecto todavía).

Esto significa que las sugerencias de credenciales de clave pública de WebAuthn realmente solo funcionan en macOS y Windows 10 (de los principales sistemas operativos de escritorio).

Además, a fecha de octubre de 2024, incluso si se usa Chrome / Edge en estos sistemas operativos, si se establece el authenticatorAttachment, este también prevalece sobre las sugerencias de User-Agent de WebAuthn (como afirma Google).

Desde la perspectiva de los casos de uso, vemos los siguientes casos de uso recomendados para obtener el máximo valor de esta nueva función.

Al construir nuestro backend y la inteligencia de passkeys, podemos incluir el uso correcto de las sugerencias de credenciales de clave pública para facilitar el inicio de sesión y ahorrarle al usuario clics innecesarios. Por ejemplo, si nuestro sistema detecta que un usuario inicia sesión en un dispositivo donde probablemente hay una passkey local disponible, usamos la sugerencia client-device.

Si el usuario accede al sitio web desde un nuevo dispositivo y nuestra inteligencia de passkeys sabe que una passkey podría estar disponible en un dispositivo móvil del usuario, establecemos la sugerencia en hybrid, para que el usuario pueda escanear rápidamente el código QR y hacer uso de la passkey híbrida.

El objetivo principal aquí es proporcionar una experiencia de usuario más fluida e intuitiva. Al guiar a los navegadores sobre qué autenticadores es probable que se usen, los desarrolladores pueden reducir la confusión y la fricción del usuario durante el proceso de inicio de sesión. En lugar de que los usuarios se sientan abrumados con opciones de autenticación innecesarias, las sugerencias permiten a los navegadores centrarse en las opciones más relevantes, lo que conduce a una experiencia más rápida y directa.

Las empresas de alta seguridad o las organizaciones gubernamentales que han estandarizado el uso de llaves de seguridad de hardware para la autenticación de usuarios encontrarán las sugerencias de credenciales de passkey particularmente útiles. Al usar la sugerencia security-key, pueden asegurarse de que los navegadores muestren de manera prominente la opción de la llave de seguridad de hardware.

Esto es especialmente útil para grandes organizaciones donde a los empleados se les han entregado llaves de seguridad de hardware y donde no se permiten otros métodos de autenticación (como los autenticadores de plataforma). La sugerencia security-key permite a las empresas restringir sus flujos de autenticación sin limitar su flexibilidad para futuras mejoras.

La sugerencia hybrid brilla en escenarios donde se desea la autenticación entre dispositivos y, por lo tanto, un enfoque mobile-first, o cuando los usuarios se mueven con frecuencia entre dispositivos o plataformas.

Un ejemplo de este caso de uso sería una aplicación orientada al consumidor que anticipa que la mayoría de sus usuarios usarán sus smartphones para la autenticación, ya sea a través de métodos biométricos o aplicaciones de autenticación basadas en la web (passkeys mobile-first). Al especificar hybrid como sugerencia, los desarrolladores se aseguran de que la interfaz de usuario del navegador fomente el uso del smartphone, mejorando la comodidad y la accesibilidad.

Las sugerencias de credenciales de clave pública de WebAuthn ofrecen una forma flexible de mejorar la experiencia del usuario durante la autenticación con passkeys. Repasemos las preguntas de la introducción con los conocimientos que hemos adquirido:

1. ¿Qué son las sugerencias de credenciales de clave pública de WebAuthn?

   Son sugerencias opcionales proporcionadas por el sitio web o la aplicación para guiar a los clientes sobre el método de autenticación más probable que usará un usuario, ya sea una llave de seguridad de hardware, un autenticador de plataforma o una solución híbrida como la autenticación entre dispositivos.

2. ¿Por qué necesitamos las sugerencias de credenciales de clave pública de WebAuthn?

   Simplifican el proceso de autenticación al reducir las opciones presentadas a los usuarios, disminuyendo la fricción o los clics innecesarios y mejorando la experiencia general.

3. ¿Cómo funcionan las sugerencias de credenciales de clave pública de WebAuthn?

   Los desarrolladores especifican sugerencias como security-key, client-device o hybrid según el contexto, lo que permite a los navegadores priorizar el método de autenticación relevante para el usuario. Si bien estas sugerencias no son requisitos estrictos, ayudan a optimizar el flujo de la interfaz de usuario durante la autenticación.

4. ¿Cuáles son las limitaciones y los casos de uso recomendados?

   Actualmente, el soporte completo para estas sugerencias se limita a Chrome y Edge, con otros navegadores y sistemas operativos como Windows 11 mostrando niveles variables de compatibilidad. Los casos de uso más efectivos incluyen mejorar la experiencia de inicio de sesión, hacer cumplir el uso de llaves de seguridad de hardware en entornos de alta seguridad y habilitar la autenticación entre dispositivos en aplicaciones mobile-first.

En conclusión, las sugerencias de credenciales de clave pública de WebAuthn permiten a los desarrolladores crear procesos de autenticación más intuitivos y amigables para el usuario al guiar a los navegadores hacia las opciones más apropiadas para cada escenario de usuario. Aunque todavía está en evolución, esta función puede mejorar significativamente tanto la seguridad como la experiencia del usuario en las implementaciones de passkeys.