Autenticación Básica en Traefik: Protege Tus Servicios Docker

Si ejecutas servicios Docker autoalojados detrás de Traefik, probablemente tengas algunos endpoints que no tienen autenticación propia: el panel de Traefik, un contenedor whoami, quizá algunas herramientas internas de desarrollo. Exponerlos a internet sin ningún control de acceso es un riesgo que no necesitas asumir.

El middleware de autenticación básica de Traefik añade un aviso de usuario/contraseña delante de cualquier servicio con solo un par de etiquetas Docker. No sustituye a una autenticación propia a nivel de aplicación, pero para herramientas de desarrollo y servicios internos es una primera capa rápida.

Esta guía cubre la configuración completa: generar contraseñas bcrypt seguras, añadir etiquetas de autenticación en Docker Compose, usar usersFile para configuraciones con varios servicios, personalizar el aviso de inicio de sesión, encadenar middlewares para defensa en profundidad y proteger el propio panel de Traefik. Todo está pensado para Traefik v3.x (la rama estable actual).

Si buscas más contenedores Docker que proteger, echa un vistazo a los mejores contenedores Docker autoalojados para un home server.

Middleware de autenticación básica de Traefik protegiendo servicios Docker con un aviso de inicio de sesión

Entendiendo el middleware de autenticación básica de Traefik

El middleware de Traefik se sitúa entre el cliente y tu servicio backend. Cuando llega una petición, Traefik la pasa por la cadena de middlewares antes de reenviarla al backend. La autenticación básica es uno de los muchos tipos de middleware. Intercepta la petición, comprueba las credenciales y deja pasar la petición o devuelve una respuesta 401 Unauthorized.

El flujo es así:

1. El cliente envía la petición a https://myapp.example.com
2. Traefik comprueba los middlewares: encuentra un middleware de autenticación básica en esta ruta
3. ¿Sin credenciales? Traefik devuelve 401 Unauthorized con una cabecera WWW-Authenticate
4. El navegador muestra el aviso de inicio de sesión: el usuario introduce usuario y contraseña
5. El cliente reenvía la petición con la cabecera Authorization: Basic <base64-encoded>
6. Traefik verifica el hash contra las entradas htpasswd configuradas
7. ¿Credenciales válidas? Traefik reenvía la petición al backend
8. ¿Credenciales inválidas? Traefik devuelve 401 de nuevo

Las credenciales de autenticación básica van codificadas en Base64, no cifradas. Eso significa que cualquiera que intercepte el tráfico (sin HTTPS) puede decodificarlas sin esfuerzo. Usa siempre la autenticación básica sobre HTTPS. Si tus servicios están detrás de Traefik, ya deberías tener TLS configurado.

Cómo configurar la autenticación básica de Traefik en Docker Compose

Esto asume que Traefik ya se ejecuta en Docker con el proveedor de Docker activado. Si todavía no lo has configurado, consulta primero la guía de Traefik como proxy inverso en Docker.

Requisitos previos

Paso 1: Genera contraseñas bcrypt con htpasswd

Instala la utilidad htpasswd:

# Debian/Ubuntu
sudo apt update && sudo apt install apache2-utils

# RHEL/Fedora
# sudo dnf install httpd-tools

Genera un hash bcrypt:

# The interactive prompt keeps the password out of your shell history
echo $(htpasswd -nB admin) | sed -e 's/\$/\$\$/g'

admin:$$2y$$05$$...

# Fine for testing. Avoid in production, password ends up in shell history.
echo $(htpasswd -nBC 12 admin MySecurePass) | sed -e 's/\$/\$\$/g'

Qué está pasando aquí:

• -nB: -n imprime en stdout en lugar de un archivo, -B usa bcrypt
• -C 12: factor de coste opcional (2^12 rondas). El valor por defecto suele ser 5. Un valor más alto es más lento pero más resistente a la fuerza bruta. 12 es un valor razonable para producción.
• sed -e 's/\$/\$\$/g': duplica cada $ porque Docker Compose interpreta $VAR como sustitución de variables de entorno. Sin esto, el hash queda corrupto al arrancar.

Paso 2: Añade las etiquetas de autenticación básica a tu servicio Docker

Necesitas dos etiquetas por servicio: una para referenciar el middleware y otra para definirlo.

services:
  nginx:
    image: nginx:latest
    restart: unless-stopped
    env_file: .env
    networks:
      - traefik-net
    labels:
      - traefik.enable=true
      - traefik.http.routers.nginx.rule=Host(`nginx.example.com`)
      - traefik.http.routers.nginx.entrypoints=https
      - traefik.http.services.nginx.loadbalancer.server.port=80
      # Basic auth middleware
      - traefik.http.routers.nginx.middlewares=nginx-auth
      - traefik.http.middlewares.nginx-auth.basicauth.users=${TRAEFIK_USER_PASS}
      - traefik.http.middlewares.nginx-auth.basicauth.realm=Restricted Area
      - traefik.http.middlewares.nginx-auth.basicauth.removeheader=true
networks:
  traefik-net:
    external: true

Puntos clave:

• El nombre del middleware debe coincidir entre la referencia del router (nginx-auth) y la definición del middleware (nginx-auth). Esta es la causa n.º 1 de los errores de «la autenticación no funciona». Una errata aquí hace que Traefik ignore el middleware sin avisar.
• Usa nombres de middleware únicos por servicio. Si dos servicios usan el mismo nombre de middleware con listas de usuarios distintas, uno sobrescribirá al otro sin avisar.
• Pon las etiquetas entre comillas. Sin comillas, YAML puede fallar con los caracteres especiales.

Comprueba que funciona:

# Should return 401 Unauthorized
curl -I https://nginx.example.com

# Should return 200 with correct credentials
curl -I -u admin:yourpassword https://nginx.example.com

Paso 3: Guarda las credenciales en un archivo .env

Escribir el hash de la contraseña directamente en docker-compose.yml funciona, pero mete credenciales en el control de versiones y hace que rotarlas sea un dolor. Muévelas a un archivo .env en su lugar.

# .env (in the same directory as docker-compose.yml)
TRAEFIK_USER_PASS=admin:$$2y$$05$$KJ3RixvQ.Zabc123...rest_of_hash

Fíjate en el doblado de $$. Docker Compose sigue evaluando este archivo como sustitución de variables de entorno. Tu docker-compose.yml lo referencia con ${TRAEFIK_USER_PASS}, como se muestra en el paso 2.

Paso 4: Usa usersFile para varios servicios

Cuando tienes varios servicios que comparten las mismas credenciales, las etiquetas users en línea se vuelven repetitivas. El enfoque con usersFile te permite mantener un único archivo de texto plano que Traefik lee al arrancar.

Crea el archivo de usuarios:

# ./traefik-data/users.txt
# Each line is username:hash, standard htpasswd format
# NO $$ doubling needed here, this is a plain text file, not YAML
admin:$2y$05$KJ3RixvQ.Zabc123...
viewer:$2y$05$AnotherHash...

Móntalo en el contenedor de Traefik (no en el contenedor del servicio):

# In Traefik's docker-compose.yml
services:
  traefik:
    image: traefik:v3.3
    volumes:
      - ./traefik-data/users.txt:/etc/traefik/users.txt:ro
      # ... other volumes

Referéncialo en las etiquetas del servicio:

# In any service's docker-compose.yml
labels:
  - traefik.http.routers.myapp.middlewares=myapp-auth
  - traefik.http.middlewares.myapp-auth.basicauth.usersfile=/etc/traefik/users.txt
  - traefik.http.middlewares.myapp-auth.basicauth.realm=My App

docker exec traefik cat /etc/traefik/users.txt

Nota sobre precedencia: si defines users y usersFile en el mismo middleware, los valores de users tienen prioridad sobre usersFile en el Traefik v3.x actual. De v3.1 a v3.3, usersFile tenía prioridad — el cambio se produjo en una versión posterior de v3.x, así que el comportamiento depende de tu versión.

Paso 5: Personaliza el aviso de inicio de sesión con realm

Por defecto, el diálogo de autenticación básica del navegador muestra «traefik» como nombre del realm. Puedes personalizarlo con la opción realm:

labels:
  - "traefik.http.middlewares.my-auth.basicauth.realm=My App - Restricted Access"

Es una pequeña mejora de UX, pero hace que el aviso parezca intencionado y no el de fábrica. Los usuarios ven «My App - Restricted Access» en lugar de «traefik» en el diálogo de inicio de sesión.

Paso 6: Elimina la cabecera Authorization por seguridad

Por defecto, Traefik reenvía la cabecera Authorization (que contiene las credenciales codificadas en Base64) a tu servicio backend. Si tu backend no la necesita, quítala:

labels:
  - "traefik.http.middlewares.my-auth.basicauth.removeheader=true"

Por qué importa: si tu servicio backend registra las cabeceras de las peticiones (y la mayoría lo hace), no quieres credenciales acabando en esos logs. Defensa en profundidad: elimina lo que no necesitas.

Paso 7: Pasa el nombre de usuario autenticado a los backends

Si tu backend necesita saber quién se autenticó, usa headerField para establecer una cabecera personalizada con el nombre de usuario:

labels:
  - "traefik.http.middlewares.my-auth.basicauth.headerField=X-WebAuth-User"

Esto añade X-WebAuth-User: <username> a las peticiones proxied. Útil para logging, comportamiento por usuario o control de acceso sencillo en aplicaciones sin autenticación propia.

Encadenar middlewares de Traefik para defensa en profundidad

La autenticación básica por sí sola es una sola capa. Para servicios expuestos a internet, encadénala con limitación de tasa y listas blancas de IPs.

Autenticación básica + limitación de tasa

labels:
  - traefik.enable=true
  - traefik.http.routers.myapp.rule=Host(`myapp.example.com`)
  - traefik.http.routers.myapp.entrypoints=https
  - traefik.http.routers.myapp.middlewares=rate-limit@docker,my-auth@docker
  # Rate limiting
  - traefik.http.middlewares.rate-limit.ratelimit.average=100
  - traefik.http.middlewares.rate-limit.ratelimit.burst=50
  # Basic auth
  - traefik.http.middlewares.my-auth.basicauth.users=${TRAEFIK_USER_PASS}
  - traefik.http.middlewares.my-auth.basicauth.removeheader=true
  - traefik.http.middlewares.my-auth.basicauth.realm=My App

Esto limita el servicio a una media de 100 peticiones/segundo con picos de hasta 50, y exige autenticación.

Autenticación básica + lista blanca de IPs

labels:
  - traefik.http.routers.myapp.middlewares=local-only@docker,my-auth@docker
  # Allow only private networks
  - traefik.http.middlewares.local-only.ipallowlist.sourcerange=10.0.0.0/8,192.168.0.0/16
  # Basic auth
  - traefik.http.middlewares.my-auth.basicauth.users=${TRAEFIK_USER_PASS}

Nota: ipWhiteList pasó a llamarse ipAllowList en Traefik v3. Si migras desde v2, actualiza los nombres de las etiquetas.

Para una seguridad de servidor más amplia incluyendo la integración con CrowdSec, consulta cómo securizar un VPS con CrowdSec.

Proteger solo rutas específicas

Caso de uso: proteger /admin pero dejar /public abierto. Define dos routers en el mismo host:

labels:
  # Public router — no auth
  - traefik.http.routers.myapp.rule=Host(`myapp.example.com`)
  - traefik.http.routers.myapp.entrypoints=https
  # Admin router — with auth, higher priority
  - traefik.http.routers.myapp-admin.rule=Host(`myapp.example.com`) && PathPrefix(`/admin`)
  - traefik.http.routers.myapp-admin.entrypoints=https
  - traefik.http.routers.myapp-admin.priority=10
  - traefik.http.routers.myapp-admin.middlewares=admin-auth
  - traefik.http.middlewares.admin-auth.basicauth.users=${TRAEFIK_USER_PASS}

El router más específico (/admin) necesita un valor de prioridad más alto para coincidir primero. La prioridad por defecto de Traefik se calcula a partir de la longitud de la regla, pero los valores explícitos son más fiables.

Proteger el panel de Traefik con autenticación básica

Uno de los casos de uso más comunes: securizar el propio panel de Traefik. Añade estas etiquetas al contenedor de Traefik:

services:
  traefik:
    image: traefik:v3.3
    command:
      - --api.dashboard=true
      - --providers.docker=true
      # ... other args
    labels:
      - traefik.enable=true
      - traefik.http.routers.dashboard.rule=Host(`traefik.example.com`)
      - traefik.http.routers.dashboard.service=api@internal
      - traefik.http.routers.dashboard.entrypoints=https
      - traefik.http.routers.dashboard.middlewares=dashboard-auth
      - traefik.http.middlewares.dashboard-auth.basicauth.users=${TRAEFIK_DASHBOARD_USERS}
      - traefik.http.middlewares.dashboard-auth.basicauth.realm=Traefik Dashboard
      - traefik.http.middlewares.dashboard-auth.basicauth.removeheader=true
    networks:
      - traefik-net

Usa una variable de entorno distinta para las credenciales del panel (TRAEFIK_DASHBOARD_USERS): no compartas la misma contraseña entre todos tus servicios.

Comprueba: abre https://traefik.example.com en tu navegador. Deberías ver un aviso de inicio de sesión. Tras introducir las credenciales, el panel de Traefik debería cargar.

Problemas comunes y solución de errores

# Generate a fresh bcrypt hash
echo $(htpasswd -nBC 12 admin) | sed -e 's/\$/\$\$/g'

# Test with curl (should return 200)
curl -I -u admin:yourpassword https://myapp.example.com

# WRONG — names don't match:
- "traefik.http.routers.myapp.middlewares=traefik-auth"
- "traefik.http.middlewares.traefiknas-auth.basicauth.users=..."

# RIGHT — names match exactly:
- "traefik.http.routers.myapp.middlewares=myapp-auth"
- "traefik.http.middlewares.myapp-auth.basicauth.users=..."

docker exec traefik cat /etc/traefik/users.txt

volumes:
  - ./traefik-data/users.txt:/etc/traefik/users.txt:ro

docker logs traefik 2>&1 | grep -i "middleware"

# On the host (Debian/Ubuntu)
sudo apt install apache2-utils
echo $(htpasswd -nBC 12 admin) | sed -e 's/\$/\$\$/g'

# Or via Docker
docker run --rm -it alpine:latest sh -c "apk add --no-cache apache2-utils && htpasswd -nBC 12 admin"

Lista rápida de verificación

Después de configurar la autenticación, ejecuta estos comandos para confirmar que todo funciona:

# Should return 401 Unauthorized (no credentials)
curl -I https://myapp.example.com

# Should return 200 OK (with correct credentials)
curl -I -u admin:yourpassword https://myapp.example.com

# Check Traefik logs for auth-related entries
docker logs traefik 2>&1 | grep -i "authentication"

Limitaciones de la autenticación básica

Conclusión

El middleware de autenticación básica de Traefik es una forma rápida de añadir control de acceso a servicios Docker que no tienen autenticación propia. Con hashing de contraseñas bcrypt, el enfoque usersFile para credenciales compartidas y el encadenamiento de middlewares con limitación de tasa o listas blancas de IPs, obtienes una primera capa de protección sólida.

Esto es lo que hemos visto:

• Generar contraseñas bcrypt seguras con htpasswd -nB
• Añadir etiquetas de autenticación a servicios de Docker Compose
• Usar archivos .env y usersFile para gestionar credenciales
• Personalizar el aviso de inicio de sesión con realm
• Eliminar la cabecera Authorization con removeHeader
• Pasar el nombre de usuario autenticado a los backends con headerField
• Encadenar middlewares para defensa en profundidad
• Proteger el panel de Traefik

Si todavía estás configurando Traefik, empieza con la guía de Traefik como proxy inverso en Docker y configura certificados wildcard. Para más servicios que proteger detrás de autenticación, consulta los mejores contenedores Docker para un home server. Si prefieres una plataforma de despliegue gestionada, echa un vistazo a autoalojar con Dokploy.

¿Necesitas un VPS fiable donde ejecutar todo esto? Hetzner ofrece hosting VPS asequible con un rendimiento sólido para stacks Docker autoalojados.

Los precios de los VPS subieron en toda la línea en 2026 — si estás replanteándote un servidor alquilado, consulta qué cambió y cuándo gana un mini PC.