Zum Hauptinhalt springen

Caddy

casdoor-forward-auth stellt Casdoor Single Sign-On vor jeden Dienst hinter Caddy, ohne den Dienst selbst zu ändern. Caddy fragt casdoor-forward-auth über jede Anfrage durch seine integrierte forward_auth-Direktive ab: Angemeldete Benutzer erreichen den Dienst mit ihrer Identität in den Request-Headern, alle anderen werden zuerst zur Casdoor-Anmeldeseite weitergeleitet.

Derselbe Dienst funktioniert auch mit Traefik und Nginx. Die Einrichtung auf dieser Seite wurde end-to-end mit Caddy v2.11 und casdoor-forward-auth v2.0 getestet.

Wie es funktioniert​

  1. Caddy sendet jede Anfrage für eine geschützte Site an /auth von casdoor-forward-auth.
  2. Mit einem gültigen Session-Cookie antwortet /auth mit 200 und Headern wie X-Forwarded-User, und Caddy kopiert diese in die Anfrage an Ihren Dienst.
  3. Ohne Sitzung werden Seitenaufrufe (GET, HEAD) zu Casdoor umgeleitet. Andere Anfragen (POST, PUT, ...) erhalten 401, da sie einer Login-Umleitung nicht folgen können. Caddy gibt diese Antworten unverändert an den Browser zurück.
  4. Nach dem Login leitet Casdoor zu /callback um. casdoor-forward-auth prüft den state, tauscht den Autorisierungscode aus, verifiziert das Access Token, speichert den Benutzer in einem signierten HttpOnly Session-Cookie und schickt den Benutzer zurück zur angeforderten Seite.

Voraussetzungen​

  • Caddy v2
  • Eine Casdoor-Instanz (siehe Server Installation)
  • Zwei Hostnamen, die auf Caddy zeigen, z. B. auth.example.com für casdoor-forward-auth und app.example.com für den geschützten Dienst

Schritt 1: Konfigurieren Sie die Casdoor-Anwendung​

  1. Erstellen oder bearbeiten Sie eine Anwendung in Casdoor.

  2. Fügen Sie den Callback von casdoor-forward-auth zu Redirect URLs hinzu:

    https://auth.example.com/callback
  3. Notieren Sie sich Client ID und Client secret.

Schritt 2: Stellen Sie casdoor-forward-auth und Caddy bereit​

Erstellen Sie eine 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 ist der Dienst, den Sie schützen. Um weitere Dienste zu schützen, geben Sie jeder Site denselben forward_auth-Block. Setzen Sie forward_auth nicht auf die Site von casdoor-forward-auth selbst.

Erstellen Sie eine 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:

Ersetzen Sie die Platzhalter:

  • CASDOOR_ENDPOINT: Die URL Ihres Casdoor-Servers
  • CLIENT_ID und CLIENT_SECRET: Die Werte aus Schritt 1
  • EXTERNAL_URL: Die öffentliche URL von casdoor-forward-auth. <EXTERNAL_URL>/callback muss eine Redirect URL der Anwendung sein
  • COOKIE_DOMAIN: Die übergeordnete Domain der geschützten Hosts, damit das Session-Cookie an alle gesendet wird
  • COOKIE_SECRET: Ein zufälliges Secret, z. B. aus openssl rand -hex 32. Halten Sie es stabil: Eine Änderung meldet alle Benutzer ab

Caddy erhält automatisch HTTPS-Zertifikate für beide Hosts. Starten Sie die Dienste:

docker compose up -d

Schritt 3: Testen Sie die Integration​

  1. Öffnen Sie den geschützten Dienst, z. B. https://app.example.com.
  2. Sie werden zur Casdoor-Anmeldeseite umgeleitet.
  3. Nach der Anmeldung sind Sie wieder auf der geöffneten Seite, und der Dienst erhält die Identitäts-Header. traefik/whoami gibt diese aus, sodass Sie sie dort überprüfen können.

Identitäts-Header​

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 gibt immer alle Header zurück, möglicherweise leer, sodass copy_headers von Caddy alles ersetzt, was der Client in denselben Headern gesendet hat. Stellen Sie sicher, dass der geschützte Dienst nur über Caddy erreichbar ist, sonst kann jeder diese Header direkt senden.

Zugriff einschränken​

Standardmäßig wird jeder Benutzer zugelassen, der sich bei der Casdoor-Anwendung anmelden kann. Um nur Benutzer mit bestimmten Casdoor-Rollen oder Gruppen zuzulassen, fügen Sie roles und/oder groups (durch Komma getrennt) zum uri dieser Site hinzu:

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
}

Ein Benutzer wird zugelassen, wenn er mindestens eine der aufgeführten Rollen besitzt und, falls groups angegeben ist (z. B. groups=built-in/dev), mindestens eine der aufgeführten Gruppen. Alle anderen angemeldeten Benutzer erhalten 403. Jede Site kann ihre eigene Regel haben; die Umgebungsvariablen ALLOWED_ROLES und ALLOWED_GROUPS setzen eine Regel für alle Sites.

Dies deckt auch das Szenario "erst registrieren, später Zugriff erhalten" ab: Neue Benutzer, z. B. über Google-Registrierung, haben keine Rolle und erhalten 403, bis ein Administrator ihnen eine auf der Roles-Seite von Casdoor zuweist. Rollen und Gruppen werden beim Login gelesen, daher muss der Benutzer nach einer Änderung https://auth.example.com/logout öffnen und sich erneut anmelden oder auf das Ende der Sitzung warten (SESSION_TTL).

Konfiguration und Abmeldung​

casdoor-forward-auth wird mit denselben Umgebungsvariablen für jeden Reverse Proxy konfiguriert; siehe Configuration auf der Traefik-Seite. /logout löscht die casdoor-forward-auth-Sitzung (mit ?rd=<url>, um danach weiterzuleiten); der Benutzer bleibt bei Casdoor angemeldet.