Instalar Authentik con Docker Compose y Traefik

Un inicio de sesión para todas las aplicaciones alojadas

Authentik es un servidor SSO (inicio de sesión único) autohospedado: los usuarios inician sesión una vez y todas las aplicaciones protegidas aceptan esa sesión en lugar de solicitar su propia contraseña. La instalación usa un archivo oficial de Docker Compose y dos secretos generados. La parte que requiere más atención viene después: apuntar un reverse proxy hacia él y poner una aplicación existente detrás de forward auth.

Authentik se ejecuta como tres servicios definidos en ese archivo de Compose: una base de datos PostgreSQL, un proceso server y un proceso worker. El contenedor del servidor también ejecuta el outpost integrado, que es el componente que responde «¿esta petición tiene una sesión iniciada?» para cada aplicación protegida. La versión 2026.8.5 es la versión actual a fecha de 25 de octubre de 2026. Se publicó el 21 de octubre de 2026 como el último parche de la serie 2026.8, que comenzó con 2026.8.0 el 18 de agosto, y sustituye a 2026.8.4, publicada el 14 de octubre, como etiqueta de imagen predeterminada en el archivo oficial de Compose. El proyecto solicita un host con al menos 2 núcleos de CPU y 2 GB de RAM. Considérelo el mínimo. PostgreSQL y el worker mantienen memoria ocupada después de que el sistema lleva un día encendido.

Requisitos previos

Necesita Docker Engine con el plugin Compose v2, lo cual puede confirmar con docker compose version. Si esto devuelve un error en lugar de una versión, instale el plugin antes de continuar; los conceptos básicos se tratan en ejecución de aplicaciones con Docker Compose en un VPS. También necesita un registro DNS tipo A que apunte al servidor, auth.example.com en los ejemplos siguientes, ya que Authentik construye sus URL de redirección a partir del nombre de host utilizado por el navegador.

Ejecute la pila como un usuario normal en el grupo docker en lugar de como root. La pertenencia a ese grupo equivale a tener privilegios de root en el host, así que asígnelo a una única cuenta de despliegue y a nadie más, siguiendo las pautas de cuentas de usuario con privilegios mínimos en un VPS.

Instalar con el archivo oficial de Compose

sudo install -d -o "$USER" -g "$USER" /opt/authentik
cd /opt/authentik
wget https://docs.goauthentik.io/compose.yml
echo "PG_PASS=$(openssl rand -base64 36 | tr -d '\n')" >> .env
echo "AUTHENTIK_SECRET_KEY=$(openssl rand -base64 60 | tr -d '\n')" >> .env
docker compose pull
docker compose up -d

docker compose ps debe mostrar tres contenedores, todos en ejecución, y postgresql debe informar healthy cuando su comprobación finalice correctamente. El primer arranque ejecuta las migraciones de la base de datos, así que espere un minuto antes de acceder a la interfaz web.

Los dos valores generados son importantes, pero por motivos distintos. PG_PASS es la contraseña de PostgreSQL. La documentación de instalación de Authentik indica que no se admiten contraseñas de más de 99 caracteres, así que mantenga por debajo de ese límite cualquier contraseña que elija; la generada es mucho más corta. AUTHENTIK_SECRET_KEY es la clave que Authentik usa para firmar las cookies, y su documentación de configuración indica que cambiarla invalida las sesiones activas. Por tanto, una clave nueva cerrará la sesión de todos los usuarios autenticados. Mantenga .env con el modo 600 y guarde una copia en un lugar seguro junto con las copias de seguridad, para que una restauración recupere la misma clave con la que se ejecutaba el servidor.

El archivo de Compose marca ambos valores como obligatorios mediante la forma ${VAR:?message}: ${PG_PASS:?database password required} en el servicio PostgreSQL y ${AUTHENTIK_SECRET_KEY:?secret key required} en el servidor y el worker. Esto significa que Compose no inicia si falta el archivo. Ejecutar docker compose up -d desde el directorio incorrecto muestra una línea como required variable AUTHENTIK_SECRET_KEY is missing a value: secret key required y se detiene. Ese mensaje indica un problema de ruta, no de configuración.

Los valores de entorno importantes

Todo lo demás va en el mismo archivo .env. Authentik asigna un doble guion bajo a una clave de configuración anidada, por lo que AUTHENTIK_EMAIL__HOST establece email.host. Un solo guion bajo no se asigna a la clave anidada. Esta es la causa más habitual de que una configuración parezca no tener efecto.

• AUTHENTIK_BOOTSTRAP_PASSWORD establece la contraseña del usuario integrado akadmin durante el primer arranque, por lo que nunca tendrá que introducirla en un formulario web público. AUTHENTIK_BOOTSTRAP_EMAIL y AUTHENTIK_BOOTSTRAP_TOKEN establecen del mismo modo la dirección de ese usuario y un token de API.
• COMPOSE_PORT_HTTP y COMPOSE_PORT_HTTPS cambian los puertos publicados de los valores predeterminados 9000 y 9443.
• AUTHENTIK_EMAIL__HOST, AUTHENTIK_EMAIL__PORT, AUTHENTIK_EMAIL__USERNAME, AUTHENTIK_EMAIL__PASSWORD, AUTHENTIK_EMAIL__USE_TLS y AUTHENTIK_EMAIL__FROM configuran el correo saliente. Sin estos valores, Authentik intenta usar localhost en el puerto 25, por lo que los mensajes para restablecer contraseñas terminan con un error de conexión en el registro del worker.
• AUTHENTIK_LOG_LEVEL=debug activa el nivel de detalle que necesita mientras un flujo de inicio de sesión presenta problemas. Después, vuelva a establecerlo en info.
• AUTHENTIK_ERROR_REPORTING__ENABLED es false de forma predeterminada. Establézcalo en true sólo si acepta enviar informes de fallos al proveedor.

Estos son secretos almacenados en un archivo sin cifrar. Trate el directorio como cualquier otro almacén de credenciales. Un gestor de contraseñas como una instancia de Vaultwarden autohospedada es un lugar más adecuado para guardar la copia de recuperación que una nota en su portátil.

Primer inicio de sesión y cuenta de administración

Abra http://SERVER_IP:9000 en un navegador. Authentik muestra el flujo de configuración inicial y solicita establecer una contraseña para el usuario akadmin predeterminado. Si ya configuró AUTHENTIK_BOOTSTRAP_PASSWORD, ese paso está hecho y accederá directamente a la página de inicio de sesión.

Cree un usuario administrador normal para usted en Directory y después en Users, añádalo al grupo authentik Admins e inicie sesión con esa cuenta. Mantenga akadmin como cuenta de emergencia, con una contraseña larga almacenada sin conexión. Si un flujo o una etapa defectuosos le impiden iniciar sesión, docker compose run --rm server create_recovery_key 10 akadmin, ejecutado desde /opt/authentik, muestra un enlace que inicia sesión directamente como akadmin. Cualquiera que tenga ese enlace obtiene el mismo acceso, así que trátelo como la contraseña. El trabajo diario con una cuenta integrada compartida destruye el registro de auditoría, porque todos los eventos indican akadmin y no identifican a ninguna persona. Este argumento también se aplica después de Authentik: algo como un entorno autohospedado de OneCLI que proporciona su propio agente a cada persona sólo deja un registro legible si la identidad que llega pertenece a una sola persona y no a una cuenta compartida por todo el equipo.

Coloque Authentik detrás de su proxy inverso

Publicar el puerto 9000 en Internet funciona, pero necesita TLS (seguridad de la capa de transporte) y un nombre de host real. Si ya usa la configuración de Traefik como proxy inverso para varias aplicaciones de Compose, conecte Authentik a la misma red externa proxy mediante un archivo de anulación. Cree docker-compose.override.yml junto a compose.yml:

services:
  server:
    networks:
      - default
      - proxy
    labels:
      traefik.enable: "true"
      traefik.docker.network: proxy
      traefik.http.routers.authentik.rule: Host(`auth.example.com`)
      traefik.http.routers.authentik.entrypoints: websecure
      traefik.http.routers.authentik.tls.certresolver: le
      traefik.http.services.authentik.loadbalancer.server.port: "9000"

networks:
  proxy:
    external: true

Aplíquelo con docker compose up -d. Compose combina automáticamente el archivo de anulación, por lo que el servicio server conserva todo lo incluido en el archivo oficial y además obtiene las etiquetas. Compruébelo con curl -I https://auth.example.com/if/user/, que debería responder HTTP/2 200. Un 404 page not found de Traefik indica que ningún router coincidió con la solicitud. Compruebe que las etiquetas hayan llegado al contenedor, que la regla Host() coincida exactamente con el nombre de host y que la solicitud haya llegado al punto de entrada HTTPS en el que escucha el router.

Cuando el nombre de host funcione, vincule los puertos publicados a 127.0.0.1 en el archivo de anulación para que la única forma de acceso sea a través del proxy.

Proteger una aplicación con autenticación directa (forward auth)

El proveedor proxy de Authentik tiene tres modos, y elegir el incorrecto supone perder una hora. Proxy significa que el propio outpost reenvía el tráfico a la aplicación upstream. Forward auth (single application) significa que su propio proxy inverso sigue moviendo el tráfico y solo consulta a Authentik si la petición está autenticada. Forward auth (domain level) protege todas las aplicaciones bajo un dominio padre con un único proveedor, a costa de perder reglas de autorización por aplicación. Con Traefik al frente, usted necesita forward auth (single application). Si busca una aplicación concreta para practicar, algo como un espacio de trabajo AFFiNE autohospedado es un buen primer candidato, ya que es el tipo de herramienta interna que desea que sea accesible desde sus propios dispositivos y desde ningún otro lugar. Una herramienta de equipo refuerza aún más el caso: coloque un servicio de soporte Chatwoot autohospedado detrás del mismo proveedor y cada persona que responda al buzón iniciará sesión una vez al día en lugar de compartir una contraseña más.

En la interfaz web, abra Applications y luego Providers, cree un Proxy Provider, elija el modo forward auth single application y establezca el host externo en https://app.example.com. Cree una Application que apunte a ese proveedor. Luego abra Outposts, edite el authentik Embedded Outpost y mueva la nueva aplicación a sus aplicaciones seleccionadas. El outpost solo responde por las aplicaciones que se le han asignado, por lo que omitir ese último paso es la razón por la que un proveedor configurado correctamente sigue sin devolver nada.

Defina el middleware una vez, en el contenedor de Authentik, y haga referencia a él desde cada aplicación protegida:

      traefik.http.middlewares.authentik.forwardauth.address: http://server:9000/outpost.goauthentik.io/auth/traefik
      traefik.http.middlewares.authentik.forwardauth.trustForwardHeader: "true"
      traefik.http.middlewares.authentik.forwardauth.authResponseHeaders: X-authentik-username,X-authentik-groups,X-authentik-entitlements,X-authentik-email,X-authentik-name,X-authentik-uid,X-authentik-jwt,X-authentik-meta-jwks,X-authentik-meta-outpost,X-authentik-meta-provider,X-authentik-meta-app,X-authentik-meta-version

authResponseHeaders es la lista de cabeceras que Traefik copia de la respuesta de Authentik a la petición que envía upstream. Si la omite, la aplicación sigue protegida, pero nunca sabrá quién es el usuario, por lo que cualquier servicio que lea X-authentik-username para el inicio de sesión automático permanecerá desconectado. Esa brecha es más evidente frente a una aplicación que mantiene su propio inicio de sesión, como un rastreador de ejercicios openGym autohospedado y su inicio de sesión con passkey, donde las cabeceras marcan la diferencia entre un aviso y dos para la misma página.

La aplicación protegida en sí necesita dos routers, no uno:

    labels:
      traefik.enable: "true"
      traefik.http.routers.myapp.rule: Host(`app.example.com`)
      traefik.http.routers.myapp.entrypoints: websecure
      traefik.http.routers.myapp.tls.certresolver: le
      traefik.http.routers.myapp.middlewares: authentik@docker
      traefik.http.routers.myapp-auth.rule: Host(`app.example.com`) && PathPrefix(`/outpost.goauthentik.io/`)
      traefik.http.routers.myapp-auth.entrypoints: websecure
      traefik.http.routers.myapp-auth.tls.certresolver: le
      traefik.http.routers.myapp-auth.priority: "15"
      traefik.http.routers.myapp-auth.service: authentik

El segundo router es la parte que todo el mundo olvida. Tras iniciar sesión, Authentik envía el navegador de vuelta a una ruta bajo /outpost.goauthentik.io/ en el nombre de host de la aplicación, no en auth.example.com. Sin un router que envíe ese prefijo de ruta al servicio de Authentik, la petición llega a su aplicación, que responde con un 404, y el inicio de sesión nunca termina. El valor más alto de priority es lo que hace que la regla de ruta específica prevalezca sobre la regla general Host() en el mismo dominio.

Realice la prueba en una ventana de navegación privada. Debería ser redirigido a auth.example.com, iniciar sesión y volver a la aplicación. docker compose logs -f server en el lado de Authentik imprime un evento de autorización por intento, lo que le indica si la petición llegó a Authentik en algún momento.

Los fallos que encontrará realmente

Bucle de redirección infinito entre la aplicación y la página de inicio de sesión. El host externo en el proveedor no coincide con el que utiliza el navegador, generalmente http:// en el proveedor frente a https:// en la barra de direcciones. La cookie de sesión se establece para un origen diferente, por lo que cada retorno parece una solicitud anónima nueva. Corrija el host externo y borre las cookies de ambos dominios antes de volver a probar.

404 en /outpost.goauthentik.io/start. Falta el router del outpost o su prioridad es menor que la del router comodín para ese host.

La aplicación carga sin solicitar inicio de sesión. La etiqueta middlewares nombra un middleware que no existe. Traefik no advierte sobre esto, por lo que un error tipográfico en authentik@docker simplemente significa que no se ejecuta ningún middleware. Abra el panel de control de Traefik y confirme que el router enumera el middleware.

403 desde Authentik tras un inicio de sesión exitoso. El usuario está autenticado pero no autorizado: la aplicación tiene una vinculación de política o un requisito de grupo que este usuario no cumple. El registro de eventos en la interfaz de administración indica la política que denegó el acceso.

Cuándo encaja mejor Keycloak

Keycloak es el proyecto más antiguo, cuenta con el respaldo de Red Hat y es la opción más sólida para los casos clásicos de identidad empresarial: federación SAML intensiva, gestión de inicios de sesión mediante varios proveedores de identidad externos a la vez, y exportación e importación de realms como ruta de migración documentada. Para algunas organizaciones, el soporte comercial asociado también es importante sobre el papel. La contrapartida es que Keycloak no incluye su propio proxy. Por tanto, para proteger una aplicación que no admita OIDC (OpenID Connect) ni SAML, hay que ejecutar junto a él una solución como oauth2-proxy. El proveedor de proxy integrado de Authentik cubre esa función y ya está integrado. Por eso, la mayoría de los usuarios que administran por sí mismos un conjunto heterogéneo de aplicaciones optan por Authentik.

Copias de seguridad y actualizaciones

Tres elementos hacen posible una restauración: la base de datos PostgreSQL, el directorio ./data y .env.

cd /opt/authentik
docker compose exec -T postgresql pg_dump -U authentik authentik | gzip > authentik-$(date +%F).sql.gz

Guarde ese volcado junto con .env. El volcado no contiene ninguna copia de AUTHENTIK_SECRET_KEY, y restaurar con una clave diferente invalida todas las sesiones activas. Conservar la clave original permite que el servidor restaurado continúe funcionando como antes.

Las actualizaciones consisten en cambiar una etiqueta. Establezca AUTHENTIK_TAG en .env con la versión que quiera y ejecute docker compose pull seguido de docker compose up -d. Si nunca establece AUTHENTIK_TAG, la versión procede del valor predeterminado escrito en el propio compose.yml. Por tanto, descargar una copia más reciente de ese archivo realiza la actualización, que es el procedimiento descrito en la documentación oficial de actualización. Lea primero las notas de la versión. Authentik usa versiones basadas en fechas y, a fecha de octubre de 2026, su documentación indica que las actualizaciones deben seguir la secuencia de las versiones principales: pase al último parche de la serie que ejecuta y después avance por cada serie posterior en orden, sin omitir ninguna. Authentik no admite downgrades, así que haga el volcado de la base de datos antes de ejecutar el pull, no después.

FAQ

¿AuthentiK es gratuito para autohospedarlo?

La edición de código abierto es gratuita e incluye todo lo anterior: el proveedor proxy, forward auth, OIDC (OpenID Connect), SAML y el motor de flujos. Un nivel empresarial de pago añade soporte y algunas funciones empresariales, pero nada de lo descrito aquí requiere una licencia.

¿Necesito Traefik para usar Authentik?

No. Forward auth funciona con nginx mediante auth_request y con Caddy mediante forward_auth. El patrón es el mismo en todos los casos: el reverse proxy consulta a Authentik sobre cada solicitud, y el prefijo de ruta /outpost.goauthentik.io/ del hostname protegido debe dirigir a Authentik en lugar de a la aplicación.

¿Por qué mi aplicación protegida alterna indefinidamente entre el inicio de sesión y el error?

El host externo configurado en el proveedor proxy no coincide con la URL que usa el navegador, normalmente http frente a https. La cookie de sesión se emite para un origen y se lee desde otro, por lo que Authentik recibe una solicitud anónima cada vez. Corrija el host externo y borre después las cookies de ambos hostnames antes de volver a probar.

¿Cuánta RAM necesita Authentik?

El mínimo documentado es 2 núcleos de CPU y 2 GB de RAM a fecha de octubre de 2026, para PostgreSQL, el servidor y el worker en conjunto. En un equipo con 2 GB, la presión de memoria puede activar el OOM killer del kernel, que termina el proceso con la puntuación de badness más alta: aproximadamente la proporción de memoria permitida que utiliza, más su oom_score_adj. Cuando el proceso afectado es el worker, el síntoma es que se detienen las tareas en segundo plano y el correo saliente, mientras la página de inicio de sesión sigue funcionando. Asígnele 4 GB si el mismo servidor también ejecuta las aplicaciones que está protegiendo.