Passkeys en Vaultwarden: qué funciona y cómo activar FIDO2

Las passkeys permiten acceder a servicios compatibles utilizando una llave de seguridad, la biometría del dispositivo o un PIN, evitando depender de contraseñas fáciles de robar mediante phishing. Vaultwarden puede almacenarlas dentro de la bóveda y también utilizar credenciales FIDO2/WebAuthn para añadir una segunda comprobación al iniciar sesión.

Sin embargo, es importante diferenciar estas funciones. Vaultwarden es un servidor alternativo compatible con los clientes de Bitwarden, pero no implementa automáticamente todas las características del servidor oficial. Actualmente puedes guardar passkeys para otras páginas y proteger Vaultwarden mediante FIDO2, pero no puedes sustituir completamente la contraseña maestra por una passkey para iniciar y descifrar la bóveda.

Esta guía parte de una instancia ya operativa. Si todavía no la tienes preparada, primero debes instalar Vaultwarden con Docker y configurar HTTPS.

Qué significa utilizar passkeys en Vaultwarden

La palabra passkey aparece en varias zonas de los clientes de Bitwarden, pero no siempre hace referencia a la misma función. En Vaultwarden existen tres escenarios que conviene separar.

Función	Disponibilidad en Vaultwarden	Para qué sirve
Guardar passkeys de otras webs	Sí	Acceder a Google, GitHub u otros servicios utilizando una passkey almacenada en la bóveda.
FIDO2/WebAuthn como segundo factor	Sí	Confirmar el acceso a Vaultwarden después de introducir el correo y la contraseña maestra.
Iniciar y descifrar Vaultwarden con una passkey	No	Sustituir el correo, la contraseña maestra y el desbloqueo mediante una credencial PRF.

Vaultwarden añadió soporte para guardar y utilizar passkeys de otras páginas mediante las extensiones oficiales de Bitwarden. Estas credenciales se sincronizan como parte de los elementos de inicio de sesión de la bóveda.

También admite el inicio de sesión en dos pasos mediante FIDO2/WebAuthn. En este caso, primero introduces el correo electrónico y la contraseña maestra y, posteriormente, verificas tu identidad mediante una llave física, Windows Hello u otro autenticador compatible.

La tercera posibilidad, denominada en Bitwarden Log in and unlock with passkeys, necesita endpoints adicionales del servidor y soporte para el descifrado mediante PRF. Vaultwarden todavía no los implementa, aunque el cliente web pueda mostrar temporalmente botones o ajustes relacionados con esta función.

Qué necesitas para configurar FIDO2 en Vaultwarden

Para utilizar una passkey como segundo factor necesitas preparar correctamente el servidor y el dispositivo desde el que vas a registrarla.

• Una versión reciente de Vaultwarden y del cliente de Bitwarden.
• Acceso a la bóveda web mediante un dominio estable.
• Una conexión HTTPS con un certificado válido.
• La variable DOMAIN configurada con la dirección pública correcta.
• Un navegador compatible con WebAuthn.
• Una llave física o autenticador FIDO2 compatible.
• La contraseña maestra de la cuenta.

La bóveda web necesita un contexto seguro para utilizar Web Crypto y WebAuthn. Por tanto, acceder mediante una dirección IP con HTTP puede impedir que el navegador cree o utilice la credencial.

La variable DOMAIN debe coincidir con la dirección empleada para entrar en Vaultwarden:

DOMAIN=https://vault.ejemplo.com

No registres la llave utilizando un dominio provisional que pienses cambiar posteriormente. Las credenciales WebAuthn están vinculadas al dominio del servicio y pueden dejar de funcionar si cambia el identificador del sitio.

Cómo activar una passkey como segundo factor

La configuración debe realizarse desde la bóveda web, no desde el panel de administración de Vaultwarden.

1. Abre la bóveda web mediante su dirección HTTPS.
2. Inicia sesión con tu correo electrónico y contraseña maestra.
3. Entra en Settings > Security.
4. Selecciona Two-step login.
5. Busca la opción Passkey o FIDO2 WebAuthn.
6. Pulsa Manage.
7. Confirma de nuevo tu contraseña maestra.
8. Escribe un nombre que identifique el dispositivo.
9. Selecciona la opción para registrar o leer la llave.
10. Completa la verificación solicitada por el navegador.
11. Guarda los cambios.

El autenticador puede ser una llave USB o NFC, Windows Hello, la biometría del equipo o un gestor de passkeys compatible. Las opciones concretas dependen del navegador, el sistema operativo y los dispositivos disponibles.

Si el navegador intenta utilizar automáticamente un autenticador diferente, busca una opción como Try another way, Other options o utiliza el botón para cancelar y elegir otra llave.

Después de registrar la credencial, Vaultwarden continuará solicitando la contraseña maestra. La passkey funciona como segundo paso de autenticación, no como sustituta de la contraseña.

Cómo guardar el código de recuperación

Al activar cualquier método de inicio en dos pasos debes guardar inmediatamente el código de recuperación. Sin él, perder la llave o el dispositivo puede dejarte fuera de la bóveda de forma permanente.

1. Abre Settings > Security.
2. Entra en Two-step login.
3. Selecciona View recovery code.
4. Introduce la contraseña maestra.
5. Copia o imprime el código mostrado.

Guárdalo fuera de la propia bóveda. Una copia impresa dentro de una caja fuerte o un archivo cifrado almacenado en un dispositivo desconectado evita el problema circular de necesitar entrar en Vaultwarden para recuperar el acceso a Vaultwarden.

Cuando utilizas el código de recuperación, se desactivan los métodos de inicio en dos pasos de la cuenta. El sistema genera después un código nuevo que también deberás guardar.

Cómo probar la passkey sin bloquear tu cuenta

No cierres todas las sesiones inmediatamente después de configurar FIDO2. Mantén abierta la pestaña desde la que realizaste el registro y utiliza otra ventana para comprobar el acceso.

1. Conserva abierta y desbloqueada la sesión actual.
2. Abre una ventana privada o un navegador diferente.
3. Accede al dominio habitual de Vaultwarden.
4. Introduce el correo electrónico y la contraseña maestra.
5. Completa la comprobación FIDO2 cuando aparezca.
6. Verifica que la bóveda se sincroniza correctamente.

Si la prueba falla, podrás volver a la sesión original y eliminar o registrar de nuevo el autenticador sin depender del código de recuperación.

También es recomendable disponer de un método alternativo de segundo factor. Puede ser otra llave física o una aplicación TOTP guardada en un dispositivo independiente.

Por qué Vaultwarden no permite iniciar sesión solo con una passkey

El servidor oficial de Bitwarden permite utilizar una passkey para autenticar la cuenta y, si el navegador y el autenticador admiten PRF, descifrar también la bóveda. De esta manera, el usuario puede entrar sin escribir el correo electrónico ni la contraseña maestra.

Este sistema necesita almacenar información adicional asociada a la credencial, como la clave de cifrado de la cuenta protegida mediante PRF. No es una función exclusivamente visual del cliente web: también requiere soporte específico en el servidor.

Vaultwarden no dispone actualmente de los endpoints necesarios para completar este registro. Por eso, si el cliente muestra la sección Log in with passkey, pueden aparecer errores 404 al intentar activarla. En algunas versiones, la compilación modificada de la bóveda web oculta directamente esta opción para evitar confusiones.

Modificar el CSS para mostrar el botón, cambiar el proxy o utilizar un autenticador compatible con PRF no añade la función que falta en el backend. Hasta que Vaultwarden incorpore oficialmente este soporte, tendrás que seguir utilizando la contraseña maestra para iniciar sesión.

Qué es PRF y por qué no soluciona la limitación

PRF significa Pseudo-Random Function y es una extensión de WebAuthn que permite derivar una clave secreta utilizando el autenticador. Bitwarden puede emplear esa clave para proteger la clave de cifrado de la cuenta y desbloquear la bóveda mediante una passkey.

Para que funcione, tanto el navegador como el autenticador deben admitir PRF. Por ejemplo, determinadas llaves YubiKey y navegadores basados en Chromium son compatibles, aunque el soporte cambia según el sistema operativo.

No obstante, disponer de una llave y un navegador compatibles no es suficiente. Vaultwarden tendría que almacenar y devolver los datos cifrados necesarios durante el inicio de sesión. Como esta parte del servidor aún no está implementada, PRF no permite descifrar una bóveda de Vaultwarden.

Cómo guardar passkeys de otras páginas en Vaultwarden

Una función diferente, y que sí está disponible, consiste en utilizar Vaultwarden como almacén de las passkeys creadas para otras páginas. Esto permite iniciar sesión en servicios compatibles sin depender de sus contraseñas tradicionales.

1. Instala una versión reciente de la extensión oficial de Bitwarden.
2. Configura la extensión para conectarse a tu servidor Vaultwarden.
3. Inicia sesión y desbloquea la bóveda.
4. Abre una web que permita crear passkeys.
5. Entra en sus ajustes de seguridad y selecciona la creación de una nueva passkey.
6. Elige Bitwarden cuando el navegador pregunte dónde quieres guardarla.
7. Autoriza la operación mediante la extensión.
8. Comprueba que la passkey aparece dentro del elemento de inicio de sesión.
9. Fuerza una sincronización antes de probarla desde otro dispositivo.

Cuando vuelvas a la página, la extensión podrá ofrecer la passkey guardada. La clave privada permanece cifrada dentro de la bóveda y se sincroniza entre los clientes compatibles.

Esta función no debe confundirse con la protección de la propia cuenta. Una passkey guardada para Google, GitHub o cualquier otro servicio no reemplaza la contraseña maestra de Vaultwarden.

Cómo reforzar la contraseña maestra con Argon2id

Como Vaultwarden sigue necesitando la contraseña maestra, debes utilizar una clave larga, única y que puedas recordar. También puedes configurar Argon2id como función de derivación de claves.

Este ajuste pertenece a cada cuenta individual. No se activa mediante una variable del contenedor ni modifica el algoritmo global del servidor.

1. Abre la bóveda web.
2. Entra en Settings > Security.
3. Selecciona el apartado Keys.
4. Elige Argon2id en el campo del algoritmo.
5. Revisa los parámetros mostrados.
6. Actualiza la configuración de cifrado.
7. Comprueba el acceso desde todos tus dispositivos.

Unos valores excesivamente altos pueden ralentizar el inicio y el desbloqueo, especialmente en móviles o equipos modestos. No copies configuraciones extremas sin probarlas primero en todos los clientes utilizados.

Argon2id dificulta los ataques de fuerza bruta contra la contraseña maestra, pero no habilita el inicio mediante passkeys. Son mecanismos diferentes y complementarios.

También conviene aplicar las recomendaciones generales para utilizar gestores de contraseñas de forma segura, especialmente cuando la instancia contiene credenciales familiares o empresariales.

Limitaciones de seguridad en servidores autoalojados

WebAuthn está diseñado para vincular una credencial con el dominio donde fue creada, lo que reduce notablemente el riesgo de phishing. Sin embargo, la documentación de Bitwarden advierte de que los servidores autoalojados pueden estar expuestos a determinados ataques contra la verificación FIDO2 en dos pasos.

Un atacante que ya conozca el correo y la contraseña maestra podría intentar mostrar una solicitud falsa de passkey y reutilizar la respuesta. Por este motivo, antes de tocar una llave o aceptar una petición biométrica, comprueba siempre que estás en el dominio exacto de tu servidor.

• No accedas desde enlaces recibidos por mensajes inesperados.
• Comprueba el dominio y el certificado HTTPS.
• No aceptes solicitudes WebAuthn que aparezcan fuera del inicio de sesión esperado.
• Utiliza una contraseña maestra única aunque tengas activado FIDO2.
• Conserva el código de recuperación fuera de línea.

Qué ocurre con las passkeys en iPhone y iPad

Los clientes nativos de Apple necesitan asociar la aplicación con el dominio del servidor. Algunos usuarios de Vaultwarden han informado de bucles de autenticación porque el dominio no sirve el archivo apple-app-site-association esperado por iOS.

Sin embargo, añadir manualmente un JSON con los identificadores de la aplicación de Bitwarden no es una solución oficial ni universal. La propuesta procede de una incidencia abierta y puede dejar de funcionar si cambian los identificadores, las rutas o el comportamiento del cliente.

Además, ese archivo no incorpora el inicio y descifrado mediante passkey al backend de Vaultwarden. Solamente interviene en la asociación entre la aplicación nativa y el dominio.

Si encuentras un bucle en iOS:

1. Actualiza Vaultwarden y la aplicación de Bitwarden.
2. Confirma que DOMAIN contiene la dirección HTTPS correcta.
3. Comprueba FIDO2 desde la bóveda web.
4. Revisa el diagnóstico disponible en /admin/diagnostics.
5. Elimina y registra de nuevo la credencial si todavía conservas otra sesión.
6. Utiliza temporalmente TOTP u otro método alternativo.

No modifiques el proxy con identificadores copiados de una incidencia sin comprobar antes la documentación y el estado actual del problema.

Errores frecuentes al utilizar passkeys en Vaultwarden

Log in with passkey devuelve un error 404

La función de iniciar y descifrar la bóveda mediante passkey todavía no está implementada en Vaultwarden. El cliente intenta acceder a endpoints que el servidor no ofrece. No es necesariamente un problema de Caddy, Nginx o el navegador.

La opción FIDO2 WebAuthn no aparece

Busca dentro de Settings > Security > Two-step login. No debes utilizar la sección de contraseña maestra destinada al inicio mediante passkey del servidor oficial de Bitwarden.

El navegador rechaza la creación de la credencial

Comprueba que utilizas HTTPS, que el certificado sea válido y que DOMAIN coincida con la dirección visible en el navegador. Revisa también que el navegador y el autenticador admitan FIDO2.

La llave funciona en la web, pero no en la aplicación

El soporte puede variar entre la bóveda web, las extensiones y los clientes nativos. Actualiza todas las aplicaciones y conserva un método alternativo para los dispositivos donde WebAuthn no funcione correctamente.

La passkey acepta la verificación, pero no desbloquea la bóveda

Es el comportamiento esperado cuando FIDO2 se utiliza como segundo factor. Para desbloquear una bóveda ya bloqueada necesitas la contraseña maestra, un PIN o la biometría configurada en el cliente.

La passkey de otra página no aparece al iniciar sesión

Fuerza la sincronización de la extensión, comprueba que el elemento contiene la passkey y revisa que la dirección guardada corresponda con el dominio real. Las credenciales WebAuthn están vinculadas al identificador del sitio que las creó.

He perdido la llave de seguridad

Utiliza otro método configurado o el código de recuperación. El código se introduce desde:

https://vault.ejemplo.com/#/recover-2fa/

Después de recuperarla, vuelve a configurar los métodos de segundo factor y guarda el nuevo código generado.

Windows Hello se abre en lugar de la llave USB

El sistema puede seleccionar automáticamente su autenticador integrado. Busca una opción para utilizar otro dispositivo o cancela el primer diálogo para mostrar el selector completo de credenciales.

Las passkeys amplían considerablemente las posibilidades de Vaultwarden, pero es fundamental saber qué función realiza cada una. Puedes guardar credenciales para acceder sin contraseña a otras páginas y proteger tu propia cuenta mediante FIDO2/WebAuthn como segundo factor.

Lo que todavía no puedes hacer es sustituir completamente el correo, la contraseña maestra y el descifrado de Vaultwarden mediante una passkey PRF. Hasta que el proyecto incorpore ese soporte, mantén una contraseña maestra robusta, guarda el código de recuperación fuera de la bóveda y prueba cada autenticador antes de cerrar las demás sesiones.