Joomla: autenticación FIDO2 / WebAuthn con Nitrokey 3
1. Introducción
En este manual aprenderemos a integrar la llave de seguridad Nitrokey 3 como método de autenticación segura en Joomla utilizando los estándares FIDO2 y WebAuthn. Permitiendo iniciar sesión sin contraseña, utilizando únicamente la llave de seguridad (Nitrokey 3).
El objetivo es que cualquier usuario pueda:
- habilitar WebAuthn en Joomla
- registrar una llave de seguridad (Nitrokey 3)
- iniciar sesión usando FIDO2 / WebAuthn
- gestionar varias llaves
- resolver errores comunes
Este manual se ha elaborado utilizando:
- Joomla
- Nitrokey 3A NFC
- Navegadores compatibles con WebAuthn (Chrome, Firefox, Edge, Chromium)
Al finalizar, tendrás un sistema de autenticación moderno, seguro y sin contraseñas, totalmente integrado en Joomla.
2. Requisitos técnicos
Para utilizar la llave de seguridad (Nitrokey 3) como método de autenticación FIDO2 / WebAuthn en Joomla es necesario cumplir una serie de requisitos técnicos.
- Tener un sitio web con Joomla
- Sitio web servido mediante HTTPS
- Un navegador compatible
- Una llave de seguridad (Nitrokey 3)
- Usar el plugin: Sistema - Inicio de sesión sin contraseña de WebAuthn
Si alguno de estos puntos no se cumple, el registro de la llave o el inicio de sesión pueden fallar.
2.1 Tener un sitio web con Joomla
Este manual está basado en Joomla
Requisitos mínimos:
- Joomla correctamente instalado
- Acceso al panel de administración
2.2 Sitio web servido mediante HTTPS
WebAuthn no funciona en HTTP. El sitio debe estar servido obligatoriamente bajo HTTPS con un certificado de seguridad válido.
Si intentas registrar la llave en un sitio HTTP, aparecerá el error: SecurityError: The operation is insecure
Por tanto, asegúrate de que:
- El dominio tiene un certificado SSL válido
- No hay contenido mixto (HTTP dentro de HTTPS)
- El navegador nos muestre las advertencias de seguridad
2.3 Un navegador compatible
Para registrar y usar una llave de seguridad (Nitrokey 3) en Joomla necesitas un navegador con soporte completo para FIDO2 / WebAuthn.
- Google Chrome
- Mozilla Firefox
- Microsoft Edge
- Google Chromium
2.4 Una llave de seguridad (Nitrokey 3)
Antes de usar la llave de seguridad (Nitrokey 3) en Joomla, asegúrate de que:
- La llave de seguridad está actualizada a la última versión de firmware
- El módulo FIDO2 / WebAuthn este configurado para usar: PIN y/o Sensor dactilar (ambos opcional, pero recomendado)
Si necesitas revisar la configuración, consulta el Manual: Configurar Nitrokey 3 desde Nitrokey App 2 (GUI).
La llave de seguridad (Nitrokey 3) puede registrarse mediante las opciones: USB-A, USB-C y NFC,
pero cada método depende del dispositivo utilizado y del soporte del
servicio (en este caso Joomla).
Es importante entender estas limitaciones para evitar errorres durante el registro de la llave.
Registrar una llave de seguridad en Joomla crea una credencial FIDO2, que queda almacenada.
Sin embargo, FIDO2 / WebAuthn distingue entre los transportes:
- USB (USB-A, USB-C)
- NFC
Cada transporte (USB y NFC) requiere de registro.
Ejemplo:
- Registrar la llave por USB-A o USB-C (habilita el transporte USB)
- Registrar la llave por NFC (habilita el transporte NFC)
Si deseas usar la llave mediante NFC, debes iniciar sesión en Joomla desde Android/Iphone.
2.5 Usar el plugin: Sistema - Inicio de sesión sin contraseña de WebAuthn
Joomla incluye soporte para WebAuthn de forma nativa mediante el plugin: Sistema - Inicio de sesión sin contraseña de WebAuthn. No es necesario instalar nada adicional, el plugin ya forma parte del sistema, pero viene desactivado por defecto.
Para poder registrar la llave de seguridad (Nitrokey 3), es necesario:
- Activar el plugin: Sistema - Inicio de sesión sin contraseña de WebAuthn
- Asegurarse de que el sitio funciona bajo HTTPS
Observaciones:
Un usuario puede quedarse bloqueado al intentar usar un servicio si:
- No puede iniciar sesión desde el móvil ni el pc
- Si usa una llave de seguridad USB-C y NO tiene adaptador USB-C a USB-A para conectarse al pc
- Si usa una llave de seguridad USB-A y NO tiene adaptador USB-A a USB-C para conectarse al móvil
- Intenta registrar por NFC en PC (no funciona)
Por eso es importante leer esta sección antes de continuar.
El uso de llaves de seguridad, conlleva usar al menos dos llaves de seguridad:
- 1 llave de uso diario
- 1 llave como "backup"
Y en caso de deterioro, rotura, perdida o robo, damos de baja del servicio (en este caso; Joomla) dicha llave, y damos de alta la nueva llave de seguridad. Porque siempre se recomienda usar 2 llaves de seguiridad
NOTA MUY IMPORTANTE: El backup no es una copia exacta, ya que las llaves de seguridad no se pueden clonar, ni hacer copias. Lo que se tiene que hacer es registrar las dos llaves físicas, en el mismo servicio (en este caso en joomla).
3. Activación y configuración FIDO2 / WebAuthn en Joomla
Joomla incluye soporte nativo para autenticación sin contraseña mediante el plugin: Sistema - Inicio de sesión sin contraseña de WebAuthn, que viene instalado por defecto pero esta desactivado.
Para poder registrar y utilizar la Nitrokey 3 como clave de seguridad, es necesario activarlo.
A continuación se detallan los pasos.
3.1 Activar el plugin WebAuthn
Iniciamos sesión en el panel de administración de Joomla. Y seguimos los siguientes pasos
- Primero haz clic en el menú izquierdo en: Sistema
En el menú de la derecha hacemos clic en: Plugins
En el buscador superior, escribe: webauthn
Debería aparecer el plugin: Sistema - Inicio de sesión sin contraseña de WebAuthn y observamos como el plugins esta instalado pero desactivado
Selecciona dicho plugins marcándolo en el check de la izquierda y en la parte superior, hacemos clic en: Habilitar
A partir de este momento, Joomla ya permite registrar llaves de seguridad con soporte FIDO2 / WebAuthn, como las Nitrokey 3.
4. Registrar llaves de seguridad FIDO2 / WebAuthn por USB
Este
registro se realiza desde el perfil del usuario, y únicamente lo puede
hacer el mismo usuario, nunca el administrador, no se puede registrar
llaves de seguridad en un perfil distinto al que está logueado. Y lo
podemos hacer desde un PC o desde el móvil (siendo indiferente donde lo
habilites, es totalmente válido para usar tanto en el PC como en el
móvil)
A continuación se detalla el proceso.
- Primero conectamos la llave de seguridad al PC
- Iniciamos sesión en el panel de administración de Joomla. En el menú lateral o central, hacemos clic en: Usuario
- Haz clic sobre tu nombre de usuario.
- Accede a la pestaña: Inicio de sesión de autenticación web W3C (WebAuthn)
NOTA MUY IMPORTANTE: Esta pestaña solo aparece cuando activas el plugins
- Hacemos clic en: + Añadir nuevo autenticador
El navegador mostrará una ventana emergente solicitando el PIN de seguridad del modulo FIDO2 / WebAuthn (que configuramos en el Manual 2).
Introducimos la contraseña y pulsamos en siguiente.
Ahora nos pide que toquemos el sensor de la llave de seguridad (que configuramos en el Manual 2). La llave de seguridad (nitrokey 3) comenzará a parpadear, indicando que está esperando la confirmación táctil, para confirmar y autorizar la operación.
Una vez que pulsemos el sensor táctil, la llave de seguridad queda registrada en la administración Joomla.
- La nueva llave aparecerá en la lista de llaves de seguridad
- Le ponemos un nombre descriptivo, para diferenciar cada llave de seguridad
Ejemplos de nombres útiles:
- Nitrokey 3A USB
- Nitrokey 3A NFC
Ahora repetimos el mismo proceso para añadir el transporte NFC. Aquí solo se puede hacer desde el propio móvil Android / Iphone. Una vez registrado nos aparece listado en el almacén de llaves de seguridad.
Nota importantes:
- Si la llave no parpadea, desconéctala y vuelve a conectarla.
- Si aparece un error de seguridad, revisa que el sitio esté bajo HTTPS.
- Si el navegador no muestra la ventana emergente, revisa bloqueadores o políticas de seguridad.
- Si la operación expira, repite el proceso
5. Inicio de sesión en Joomla usando la llave de seguridad (Nitrokey 3)
Una vez registrada la llave de seguridad (Nitrokey 3), ya es posible iniciar sesión en Joomla utilizando autenticación FIDO2 / WebAuthn, sin necesidad de introducir una contraseña. El proceso es sencillo, rápido y seguro.
A continuación se muestra el flujo completo.
- Abre el navegador. Accede a la URL de inicio de sesión de Joomla (backend o frontend). Verás el formulario habitual de usuario, contraseña y Autenticación Web.
- Solo es necesario introducir el usuario. Y hacemos clic en Autenticación web
El navegador mostrará una ventana emergente solicitando introducir el PIN de la llave de seguridad (FIDO2).
Introducimos la contraseña y pulsamos en continuar.
Ahora debemos tocar la Nitrokey 3 para confirmar y autorizar la operación.
Si el toque ha sido reconocido correctamente, ya nos habremos logeado en el sistema.
6. Gestión de llaves de seguridad registradas
Una vez registrada la llave de seguridad (Nitrokey 3) como método de autenticación, Joomla permite gestionar todas las llaves de seguridad que tiene activada cada usuario.
Desde el perfil del usuario, es posible:
- ver las llaves de seguridad registradas
- añadir nuevas llaves de seguridad
- renombrar una llave de seguridad existente
- eliminar llaves de seguridad que ya no se utilices
7. Errores comunes y soluciones
Aunque la integración de Nitrokey 3 con Joomla mediante WebAuthn suele funcionar sin problemas, existen ciertos errores habituales que pueden aparecer durante el registro o el inicio de sesión.
En esta sección se describen los fallos más frecuentes, sus causas y cómo solucionarlos.
7.1 “SecurityError: The operation is insecure”
Este es el error más común al intentar registrar o usar una llave FIDO2.
Causa: El sitio no está servido bajo HTTPS o el certificado SSL no es válido.
Solución:
- Asegúrate de que el dominio utiliza HTTPS.
- Verifica que el certificado SSL no está caducado.
- Evita contenido mixto (HTTP dentro de HTTPS).
- Comprueba que el navegador no muestra advertencias de seguridad.
7.2 “This site must be served over HTTPS”
Este mensaje aparece directamente desde el navegador.
Causa: WebAuthn no funciona en HTTP bajo ninguna circunstancia.
Solución:
- Habilitar HTTPS en el servidor.
- Instalar un certificado válido (Let’s Encrypt es suficiente).
- Redirigir automáticamente HTTP a HTTPS.
7.3 La ventana emergente de WebAuthn no aparece
Causas posibles:
- El navegador bloquea ventanas emergentes.
- Extensiones de seguridad interfieren.
- Políticas corporativas deshabilitan WebAuthn.
- El plugin WebAuthn no está habilitado en Joomla.
Solución:
- Permitir ventanas emergentes para el dominio.
- Desactivar temporalmente extensiones de seguridad.
- Probar en otro navegador.
- Revisar que el plugins WebAuthn está habilitado.
7.4 La Nitrokey 3 no parpadea
Causas posibles:
- La llave no está bien conectada.
- El puerto USB no responde.
- El navegador no detecta dispositivos FIDO2.
- La operación WebAuthn no se ha iniciado correctamente.
Solución:
- Desconectar y volver a conectar la Nitrokey 3.
- Probar otro puerto USB.
- Cerrar y abrir el navegador.
- Repetir el proceso desde el inicio.
7.5 Error de timeout (tiempo agotado)
Causa: El usuario tarda demasiado en tocar la llave o el navegador no recibe la señal a tiempo.
Solución:
- Repetir el proceso y tocar la llave en cuanto empiece a parpadear.
- Evitar usar hubs USB de baja calidad.
7.6 “NotAllowedError: The request is not allowed”
Causas posibles:
- Se ha cancelado la operación desde el navegador.
- Se ha cerrado la ventana emergente.
- Se ha intentado registrar una llave ya registrada.
Solución:
- Repetir el proceso desde el paso inicial.
- Comprobar si la llave ya aparece en la lista de claves registradas.
7.7 El navegador indica que la llave no es compatible
Causas posibles:
- Navegador desactualizado.
- WebAuthn deshabilitado por políticas.
- Uso de navegadores no compatibles (algunos móviles antiguos).
Solución:
- Actualizar el navegador.
- Probar con Chrome, Firefox, Edge o Chromium.
- Revisar políticas de seguridad si es un entorno corporativo.
7.8 La llave aparece registrada pero no permite iniciar sesión
Causas posibles:
- El usuario ha cambiado de dominio (por ejemplo, de prueba a producción).
- El ID no coincide con el dominio actual.
- La clave se registró en un subdominio distinto.
Solución:
- Eliminar la clave y registrarla de nuevo en el dominio correcto.
- Revisar la configuración del plugin WebAuthn.
7.9 Joomla no muestra la opción “Añadir clave de seguridad”
Causas posibles:
- El plugin WebAuthn no está habilitado.
- El usuario no tiene permisos suficientes.
- El sitio no está bajo HTTPS.
Solución:
- Activar el plugins WebAuthn.
- Usar un usuario con permisos de administrador.
- Verificar HTTPS.
Manuales publicados en este blog sobre Nitrokey 3, hasta ahora son:
1- Configurar Nitrokey 3 desde consola (nitropy)
2- Configurar Nitrokey 3 desde Nitrokey App 2 (GUI)
3- Joomla: Autenticación FIDO2 / WebAuthn con Nitrokey 3
