Añadir una llave física en Gitea
Introducción
Configuración del inicio de sesión en Gitea mediante una llave física compatible con WebAuthn (YubiKey 5C NFC en este caso), manteniendo el método TOTP activo como respaldo en caso de pérdida o fallo de la llave.
Requisitos previos
- Gitea actualizado (≥ 1.21) con soporte WebAuthn.
- Navegador compatible con FIDO2/WebAuthn.
- Llave física (YubiKey, SoloKey, etc.).
- Método TOTP ya configurado (por ejemplo con Aegis o Authy) para disponer de acceso alternativo.
- Variable
ROOT_URLcorrectamente definida en el archivoapp.inicon la URL pública real de la instancia.
Desarrollo / pasos
1. Acceder a la configuración de seguridad
Desde el perfil de usuario: Perfil → Configuración → Seguridad.
2. Añadir la llave física
En el apartado Two-Factor Authentication (Security Keys):
- Introducir un nombre identificativo para la llave (por ejemplo:
YubiKey 5C NFC). - Pulsar Añadir llave de seguridad y seguir las instrucciones del navegador para completar el registro.
3. Confirmar el registro
La llave quedará listada con el nombre asignado. Se puede verificar su funcionamiento cerrando sesión y volviendo a iniciar con la llave insertada o aproximada (en caso de NFC).
4. Mantener TOTP como respaldo
No eliminar el método TOTP. Servirá para acceder si la llave se pierde, se rompe o deja de funcionar.
Errores comunes o decisiones importantes
- Error
Error validating origin: revisar que la variableROOT_URLenapp.inicoincide con la URL pública (por ejemplohttps://gitea.tudominio.org). - Algunas configuraciones de proxy (Caddy, Nginx) pueden alterar cabeceras y provocar fallos en WebAuthn.
- Recomendable registrar más de una llave si se dispone de varias.
Resumen breve
- Añadir la llave desde Configuración → Seguridad.
- Verificar
ROOT_URL. - Mantener TOTP como respaldo.
- Probar inicio de sesión con la llave.