API Signal de WebAuthn: Actualizar y eliminar passkeys en el lado del cliente

Looking for a dev-focused passkey reference? Download our Passkeys Cheat Sheet. Trusted by dev teams at Ally, Stanford CS & more.

Get Cheat Sheet

Última actualización: 4 de noviembre de 2025

Un resumen rápido del soporte de la API Signal de WebAuthn en diferentes plataformas:

⚠️ Problema conocido: Safari 26+ tiene un error donde la promesa no se resuelve correctamente (WebKit Bug #298951). Corrección pendiente de fusión.

El ecosistema de las passkeys está evolucionando. Para facilitar el cambio, el estándar subyacente WebAuthn avanza rápidamente. Las nuevas características suelen comenzar con una explicación técnica en GitHub y luego evolucionan hacia un pull request en el estándar una vez que se han discutido lo suficiente. Recientemente, este pull request se añadió al borrador del estándar como la API Signal de WebAuthn. En este artículo, cubriremos:

• Por qué es necesaria la API Signal de WebAuthn: ¿Qué casos de uso soporta la API Signal de WebAuthn?
• Cómo funciona la API Signal de WebAuthn: ¿Cómo funciona exactamente? ¿Cuáles son las recomendaciones para los relying parties?

En el momento de escribir esto, la API Signal de WebAuthn está habilitada por defecto desde Chrome 132 y anteriormente se conocía como Reporting API, antes de ser renombrada para evitar conflictos con otra API del mismo nombre.

La API Signal de WebAuthn aborda casos de uso específicos relacionados con la gestión de passkeys en el lado del cliente. Específicamente, ayuda a mantener la información sincronizada entre el relying party (RP) y los autenticadores que forman parte de los sistemas operativos del cliente. Existen los siguientes casos de uso importantes:

Subscribe to our Passkeys Substack for the latest news.

Subscribe

Cuando se crea una passkey, esta incluye varias piezas de información: user.id, user.name y user.displayName. La passkey en sí se identifica a través del Credential ID único.

• user.id: es un identificador único que representa la cuenta a la que está vinculada la passkey. Este user.id es crucial porque se utiliza para el emparejamiento real de la passkey con la cuenta del usuario.
• user.name y user.displayName: son metadatos utilizados únicamente con fines de visualización en la interfaz de usuario.

La siguiente ilustración muestra una estructura de base de datos simple y típica que explica qué información se almacenaría usualmente en cada campo:

Es importante entender que, aunque user.name (a menudo una dirección de correo electrónico) y user.displayName (un nombre más amigable y legible) ayudan al usuario a identificar su cuenta en la interfaz de selección, la asociación real entre una passkey y una cuenta se mantiene a través del user.id y el Credential ID:

• Una cuenta puede tener múltiples passkeys, pero cada passkey se identifica de forma única y se empareja con la cuenta utilizando el user.id.
• Cada passkey en sí tiene un Credential ID único que es generado por el autenticador.

Surge un problema cuando el user.name, que puede ser una dirección de correo electrónico, cambia. Actualmente, no existe un mecanismo para actualizar este cambio directamente en el autenticador del lado del cliente. El user.name puede cambiar por varias razones, como cuando un usuario actualiza su dirección de correo electrónico. A pesar de este cambio en los metadatos de la cuenta en el lado del servidor, el antiguo user.name continuará apareciendo en la interfaz de selección de credenciales, lo que puede causar confusión a los usuarios.

La solución alternativa para este problema es crear una nueva passkey con el user.name actualizado y el mismo user.id, y luego sobrescribir la passkey existente. Sin embargo, este enfoque es inconveniente por varias razones:

1. Redundancia: Un autenticador solo puede almacenar una passkey por user.id para un ID de relying party específico. Esto significa que la passkey antigua debe ser reemplazada por una nueva para actualizar los metadatos, lo cual es un paso extra.
2. Experiencia de Usuario: Los usuarios no entenderán por qué necesitan crear una nueva passkey. Esa es la razón por la que esta solución alternativa no se usa ampliamente.
3. Complejidad: Gestionar la creación de passkeys y el reemplazo solo para actualizar metadatos es una complejidad innecesaria.

Las direcciones de correo electrónico, números de teléfono y otros identificadores pueden cambiar regularmente. Sin un método directo para actualizar user.name y user.displayName directamente en el autenticador, los usuarios pueden encontrar un problema persistente donde ven y tienen que seleccionar una passkey asociada con su antigua dirección de correo electrónico. Esta situación socava la experiencia fluida que las passkeys pretenden proporcionar. La API Signal de WebAuthn tiene como objetivo resolver este problema permitiendo a los relying parties reportar actualizaciones de los metadatos de las passkeys sin requerir la creación de nuevas. Antes de explicar cómo implementar la API Signal, exploraremos el segundo caso de uso importante que aborda.

Become part of our Passkeys Community for updates & support.

Join

Otro caso de uso crucial es la eliminación de passkeys en el autenticador del lado del cliente. Con el tiempo, los usuarios pueden revocar credenciales a través de la lista de gestión de passkeys o eliminar sus cuentas, y se hace necesario asegurar que estas credenciales se eliminen del autenticador del lado del cliente para evitar que aparezcan en futuras interfaces de selección de credenciales (Conditional UI / passkey autofill).

La necesidad de esta funcionalidad surge en varios escenarios:

1. Passkey eliminada a través de la configuración de la cuenta: Cuando una credencial ya no es válida, como después de que un usuario la haya eliminado explícitamente a través de la configuración de la cuenta:

Desde la perspectiva del usuario, es difícil entender que eliminar una credencial en la configuración de su cuenta (como en el diálogo de arriba) no elimine la passkey en su dispositivo actual.

2. Eliminación de Cuenta: Cuando un usuario elimina su cuenta, todas las passkeys asociadas también deberían eliminarse.

3. Políticas de Seguridad: Los relying parties pueden tener políticas de seguridad que requieran la revocación de credenciales después de períodos de inactividad o debido a problemas de seguridad detectados.

Sin un método directo para eliminar passkeys en el lado del cliente, estas credenciales obsoletas o inválidas continúan saturando la interfaz de selección, llevando a confusión. Los usuarios podrían ver e intentar usar passkeys que ya no son válidas, resultando en intentos de autenticación fallidos y una mala experiencia de usuario.

Mira este video sobre cómo eliminar passkeys del lado del servidor en la Consola de Gestión de Corbado Connect:

Implementar la API Signal de WebAuthn implica varios pasos y consideraciones para asegurar que la funcionalidad se integre correcta y seguramente. La API Signal permite a los relying parties (RPs) actualizar o eliminar credenciales passkey en el autenticador del lado del cliente. Esta sección describe las consideraciones clave y los pasos para la implementación.

Al implementar la API Signal de WebAuthn, es crucial tener en cuenta lo siguiente:

• Preservación de la Privacidad: La API Signal de WebAuthn está diseñada para preservar la privacidad del usuario, ya que es uno de los fundamentos de WebAuthn. Esto significa que no se proporciona retroalimentación (feedback) al RP sobre si el cambio solicitado fue procesado. La API opera silenciosamente para prevenir cualquier posible filtración de información sobre el estado de las credenciales.

• Disponibilidad del Autenticador: La efectividad de la API Signal de WebAuthn depende de la disponibilidad del autenticador. Esto incluye tanto la disponibilidad física como el soporte de software (por ejemplo, compatibilidad de navegador y sistema operativo). El navegador solo puede realizar acciones si el autenticador es accesible y soporta las operaciones necesarias sin necesitar autenticación biométrica.

• Restricciones de Dominio: La API asegura que solo el relying party asociado con un dominio específico pueda solicitar cambios en las credenciales relacionadas con ese dominio. Esta es una medida de seguridad para prevenir modificaciones no autorizadas por terceros.

• Credential ID como Clave: Al referenciar passkeys, el Credential ID es la clave primaria utilizada por la API Signal de WebAuthn. Este ID identifica de forma única la passkey en el autenticador del lado del cliente. La API permite a los RPs cambiar metadatos asociados con passkeys o señalar que ciertas passkeys ya no deben ser accedidas, pero solo a través del Credential ID. En caso de que un autenticador no conozca un Credential ID específico, lo ignorará silenciosamente.

Estas consideraciones son esenciales para entender los aspectos más importantes del funcionamiento correcto de la API Signal de WebAuthn.

La API Signal de WebAuthn proporciona un mecanismo optimizado para que los relying parties (RPs) actualicen los metadatos asociados con las passkeys en los autenticadores del lado del cliente. Esto es especialmente importante para asegurar que los usuarios vean información precisa y actualizada en la interfaz de selección de credenciales sin tener que crear nuevas passkeys innecesariamente. Así es como la API permite que esto suceda:

Actualizando Metadatos con signalCurrentUserDetails(options)

El método signalCurrentUserDetails(options) en la API Signal está diseñado específicamente para actualizar metadatos de passkeys. Este método permite a los RPs proporcionar los valores actuales para user.name y user.displayName.

Así es como funciona el proceso (ver también el estándar WebAuthn Nivel 3).

1. Estructura del Método: El método signalCurrentUserDetails(options) incluye el rp.id, user.id y los valores actualizados para user.name y user.displayName.

PublicKeyCredential.signalCurrentUserDetails({
    rpId: "example.com",
    userId: "aabbcc", // user handle, base64url.
    name: "Nuevo nombre de usuario",
    displayName: "Nuevo nombre para mostrar",
});

2. Actualizando los Metadatos Locales: Busca credenciales disponibles localmente (en el autenticador) que coincidan con el rpId y userId. Para todas las credenciales coincidentes, el autenticador actualizará el name y displayName de la credencial.

3. Preservación de la Privacidad: El proceso está diseñado para preservar la privacidad. La API Signal no proporciona retroalimentación al RP sobre si las actualizaciones fueron procesadas con éxito, previniendo cualquier filtración de información sobre el estado de las credenciales.

4. Consistencia entre Dispositivos: Al ejecutar regularmente los métodos signalCurrentUserDetails(options), los RPs pueden asegurar que los metadatos para las passkeys permanezcan consistentes a través de diferentes dispositivos y plataformas donde el usuario pueda autenticarse. Este enfoque reduce las posibilidades de que se muestre información obsoleta o incorrecta en la interfaz de selección de credenciales.

En la captura de pantalla anterior, puedes ver cómo Google Chrome señala tal actualización al usuario. La API Signal de WebAuthn es parte de Chrome y puede probarse con el Google Password Manager en escritorio.

La API Signal de WebAuthn proporciona mecanismos para que los relying parties (RPs) señalen la eliminación de passkeys de los autenticadores del lado del cliente. Esto es esencial para asegurar que las credenciales obsoletas o inválidas no aparezcan en la interfaz de selección de credenciales, manteniendo así una experiencia de usuario optimizada y segura. Hay dos métodos para eliminar las passkeys localmente: signalUnknownCredential(options) y signalAllAcceptedCredentials(options). El primero se puede usar en situaciones donde el usuario no está autenticado, mientras que el segundo se puede usar cuando el usuario está autenticado. Por lo tanto, el segundo debería preferirse por razones de privacidad.

Así es como funcionan los dos métodos:

1. Estructura del Método: El método signalUnknownCredential(options) incluye el rpId (ID del relying party) y el credentialId (el identificador único de la credencial a eliminar).

PublicKeyCredential.signalUnknownCredential({
    rpId: "example.com",
    credentialId: "aabbcc", // credential id que el usuario acaba de intentar usar, base64url
});

2. Llamando al Método: Los RPs llaman a este método cada vez que detectan que una credencial debe ser eliminada. Esto podría ser inmediatamente después de un intento de autenticación con una credencial inválida, durante la eliminación de una cuenta, o cuando un usuario revoca una credencial a través de la configuración de la cuenta.

3. Manejo del Método: Cuando se llama al método signalUnknownCredential(options), el autenticador del lado del cliente intenta encontrar credenciales que coincidan con el rpId y el credentialID especificado para su omisión. Dependiendo de las capacidades del autenticador, la credencial se elimina o se emplea un procedimiento específico del autenticador para ocultar la credencial en futuras ceremonias de autenticación.

1. Estructura del Método: El método signalAllAcceptedCredentials(options) incluye el rpId (ID del relying party), userId y una lista de IDs de credenciales válidos allAcceptedCredentialIds (lista de identificadores únicos de credenciales que deben mantenerse).

PublicKeyCredential.signalAllAcceptedCredentials({
    rpId: "example.com",
    userId: "aabbcc", // user handle, base64url.
    allAcceptedCredentialIds: ["bb"],
});

2. Llamando al Método: Los RPs llaman a este método cada vez que detectan que una credencial debe ser eliminada y señalan una lista de credenciales válidas. Este método debería preferirse sobre signalUnknownCredential(options) para eliminar credenciales.

3. Manejo del Método: Cuando se llama al método signalAllAcceptedCredentials(options), el autenticador del lado del cliente empareja el rpId y el userId. El autenticador busca todas las credenciales locales que coincidan con rpId y userId. El resultado se compara con allAcceptedCredentialIds. Si hay credenciales locales que no están en allAcceptedCredentialIds, entonces estas credenciales se eliminan localmente (o se ocultan dependiendo del autenticador).

4. Mostrar Credenciales Ocultas: Si unas credenciales han sido solo ocultadas (dependiendo del autenticador) y ahora son parte de allAcceptedCredentialIds, entonces estas credenciales estarán presentes nuevamente en futuras ceremonias de autenticación.

5. Consejos Útiles:

   • Al usar signalAllAcceptedCredentials(options), es importante notar que los autenticadores pueden no estar siempre conectados en el momento en que se ejecuta este método. Como resultado, los relying parties podrían considerar ejecutar signalAllAcceptedCredentials(options) periódicamente, como durante cada inicio de sesión, para asegurar que todas las credenciales estén actualizadas.
   • Los relying parties deben ser cautelosos al especificar la lista de IDs de credenciales (allAcceptedCredentialIds). Las credenciales que no se incluyan en esta lista pueden ser ocultadas o eliminadas por el autenticador, potencialmente de forma irreversible. Para evitar que credenciales válidas sean omitidas por error, es crucial asegurar que la lista esté completa. Si un ID de credencial válido se deja fuera accidentalmente, debe volver a añadirse a signalAllAcceptedCredentials(options) tan pronto como sea posible para hacerlo visible de nuevo, asumiendo que el autenticador soporte esto.
   • Siempre que sea posible, los autenticadores deberían preferir ocultar temporalmente las credenciales en lugar de eliminarlas permanentemente. Este enfoque puede ayudar a facilitar la recuperación si un ID de credencial válido fue omitido accidentalmente por el relying party, permitiendo que sea restaurado sin pérdida permanente.

En la captura de pantalla anterior, puedes ver cómo Google Chrome señala las eliminaciones. La API Signal de WebAuthn puede probarse con Google Password Manager en escritorio.

Para implementar efectivamente la API Signal de WebAuthn y asegurar una sincronización fluida de los metadatos de las passkeys a través de los autenticadores del lado del cliente, considera las siguientes recomendaciones:

• Estar atento a las actualizaciones e implementación real de la API Signal de WebAuthn: Mantente informado sobre los últimos desarrollos y actualizaciones relacionados con la API Signal. La API Signal de WebAuthn está habilitada con Google Chrome 132, seguida por otros navegadores (por ejemplo, Safari también anunció soporte). Revisa regularmente el progreso y las actualizaciones sobre la API Signal de WebAuthn para asegurar que tu implementación se alinee con los últimos estándares y prácticas. Actualizaremos esta publicación a medida que el panorama evolucione.
• Comienza con el enfoque signalAllAcceptedCredentials(options) después de cada inicio de sesión exitoso: Este enfoque asegura que todos los metadatos y IDs de credenciales se actualicen en un solo método, simplificando el proceso y manteniendo la consistencia a través de dispositivos y plataformas, y al mismo tiempo desactiva credenciales eliminadas u obsoletas.
• Mensajería en tiempo real con signalUnknownCredential(options) para despliegues a gran escala: Considera usar mensajería en tiempo real con el método signalUnknownCredential(options) en despliegues a gran escala o cuando haya necesidad de actualizaciones inmediatas. Este método puede mejorar la eficiencia y precisión de la gestión de credenciales, asegurando que las credenciales inválidas u obsoletas se eliminen prontamente de la interfaz de selección.

Siguiendo estas recomendaciones, podrás implementar la API Signal de WebAuthn efectivamente una vez que tenga soporte, asegurando que los metadatos de las passkeys permanezcan actualizados y consistentes en todos los autenticadores del lado del cliente, proporcionando así una experiencia de usuario fluida y segura para las passkeys.

El estándar WebAuthn está en continua evolución, volviéndose más rico en características mes a mes. La introducción de la API Signal de WebAuthn es un paso significativo hacia adelante en la gestión de metadatos y eliminaciones de passkeys en autenticadores del lado del cliente. Esta API aborda los casos de uso cruciales de mantener la información sincronizada entre relying parties (RPs) y autenticadores, y asegurar que las passkeys inválidas u obsoletas sean eliminadas, mejorando así la experiencia del usuario.

• ¿Por qué es necesaria la API Signal? La API Signal es esencial para actualizar metadatos de passkeys y eliminar passkeys en autenticadores del lado del cliente. Resuelve problemas relacionados con información obsoleta de user.name y user.displayName, que puede causar confusión cuando las credenciales se presentan en la interfaz de selección. Además, ayuda a mantener una interfaz de selección de credenciales limpia y segura al eliminar passkeys revocadas o borradas.
• ¿Cómo funciona la API Signal? La API Signal funciona permitiendo a los RPs llamar métodos sobre el estado actual de las credenciales, incluyendo actualizaciones de metadatos y señalando la eliminación de passkeys. Estos reportes son procesados por el autenticador del lado del cliente, asegurando que la información presentada a los usuarios sea precisa y actual. La API está diseñada para preservar la privacidad y opera sin proporcionar retroalimentación al RP sobre el éxito de las actualizaciones.

A medida que el estándar WebAuthn evoluciona, se beneficia de los diversos intereses de sus participantes, quienes impulsan diferentes partes del estándar. Mantener un ojo en estos desarrollos es crucial para estar al día con las últimas mejoras y asegurar que las implementaciones permanezcan alineadas con las mejores prácticas y estándares más recientes. La comunidad WebAuthn continúa impulsando la innovación, haciendo la autenticación más segura y amigable para el usuario.