¿Qué es TinyAuth y por qué encaja tan bien con Pocket-ID?

TinyAuth es un servicio ligero que actúa como capa de autenticación delante de tus aplicaciones, integrándose con proxies como Traefik mediante middleware de forwardAuth. En lugar de que cada servicio hable directamente OIDC, delegas esa lógica en TinyAuth y éste se conecta a tu proveedor OAuth/OIDC preferido.

En nuestro caso, ese proveedor será Pocket-ID, que ya conoces: un IdP compatible con OpenID Connect, pensado para autoalojarse y basado exclusivamente en Passkeys, sin contraseñas tradicionales.

Para este tutorial, lo conectaremos directamente con Traefik, de tal forma que todas las apps que tengamos enlazadas con él podrán estar tras un muro de autenticación. Útil para aquellas que no disponen de ningún método de autenticación y queremos que no estén disponibles para cualquiera en nuestra red.

La combinación queda así:

Traefik recibe la petición al servicio.
Traefik la envía a TinyAuth (middleware de forwardAuth).
TinyAuth redirige a Pocket-ID para autenticarse con Passkeys.
Al volver, TinyAuth valida al usuario y, si cumple las reglas, redirige a la aplicación.

En este ejemplo concreto, la aplicación será el propio dashboard de Traefik (en lugar de securizarlo con una autenticación básica de usuario y contraseña). De esta forma tendremos el dashboard de Traefik protegido con la misma experiencia de login sin contraseñas que ya usamos en otros servicios que están integrados directamente con Pocket-ID.

Requisitos previos

Antes de empezar, necesitamos tener:

Pocket-ID desplegado y accesible por HTTPS (por ejemplo https://auth.midominio.es).
Traefik ya funcionando, sirviendo el dashboard vía HTTPS detrás de un dominio (por ejemplo https://traefik.dominiolocal.duckdns.org).
Un host (o stack Docker) donde desplegar TinyAuth.

Si ya seguiste la guía previa de Pocket-ID, puedes reutilizar el mismo dominio de autenticación y las Passkeys existentes.

Paso 1: Crear el cliente OIDC para TinyAuth en Pocket-ID

Primero, vamos a decirle a Pocket-ID que TinyAuth será una nueva aplicación que usará OIDC:

Entramos al panel de administración de Pocket-ID (https://auth.midominio.es).
Vamos a la pestaña OIDC Clients.
Pulsamos en Add OIDC Client.
Rellena los campos:
- Name: por ejemplo TinyAuth. Será el nombre que nos aparecerá en la pantalla cuando queramos hacer login.
- Callback URLs: la URL pública de TinyAuth seguida de
  /api/oauth/callback/pocketid.Por ejemplo: https://auth.midominio.es/api/oauth/callback/pocketid
- El resto de campos son opcionales y puedes editarlos más tarde, si quieres.
Guarda el cliente y anota el Client ID y el Client Secret que se mostrarán en la siguiente pantalla.

Configuración del servicio en Pocket-ID

Paso 2: Desplegar TinyAuth conectado a Pocket-ID

Lo más habitual es desplegar TinyAuth vía Docker. A continuación tienes un ejemplo de docker-compose.yml mínimo, ya preparado para hablar con Pocket-ID:

services:
  tinyauth:
    image: ghcr.io/steveiliop56/tinyauth:latest
    container_name: tinyauth
    restart: unless-stopped
    environment:
        # Log level puede ir desde -1 a 6
      - #LOG_LEVEL=0
      - SECRET= <Secreto_generado>
      - APP_URL=https://auth.dominiolocal.duckdns.org
      - APP_TITLE=Tiny Auth       
        # Config del OIDC
      - PROVIDERS_POCKETID_AUTH_URL=https://auth.dominio.es/authorize
      - PROVIDERS_POCKETID_CLIENT_ID=<PocketIdClientId>
      - PROVIDERS_POCKETID_CLIENT_SECRET=<PocketIdClientSecret>
      - PROVIDERS_POCKETID_NAME=PocketID
      - PROVIDERS_POCKETID_REDIRECT_URL=https://auth.dominiolocal.duckdns.org/api/oauth/callback/pocketid
      - PROVIDERS_POCKETID_SCOPES=openid email profile groups
      - PROVIDERS_POCKETID_TOKEN_URL=https://auth.dominio.es/api/oidc/token
      - PROVIDERS_POCKETID_USER_INFO_URL=https://auth.dominio.es/api/oidc/userinfo
      - OAUTH_AUTO_REDIRECT=pocketid
      - DISABLE_CONTINUE=true

    networks:
      - traefik_proxy
    volumes:
      - ./data:/data
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.tinyauth.rule=Host(`auth.dominiolocal.duckdns.org`)"
      - "traefik.http.routers.tinyauth.entrypoints=websecure"
      - "traefik.http.routers.tinyauth.tls.certresolver=le"
      - "traefik.http.services.tinyauth.loadbalancer.server.port=3000"
#      - "traefik.http.middlewares.tinyauth.forwardauth.address=http://tinyauth:3000/api/auth/traefik"

networks:
  traefik_proxy:
    external: true

Fichero docker-compose.yml para TinyAuth

Algunos puntos clave:

Las variables PROVIDERS_POCKETID_* siguen la guía oficial de TinyAuth para Pocket-ID.
OAUTH_AUTO_REDIRECT=pocketid hace que, al acceder a una app protegida, TinyAuth te lleve directamente a Pocket-ID sin mostrar un selector de proveedor.
Puedes usar OAUTH_WHITELIST si quieres que solo algunos usuarios (por email) puedan autenticarse, aunque más adelante veremos cómo hacerlo de forma más limpia usando grupos.
SECRET es una variable de entorno esencial en TinyAuth que actúa como clave secreta para firmar sesiones y garantizar la seguridad de la autenticación. Debe ser una cadena aleatoria de 32 caracteres (no bytes) y se puede generar con el siguiente comando:

openssl rand -base64 32 | tr -dc 'a-zA-Z0-9' | head -c 32

Comando para generar el secreto de TinyAuth

Una vez guardado el fichero, bastará con un docker compose up -d para tenerlo disponible y funcionando.

Paso 3: Crear el grupo de administradores en Pocket-ID

Vamos a aprovechar que Pocket-ID soporta grupos de usuarios para limitar el acceso al dashboard de Traefik solo a administradores.

En Pocket-ID, entramos en User Groups.
Pulsamos Add Group y creamos un grupo con nombre, por ejemplo, admins.
Añadimos al grupo los usuarios que podrán acceder al dashboard de Traefik.

Volviendo a la configuración del cliente en Pocket-ID, le asignaremos este grupo para que sólo pueda autorizar a aquellos que estén en él:

Asignación del grupo Admins al cliente de TinyAuth

Paso 4: Configurar TinyAuth para el dashboard de Traefik

TinyAuth funciona a base de labels asociadas a las aplicaciones que queremos proteger. Vamos a decirle que el dashboard de Traefik requiere pertenecer al grupo admins de Pocket-ID.

En mi caso, toda la configuración de Traefik está en ficheros YML, por lo que deberemos, primero, crear el middleware de TinyAuth y agregarlo a la ruta del dashboard:

http:
  middlewares:
    tinyauth:
      forwardauth:
        address: http://tinyauth:3000/api/auth/traefik
        trustForwardHeader: true
  routers:
    dashboard:
      rule: Host(`traefik.dominiolocal.duckdns.org`) && (PathPrefix(`/api`) || PathPrefix(`/dashboard`))
      entryPoints:
        - websecure
      service: api@internal
      tls:
        certResolver: le
      middlewares:
        - tinyauth

Configuración para crear y utilizar el middleware de TInyAuth en Traefik

Paso 5: Probar el acceso con Passkeys

Una vez reiniciados Traefik y TinyAuth, ya podemos probar el flujo completo:

Abrimos https://traefik.dominiolocal.duckdns.org en el navegador.
Nos redirigirá a TinyAuth y, automáticamente, a Pocket-ID gracias a OAUTH_AUTO_REDIRECT.
Pocket-ID pedirá que nos autentiquemos con nuestra Passkey (Yubikey, Vaultwarden, huella en el móvil, etc.).
Si pertenecemos al grupo admins, TinyAuth aceptará la sesión y devolverá la petición a Traefik, mostrando el dashboard.
Si no estamos en el grupo, veremos una página de acceso no autorizado.

A partir de aquí, cada vez que queramos proteger un nuevo servicio detrás de Traefik, solo tendremos que añadir el middleware de tinyauth a la configuración de su route y estará protegido. Todo ello manteniendo el mismo modelo de autenticación sin contraseñas que ya estamos usando en el resto de nuestros servicios conectados a Pocket-ID.

Conclusión: un paso más hacia un mundo sin contraseñas

La combinación de Pocket-ID, TinyAuth y Traefik nos permite centralizar la autenticación en nuestro homelab, manteniendo el dashboard de Traefik (y cualquier otro servicio) bajo un acceso unificado con Passkeys.

Si ya diste el salto a Pocket-ID, añadir TinyAuth encima de Traefik es un cambio pequeño en configuración, pero un avance enorme en comodidad y seguridad del día a día.

Si te ha gustado la entrada, o te ha sido útil y quieres ayudarme a pagar los gastos que conlleva el servidor y mantener así el blog libre completamente de anuncios, puedes hacer una donación pulsando sobre el siguiente botón:

❤️ Donar