Saltar al contenido principal

Caddy

casdoor-forward-auth coloca el inicio de sesión único de Casdoor delante de cualquier servicio detrás de Caddy, sin modificar el servicio. Caddy consulta a casdoor-forward-auth sobre cada solicitud mediante su directiva integrada forward_auth: los usuarios con sesión iniciada acceden al servicio con su identidad en las cabeceras de la solicitud, mientras que los demás son redirigidos primero a la página de inicio de sesión de Casdoor.

El mismo servicio también funciona con Traefik y Nginx. La configuración de esta página fue probada de extremo a extremo con Caddy v2.11 y casdoor-forward-auth v2.0.

Cómo funciona​

  1. Caddy envía cada solicitud para un sitio protegido a /auth de casdoor-forward-auth.
  2. Con una cookie de sesión válida, /auth responde con 200 y cabeceras como X-Forwarded-User, y Caddy las copia en la solicitud hacia su servicio.
  3. Sin sesión, las cargas de páginas (GET, HEAD) se redirigen a Casdoor. Otras solicitudes (POST, PUT, ...) reciben 401, ya que no pueden seguir una redirección de inicio de sesión. Caddy devuelve estas respuestas al navegador sin cambios.
  4. Después del inicio de sesión, Casdoor redirige a /callback. casdoor-forward-auth verifica el state, intercambia el código de autorización, valida el token de acceso, almacena al usuario en una cookie de sesión firmada HttpOnly y envía al usuario de vuelta a la página solicitada.

Requisitos previos​

  • Caddy v2
  • Una instancia de Casdoor (consulte Instalación del servidor)
  • Dos nombres de host que apunten a Caddy, p. ej., auth.example.com para casdoor-forward-auth y app.example.com para el servicio protegido

Paso 1: Configurar la aplicación de Casdoor​

  1. Cree o edite una aplicación en Casdoor.

  2. Agregue el callback de casdoor-forward-auth a Redirect URLs:

    https://auth.example.com/callback
  3. Anote el Client ID y el Client secret.

Paso 2: Desplegar casdoor-forward-auth y Caddy​

Cree un Caddyfile:

auth.example.com {
reverse_proxy casdoor-forward-auth:9999
}

app.example.com {
forward_auth casdoor-forward-auth:9999 {
uri /auth
copy_headers X-Forwarded-User X-Forwarded-User-Id X-Forwarded-Organization X-Forwarded-Email X-Forwarded-Groups X-Forwarded-Roles
}
reverse_proxy app:8080
}

app:8080 es el servicio que protege. Para proteger más servicios, asigne a cada sitio el mismo bloque forward_auth. No coloque forward_auth en el sitio de casdoor-forward-auth mismo.

Cree un docker-compose.yml:

services:
caddy:
image: caddy:2
ports:
- "80:80"
- "443:443"
volumes:
- ./Caddyfile:/etc/caddy/Caddyfile:ro
- caddy_data:/data

casdoor-forward-auth:
image: ghcr.io/casdoor/casdoor-forward-auth:latest
environment:
CASDOOR_ENDPOINT: https://door.casdoor.com
CLIENT_ID: <client ID>
CLIENT_SECRET: <client secret>
EXTERNAL_URL: https://auth.example.com
COOKIE_DOMAIN: example.com
COOKIE_SECRET: <random string of at least 32 characters>

app:
image: traefik/whoami
command: --port 8080

volumes:
caddy_data:

Reemplace los marcadores de posición:

  • CASDOOR_ENDPOINT: la URL de su servidor de Casdoor
  • CLIENT_ID y CLIENT_SECRET: los valores del Paso 1
  • EXTERNAL_URL: la URL pública de casdoor-forward-auth. <EXTERNAL_URL>/callback debe ser una Redirect URL de la aplicación
  • COOKIE_DOMAIN: el dominio padre de los hosts protegidos, para que la cookie de sesión se envíe a todos ellos
  • COOKIE_SECRET: un secreto aleatorio, p. ej., generado por openssl rand -hex 32. Manténgalo estable: cambiarlo cerrará la sesión de todos los usuarios

Caddy obtiene automáticamente certificados HTTPS para ambos hosts. Inicie los servicios:

docker compose up -d

Paso 3: Prueba la integración​

  1. Abre el servicio protegido, por ejemplo, https://app.example.com.
  2. Se te redirige a la página de inicio de sesión de Casdoor.
  3. Después de iniciar sesión, vuelves a la página que abriste y el servicio recibe los encabezados de identidad. traefik/whoami los imprime, por lo que puedes verificarlos allí.

Encabezados de identidad​

HeaderValue
X-Forwarded-UserUser name, e.g., alice
X-Forwarded-User-IdUser ID
X-Forwarded-OrganizationOrganization of the user
X-Forwarded-EmailEmail address
X-Forwarded-GroupsComma-separated groups, e.g., built-in/dev,built-in/ops
X-Forwarded-RolesComma-separated role names

casdoor-forward-auth siempre devuelve todos ellos, posiblemente vacíos, por lo que copy_headers de Caddy reemplaza lo que el cliente envió en esos mismos encabezados. Asegúrate de que el servicio protegido solo sea accesible a través de Caddy; de lo contrario, cualquiera puede enviar estos encabezados directamente.

Restricción de acceso​

De forma predeterminada, se permite el acceso a cualquier usuario que pueda iniciar sesión en la aplicación de Casdoor. Para permitir el acceso solo a usuarios con ciertos roles o grupos de Casdoor, añade roles y/o groups (separados por comas) al uri de ese sitio:

app.example.com {
forward_auth casdoor-forward-auth:9999 {
uri /auth?roles=admin,ops
copy_headers X-Forwarded-User X-Forwarded-User-Id X-Forwarded-Organization X-Forwarded-Email X-Forwarded-Groups X-Forwarded-Roles
}
reverse_proxy app:8080
}

Un usuario pasa si tiene al menos uno de los roles listados y, si también se especifican groups (p. ej., groups=built-in/dev), al menos uno de los grupos listados. Cualquier otro usuario autenticado recibirá un error 403. Cada sitio puede tener su propia regla; las variables de entorno ALLOWED_ROLES y ALLOWED_GROUPS establecen una regla para todos los sitios.

Esto también cubre el escenario "regístrate primero, obtén acceso más tarde": los nuevos usuarios, por ejemplo, desde el registro con Google, no tienen ningún rol y reciben un error 403 hasta que un administrador les asigna uno en la página Roles de Casdoor. Los roles y grupos se leen al iniciar sesión, por lo que, tras un cambio, el usuario debe abrir https://auth.example.com/logout e iniciar sesión nuevamente, o esperar a que finalice la sesión (SESSION_TTL).

Configuración y cierre de sesión​

casdoor-forward-auth se configura con las mismas variables de entorno para cada proxy inverso; consulta Configuration en la página de Traefik. /logout limpia la sesión de casdoor-forward-auth (con ?rd=<url> para redirigir después); el usuario permanece conectado a Casdoor.