Capacidades de cliente de WebAuthn

Passkeys Cheat Sheet — dev-focused WebAuthn reference. Trusted by Ally, Stanford CS & more.

Get Cheat Sheet

WebAuthn es el estándar moderno detrás de las passkeys. En lugar de depender de las contraseñas tradicionales, utiliza criptografía de clave pública para que podamos autenticarnos con passkeys, que pueden incluir biometría (como huellas dactilares o reconocimiento facial) o llaves de seguridad físicas. Este cambio no solo mejora la seguridad, sino que también hace la experiencia mucho más cómoda al eliminar la necesidad de gestionar contraseñas.

El estándar WebAuthn Nivel 3 introduce nuevas capacidades de cliente (que podemos obtener a través de la API del navegador getClientCapabilities()). Su objetivo es darnos más control y flexibilidad al implementar passkeys. Estas actualizaciones simplifican la integración de passkeys en distintos dispositivos, navegadores y plataformas, asegurando un proceso más fluido y consistente para todos.

En este artículo, responderemos a las siguientes preguntas:

1. ¿Qué son las capacidades de cliente de WebAuthn?
2. ¿Cuáles son las capacidades de cliente que existen?
3. ¿Cómo mejoran estas capacidades la implementación de passkeys?
4. ¿Por qué son importantes tanto para desarrolladores como para product managers?

Al final, entenderás cómo estas funciones nos ayudan a crear flujos de autenticación seguros y sin fricciones que encajan perfectamente con lo que los usuarios esperan hoy en día.

Las capacidades de cliente de WebAuthn son un conjunto de funciones que permiten a los navegadores y plataformas comunicar qué tipo de herramientas WebAuthn soportan. En pocas palabras, funcionan como una "lista de características" que le dice a las páginas web qué métodos y configuraciones de autenticación están disponibles en el dispositivo del usuario. Esto nos permite adaptar los flujos de inicio de sesión según lo que el cliente pueda hacer, garantizando una experiencia más fluida y segura.

Por ejemplo, si un navegador indica que soporta autenticación biométrica (como Touch ID), podemos diseñar nuestro inicio de sesión para ofrecer la opción de entrar con la huella dactilar. Por el contrario, si el navegador no soporta ciertas funciones, podemos ofrecer alternativas, como una contraseña o un SMS OTP. En la práctica, si una función no está soportada o se interrumpe, el navegador podría mostrar un error genérico, por lo que es importante mapear estos resultados a una clasificación clara de errores de WebAuthn.

El estándar WebAuthn Nivel 3 trae varias capacidades nuevas que hacen que las implementaciones de passkeys sean más versátiles y fáciles de usar. El primer soporte para la llamada a la API getClientCapabilities() apareció en Safari 17.4.

Para detectar si el navegador lo soporta, este fragmento de código resulta muy útil:

// Check if PublicKeyCredential is supported in the current browser
if (typeof PublicKeyCredential === "undefined") {
    console.log("PublicKeyCredential is not supported in this browser.");
}
 
// Check if getClientCapabilities method exists on PublicKeyCredential
if (typeof PublicKeyCredential.getClientCapabilities === "function") {
    try {
        let capabilities = await PublicKeyCredential.getClientCapabilities();
        console.log(capabilities);
    } catch (error) {
        console.error("Error getting client capabilities:", error);
    }
} else {
    console.log("getClientCapabilities is not supported in this browser");
}

getClientCapabilities() permite que los sitios web y las aplicaciones consulten al cliente (por ejemplo, el navegador o el dispositivo) para saber qué funciones de WebAuthn soporta. Al conocer estas capacidades, podemos optimizar los flujos de autenticación para aprovechar las herramientas disponibles, como la autenticación biométrica, y ofrecer alternativas si alguna de ellas falta.

Subscribe to our Passkeys Substack for the latest news.

Subscribe

Veamos más de cerca cuáles son estas capacidades y cómo impactan en la integración de passkeys:

conditionalCreate permite la creación automática de passkeys bajo condiciones específicas. Una aplicación puede usar esto para crear una passkey automáticamente durante el autocompletado de contraseñas si el gestor de contraseñas lo soporta. Esta función ayuda a impulsar la adopción de passkeys y su uso posterior, facilitando la transición de contraseñas a passkeys de forma transparente.

Al igual que conditionalCreate, conditionalGet activa los inicios de sesión con passkeys de forma automática. Esto es ideal cuando queremos ofrecer la mejor experiencia de usuario, logrando que el inicio de sesión no solo sea sin contraseña, sino también sin nombre de usuario (la persona solo tiene que hacer clic en la passkey sugerida en un menú desplegable para autenticarse). Usando esta capacidad, nos aseguramos de que la autenticación con passkey solo aparezca cuando tenga sentido, evitando pantallas innecesarias.

hybridTransport asegura que las passkeys se puedan usar entre diferentes dispositivos (a través de códigos QR y Bluetooth). Por ejemplo, alguien podría usar una passkey guardada en su móvil para entrar a un servicio en su ordenador. Esto nos permite autenticarnos de forma segura sin tener que transferir passkeys manualmente ni depender de los métodos tradicionales en cada dispositivo, unificando la experiencia.

Los autenticadores de plataforma, como Windows Hello, Face ID o Touch ID, vienen integrados en los dispositivos y ofrecen una experiencia de passkey más rápida y segura, ya que nos permiten usar la biometría o métodos nativos del dispositivo (como un PIN o patrón).

userVerifyingPlatformAuthenticator garantiza que la autenticación con passkey incluya verificación de usuario, como escanear la huella o la cara, añadiendo así una capa extra de seguridad.

La capacidad relatedOrigins permite una autenticación fluida a través de diferentes dominios que pertenecen a la misma organización (por ejemplo, amazon.com y amazon.de). Si una empresa maneja varios dominios o subdominios, los usuarios pueden iniciar sesión una vez y acceder a todos los sitios sin tener que volver a autenticarse en cada uno. Esto reduce la fricción y es especialmente útil para grandes empresas con plataformas multiservicio o presencia internacional.

El método signalAllAcceptedCredentials(options) proporciona la lista completa de IDs de credenciales WebAuthn para un usuario. Es preferible usar este método en lugar de signalUnknownCredential() cuando el usuario ya ha iniciado sesión, ya que no hay riesgo de filtrar información privada. Nos da una visión completa de las credenciales de clave pública del usuario, incluyendo cambios recientes que tal vez no se hayan actualizado en los autenticadores conectados.

Veamos un ejemplo. Un usuario (userId: A) tiene 2 passkeys con IDs de credencial que en Base64URL equivalen a X e Y. Luego, el usuario elimina la passkey X en la configuración de su cuenta del servicio web (example.com), por lo que se borra la clave pública. Ahora, ejecutamos este fragmento:

PublicKeyCredential.signalAllAcceptedCredentials({
    rpId: "example.com",
    userId: "A", // WebAuthn User Handle, Base64URL.
    allAcceptedCredentialIds: ["Y"],
});

Si el autenticador está disponible al ejecutar el código, borrará u ocultará la passkey X para futuros intentos. Como es posible que el autenticador no esté conectado en ese momento, se recomienda ejecutar este código periódicamente, por ejemplo, en cada inicio de sesión.

Las passkeys que no estén en allAcceptedCredentialIds se eliminarán u ocultarán, posiblemente de forma irreversible. Por eso, debemos tener mucho cuidado de no quitar nunca IDs válidos de la lista. Si por error eliminamos un ID de credencial válido, debemos volver a incluirlo en otra llamada a signalAllAcceptedCredentials(options) lo antes posible para "desocultar" la passkey. Si la passkey no se ocultó sino que se borró por completo, ya no habrá mucho que hacer.

Experiment with passkey flows in the Passkeys Debugger.

Try for Free

El método signalCurrentUserDetails(options) informa del nombre actual del usuario y de su nombre a mostrar en WebAuthn. Al llamar a este método, el cliente sigue una serie de pasos definidos para actualizar la información.

Por ejemplo, si un usuario con ID de usuario WebAuthn A cambia su nombre en los ajustes de una web (example.com), podemos ejecutar:

PublicKeyCredential.signalCurrentUserDetails({
    rpId: "example.com",
    userId: "A", // user ID, Base64URL.
    name: "New user name",
    displayName: "New display name",
});

El autenticador actualizará entonces los metadatos de la passkey guardada localmente. La gran ventaja es que, en futuras solicitudes con Conditional UI o autocompletado de passkeys, el menú desplegable mostrará el nombre actualizado.

El método signalUnknownCredential(options) avisa de que un ID de credencial WebAuthn no es reconocido por el servicio (Relying Party), por ejemplo, si el usuario borró la passkey. A diferencia de signalAllAcceptedCredentials(options), este método no necesita la lista completa de credenciales válidas ni el User Handle, evitando así filtraciones de privacidad si se llama sin que el usuario haya iniciado sesión.

Por ejemplo, alguien borra una passkey con ID de credencial X en su cuenta de example.com (borrando la clave pública). Sin embargo, la clave privada sigue en su dispositivo. Esto significa que en futuros intentos de inicio de sesión con Conditional UI o autocompletado (con una lista allowCredentials vacía), esa passkey todavía se podrá seleccionar. El intento fallará porque la clave pública ya no existe, así que el servicio debería ejecutar:

PublicKeyCredential.signalUnknownCredential({
    rpId: "example.com",
    credentialId: "X", // credential ID the user just tried, Base64URL
});

Entonces, el autenticador borrará u ocultará la passkey con ID X para que no vuelva a aparecer.

Como el estándar WebAuthn Nivel 3 sigue siendo un borrador, la adopción de estas nuevas capacidades aún no es total. Los navegadores las van implementando poco a poco, pero el soporte varía. Aquí tienes un resumen actualizado:

La adopción se acelerará a medida que el Nivel 3 madure. Si quieres ver cuántos usuarios pueden aprovechar getClientCapabilities() ahora mismo, puedes revisar los datos reales en el State of Passkeys. Te recomendamos seguir las notas de lanzamiento de los navegadores para planificar una mayor compatibilidad.

See how many people actually use passkeys.

View Adoption Data

Como desarrollador, puede que te preguntes qué significa todo esto para ti y cómo deberías aplicarlo en tu app. Aquí tienes algunas recomendaciones prácticas.

Ten en cuenta que no todos los navegadores soportan todavía la API getClientCapabilities() (hasta noviembre de 2024). Hay un polyfill disponible aquí que puedes usar mientras los demás navegadores se actualizan.

Usa getClientCapabilities() al principio de tu código para detectar qué funciones soporta el cliente nada más cargar la página o iniciar el flujo de autenticación. Esto te permitirá personalizar la experiencia al vuelo, ofreciendo funciones de passkey que funcionen en ese dispositivo o navegador, impulsando la autenticación de plataforma cuando sea posible, o mostrando alternativas (como SMS OTP o llaves de seguridad físicas) cuando no lo sea.

Si estás añadiendo passkeys a una app que actualmente usa contraseñas, conditionalCreate puede ser un gran aliado para mejorar la adopción. En segundo plano, durante un autocompletado de contraseña con un gestor compatible (solo Apple Passwords hasta octubre de 2024), se genera automáticamente una passkey que será la opción preferida en el futuro.

Para conseguir una buena adopción y uso de las passkeys, comprueba siempre si el dispositivo soporta Conditional UI o autocompletado revisando conditionalGet. Así animarás a la gente a usar la passkey que acaban de crear, ya que el propio sistema operativo o navegador se la sugerirá de forma proactiva, requiriendo incluso menos esfuerzo que rellenar una contraseña.

Aprovecha hybridTransport para habilitar la autenticación entre dispositivos (vía código QR y Bluetooth). Esto permite que la gente inicie sesión cómodamente desde su smartphone, incluso si están accediendo a tu servicio desde su ordenador.

Las capacidades de cliente de WebAuthn suponen un gran avance para resolver las limitaciones actuales de las passkeys. En este artículo, hemos repasado los puntos clave:

1. ¿Qué son? Vimos cómo estas funciones permiten a los navegadores indicar qué soportan, dándonos más control sobre el inicio de sesión.
2. ¿Cuáles existen? Repasamos las nuevas funciones del estándar Nivel 3, como getClientCapabilities, conditionalCreate, hybridTransport, etc.
3. ¿Cómo mejoran la implementación? Hablamos de cómo facilitan la integración, el uso entre dispositivos y la seguridad.
4. ¿Por qué son importantes? Ayudan a crear experiencias seguras y sin fricciones que cumplen con lo que la gente espera hoy en día.

Te animamos a explorar las nuevas funciones de WebAuthn Nivel 3 y a mantenerte al día con su adopción en los distintos navegadores.

Llama a getClientCapabilities() al principio de la carga de tu página o flujo de autenticación para detectar de forma dinámica las funciones soportadas. Esto te permite ofrecer autenticación de plataforma cuando sea posible, o recurrir a alternativas como SMS OTP o llaves de seguridad físicas cuando no lo sea.

signalAllAcceptedCredentials requiere la lista completa de IDs de credenciales válidas y el User Handle, por lo que solo debe llamarse cuando el usuario está autenticado para evitar filtraciones de privacidad. signalUnknownCredential avisa sobre un único ID no reconocido sin necesidad de la lista completa, lo que lo hace seguro en escenarios sin autenticar, como después de un intento fallido de inicio de sesión.

La capacidad relatedOrigins permite una autenticación fluida entre diferentes dominios de la misma organización, por ejemplo amazon.com y amazon.de. La gente puede iniciar sesión una vez y acceder a todo sin volver a autenticarse en cada dominio, reduciendo la fricción en entornos internacionales o multiservicio.

Hasta noviembre de 2024, no todos los navegadores soportan getClientCapabilities(), así que puedes usar el polyfill disponible en github.com/MasterKale/webauthn-polyfills como solución temporal. Se espera que la adopción se acelere a medida que madure el estándar WebAuthn Nivel 3; de hecho, Chrome 133, Edge 133, Firefox 135 y Safari 17.4 ya lo soportan.

Acerca de Corbado

Corbado es la Passkey Intelligence Platform para equipos de CIAM que gestionan autenticación de consumidores a gran escala. Te ayudamos a ver lo que los logs de tu IDP y las herramientas de analytics genéricas no muestran: qué dispositivos, versiones de SO, navegadores y gestores de credenciales soportan passkeys, por qué los registros no se convierten en inicios de sesión, dónde falla el flujo de WebAuthn y cuándo una actualización de SO o navegador rompe el login en silencio — todo sin reemplazar Okta, Auth0, Ping, Cognito o tu IDP propio. Dos productos: Corbado Observe aporta observabilidad para passkeys y cualquier otro método de login. Corbado Connect añade passkeys gestionados con analytics integrado (junto a tu IDP). VicRoads ejecuta passkeys para más de 5M de usuarios con Corbado (+80 % de activación de passkey). Habla con un experto en Passkeys →