Guía Completa para Instalar y Configurar Authelia con Docker

Si tienes varias aplicaciones alojadas en un servidor, gestionar cada inicio de sesión por separado puede convertirse en un auténtico quebradero de cabeza. Además, exponer paneles internos únicamente protegidos por una contraseña aumenta el riesgo de que alguien consiga acceder a ellos mediante credenciales filtradas o ataques automatizados.

Una forma de reforzar esta infraestructura consiste en instalar Authelia con Docker. Esta plataforma de código abierto funciona como una puerta de autenticación centralizada y permite añadir inicio de sesión único, políticas de acceso y autenticación multifactor a las aplicaciones situadas detrás de un proxy inverso.

En esta guía vamos a realizar un despliegue sencillo para un único servidor, utilizando Docker Compose, usuarios almacenados en un archivo y una base de datos SQLite. La configuración avanzada del proxy, las reglas y el segundo factor se abordarán por separado para evitar mezclar distintas intenciones.

Qué necesitas para instalar Authelia con Docker

Antes de empezar, necesitas un servidor Linux con Docker Engine y el complemento Docker Compose instalados. También debes disponer de permisos para crear carpetas, redes y contenedores.

Para que el portal de autenticación funcione correctamente en el navegador necesitarás:

• Un dominio o subdominio válido, como auth.ejemplo.com.
• Un proxy inverso como Nginx Proxy Manager, Traefik, Caddy o Nginx.
• Un certificado TLS válido para acceder mediante HTTPS.
• Una red de Docker compartida entre Authelia y el proxy inverso.

Authelia puede comunicarse con el proxy mediante HTTP dentro de la red privada de Docker. El cifrado HTTPS debe aplicarse en la conexión que llega al proxy desde el navegador, por lo que no es necesario configurar TLS dentro del propio contenedor.

Esta guía utiliza SQLite porque es una opción adecuada para una única instancia. Si necesitas varias réplicas o alta disponibilidad, conviene emplear PostgreSQL o MySQL y configurar Redis como almacén compartido de sesiones.

Cómo preparar las carpetas y la red de Docker

Empieza creando una carpeta dedicada para evitar que la configuración quede mezclada con otros contenedores:

mkdir -p authelia/config authelia/secrets
cd authelia

Después, crea una red externa que también utilizará el proxy inverso:

docker network create proxy

Solo necesitas ejecutar este comando una vez. Si la red ya existe, Docker mostrará un aviso y podrás continuar con la instalación.

La estructura final será parecida a esta:

authelia/
├── docker-compose.yml
├── .env
├── config/
│   ├── configuration.yml
│   └── users_database.yml
└── secrets/
    ├── JWT_SECRET
    ├── SESSION_SECRET
    └── STORAGE_ENCRYPTION_KEY

El volumen config almacenará la configuración, los usuarios y la base de datos SQLite. Gracias a esta persistencia, los datos no desaparecerán al recrear o actualizar el contenedor.

Cómo crear los secretos de Authelia

Authelia necesita varias cadenas aleatorias para proteger las sesiones, el almacenamiento y el proceso de recuperación de contraseñas. Puedes generarlas con OpenSSL:

openssl rand -hex 64 > secrets/JWT_SECRET
openssl rand -hex 64 > secrets/SESSION_SECRET
openssl rand -hex 64 > secrets/STORAGE_ENCRYPTION_KEY
chmod 600 secrets/*

Estos valores no deben escribirse directamente en configuration.yml. Los montaremos como archivos de solo lectura y utilizaremos las variables terminadas en _FILE para que Authelia pueda leerlos.

Es importante no definir el mismo secreto mediante dos métodos diferentes. Si un valor aparece simultáneamente en el YAML y en una variable _FILE, Authelia detendrá el arranque para evitar una configuración ambigua.

Cómo crear el archivo Docker Compose de Authelia

Primero, comprueba el identificador de tu usuario y grupo:

id -u
id -g

Crea un archivo .env y sustituye los números si tus identificadores son diferentes:

AUTHELIA_UID=1000
AUTHELIA_GID=1000
TZ=Europe/Madrid

Después, crea el archivo docker-compose.yml:

services:
  authelia:
    image: docker.io/authelia/authelia:latest
    container_name: authelia
    restart: unless-stopped
    user: "${AUTHELIA_UID}:${AUTHELIA_GID}"

    environment:
      TZ: "${TZ}"
      AUTHELIA_IDENTITY_VALIDATION_RESET_PASSWORD_JWT_SECRET_FILE: /secrets/JWT_SECRET
      AUTHELIA_SESSION_SECRET_FILE: /secrets/SESSION_SECRET
      AUTHELIA_STORAGE_ENCRYPTION_KEY_FILE: /secrets/STORAGE_ENCRYPTION_KEY

    volumes:
      - ./config:/config
      - ./secrets:/secrets:ro

    networks:
      - proxy

    expose:
      - "9091"

    ports:
      - "127.0.0.1:9091:9091"

networks:
  proxy:
    external: true

El puerto 9091 queda vinculado únicamente a 127.0.0.1, por lo que no estará expuesto directamente a Internet ni al resto de la red local. El proxy podrá comunicarse con el servicio utilizando la dirección interna http://authelia:9091.

Cuando termines de integrarlo con el proxy, puedes eliminar completamente la sección ports. La directiva expose será suficiente mientras ambos contenedores compartan la red proxy.

Para entornos de producción también puedes sustituir latest por una versión estable concreta, evitando actualizaciones inesperadas al descargar de nuevo la imagen.

Cómo preparar la configuración mínima de Authelia

Crea el archivo config/configuration.yml con el siguiente contenido. Sustituye ejemplo.com por tu dominio real:

theme: auto

server:
  address: "tcp://:9091/"

log:
  level: info

authentication_backend:
  file:
    path: /config/users_database.yml
    watch: false
    password:
      algorithm: argon2

access_control:
  default_policy: deny

session:
  cookies:
    - domain: ejemplo.com
      authelia_url: https://auth.ejemplo.com
      default_redirection_url: https://ejemplo.com

storage:
  local:
    path: /config/db.sqlite3

notifier:
  filesystem:
    filename: /config/notification.txt

La política predeterminada deny mantiene todas las aplicaciones cerradas hasta que añadas reglas explícitas. Esto sigue el principio de denegación por defecto y reduce el riesgo de dejar un servicio accesible por descuido.

El notificador por archivo resulta práctico durante las pruebas porque escribe los enlaces de registro y recuperación en notification.txt. Sin embargo, para un despliegue definitivo deberías configurar SMTP, ya que el notificador por archivo no está recomendado para producción.

Las reglas específicas deben añadirse después, siguiendo una guía dedicada para configurar reglas de acceso en Authelia sin convertir esta instalación en un artículo excesivamente amplio.

Cómo crear el primer usuario de Authelia

Las contraseñas del backend de archivos deben almacenarse mediante un hash seguro. Ejecuta el generador incluido en la imagen oficial:

docker run --rm -it docker.io/authelia/authelia:latest authelia crypto hash generate argon2

Introduce la contraseña cuando el comando la solicite. En la salida aparecerá una línea denominada Digest. Copia solamente el hash que comienza por $argon2id$, sin incluir la palabra Digest:.

Después, crea config/users_database.yml:

users:
  maria:
    disabled: false
    displayname: "María"
    password: "$argon2id$v=19$m=65536,t=3,p=4$SUSTITUYE_ESTE_VALOR"
    email: "[email protected]"
    groups:
      - "admins"

Protege el archivo para impedir que otros usuarios del servidor puedan leerlo:

chmod 600 config/users_database.yml

Aunque el archivo no contiene la contraseña original, el hash sigue siendo información sensible y no debe publicarse en repositorios ni compartirse sin necesidad.

Cómo validar y arrancar Authelia

Antes de iniciar el contenedor, verifica primero la estructura del archivo Compose:

docker compose config

A continuación, utiliza el validador de Authelia para detectar propiedades desconocidas, errores de sintaxis o configuraciones incompatibles:

docker compose run --rm authelia authelia config validate --config /config/configuration.yml

Si la validación termina correctamente, levanta el servicio:

docker compose up -d

Comprueba su estado y consulta los registros:

docker compose ps
docker compose logs -f authelia

El contenedor debería aparecer como iniciado y, después de completar las comprobaciones internas, como saludable. Si entra constantemente en estado de reinicio, los logs indicarán normalmente qué clave, archivo o permiso está provocando el fallo.

Cómo comprobar que Authelia está funcionando

Antes de configurar ninguna aplicación, comprueba que el contenedor responde localmente en el puerto 9091 y que el proxy puede resolver el nombre authelia dentro de la red compartida.

El acceso normal debe realizarse mediante una URL como:

https://auth.ejemplo.com

El subdominio debe apuntar al proxy inverso y contar con un certificado válido. Authelia necesita una URL HTTPS y un dominio aceptado por los navegadores para crear correctamente sus cookies de sesión; localhost no sirve como dominio definitivo del portal.

Una vez que aparezca la pantalla de acceso, inicia sesión con el usuario creado anteriormente. El registro de TOTP, WebAuthn u otros factores dependerá de las políticas que configures posteriormente y del sistema de notificaciones elegido.

Desde aquí puedes proteger una aplicación con Authelia, conectarlo a un proxy inverso o configurar OpenID Connect en Authelia para aplicaciones compatibles con OIDC.

Cómo actualizar Authelia con Docker Compose

Antes de actualizar, realiza una copia de las carpetas config y secrets. Si utilizas SQLite, lo más seguro es detener temporalmente el contenedor antes de copiar la base de datos:

docker compose stop authelia
cp -a config "config-backup-$(date +%F-%H%M)"
cp -a secrets "secrets-backup-$(date +%F-%H%M)"

Después, descarga la imagen y recrea el servicio:

docker compose pull
docker compose up -d

Finalmente, revisa los registros para confirmar que las migraciones y comprobaciones se han completado correctamente:

docker compose logs --tail=100 authelia

Antes de cambiar entre versiones importantes, conviene revisar las notas de lanzamiento. Nunca borres el volumen de configuración durante la actualización, ya que contiene la base de datos, los usuarios y los ajustes persistentes.

Errores frecuentes al instalar Authelia con Docker

Uno de los fallos más habituales es que la red externa no exista. Si Docker muestra network proxy declared as external, but could not be found, créala con:

docker network create proxy

Si aparece un error de permisos sobre /config o /secrets, comprueba que los identificadores incluidos en .env coincidan con la propiedad de las carpetas. Puedes verificarlos mediante id -u e id -g.

Otro problema frecuente consiste en definir un secreto dos veces. Cuando utilizas variables como AUTHELIA_SESSION_SECRET_FILE, no debes incluir el mismo valor dentro de configuration.yml.

Si Authelia no acepta la contraseña, revisa el archivo users_database.yml. El campo password debe contener únicamente el hash completo que comienza por $argon2id$. No incluyas Digest: ni cortes la cadena en varias líneas.

Cuando el contenedor funciona pero el portal no carga, recuerda que expose no publica el puerto en el host. El proxy debe estar conectado a la misma red y utilizar authelia como nombre del servidor. Los errores posteriores de redirección, cabeceras o autenticación pertenecen a la configuración del proxy, no a la instalación del contenedor.

Por último, si utilizas SQLite, no intentes ejecutar varias réplicas de Authelia sobre el mismo archivo. Para un despliegue distribuido necesitas una base de datos externa y un proveedor de sesiones compartido.

Instalar Authelia con Docker Compose permite crear una base sólida para centralizar la autenticación sin exponer directamente sus puertos. Al separar la configuración, los secretos y los datos persistentes, el servicio puede actualizarse de manera controlada y ampliarse posteriormente con un proxy inverso, reglas de acceso, autenticación multifactor u OpenID Connect.