Zum Hauptinhalt springen

OAuth2 Proxy

OAuth2 Proxy ist ein Reverse Proxy, der Benutzer über einen OIDC-Anbieter anmeldet, bevor sie Ihre Anwendung erreichen. Er kann auch als Forward-Auth-Endpunkt von Nginx, Caddy oder Traefik fungieren. Mit Casdoor als Anbieter können Sie nur die Mitglieder einer Casdoor-Gruppe oder die Benutzer zulassen, die eine Casdoor-Rolle innehaben.

Die Konfiguration auf dieser Seite wurde end-to-end mit OAuth2 Proxy v7.15 und Casdoor v4.17 getestet.

Tipp

Wenn Sie nur Casdoor-Anmeldung vor einer Anwendung benötigen und OAuth2 Proxy selbst nicht verwenden müssen, erledigt casdoor-forward-auth dieselbe Aufgabe für Traefik, Caddy und Nginx und übergibt die Gruppen und Rollen des Benutzers in Request-Headern.

Schritt 1: Erstellen Sie die Anwendung in Casdoor​

  1. Fügen Sie in der Organisation Ihrer Benutzer eine Anwendung hinzu (oder öffnen Sie eine vorhandene).

  2. Fügen Sie den Callback von OAuth2 Proxy zu Redirect URLs hinzu:

    https://app.example.com/oauth2/callback
  3. Legen Sie im Tab OIDC/OAuth Folgendes fest:

    • Token format: JWT-Standard
    • Token group format: Name (group), damit Gruppen als devs anstelle von my-org/devs empfangen werden
  4. Speichern Sie die Einstellungen und notieren Sie sich die Client ID und das Client secret.

Warum JWT-Standard: Mit dem Standardformat JWT kann sich ein Benutzer mit nicht verifizierter E-Mail-Adresse nicht anmelden (OAuth2 Proxy lehnt email_verified: false ab, und von Administratoren erstellte Benutzer haben normalerweise eine unverifizierte E-Mail-Adresse), und der Claim roles enthält ganze Rollenobjekte anstelle von Rollennamen. Siehe Was Casdoor sendet.

Schritt 2: Konfigurieren Sie OAuth2 Proxy​

Erstellen Sie oauth2-proxy.cfg:

provider = "oidc"
oidc_issuer_url = "https://door.example.com"
client_id = "<client ID>"
client_secret = "<client secret>"
redirect_url = "https://app.example.com/oauth2/callback"
scope = "openid email profile"
email_domains = ["*"]

cookie_secret = "<random secret>"
http_address = "0.0.0.0:4180"
upstreams = ["http://127.0.0.1:8080"]

# Let in only members of the Casdoor group "devs"
oidc_groups_claim = "groups"
allowed_groups = ["devs"]
  • oidc_issuer_url ist die URL von Casdoor ohne abschließenden Schrägstrich. Es muss exakt der issuer sein, der unter https://door.example.com/.well-known/openid-configuration angezeigt wird. Casdoor erstellt den Issuer aus origin in conf/app.conf oder aus dem Host der Anfrage, wenn origin leer ist; wenn diese beiden unterschiedlich sind, schlägt OAuth2 Proxy mit issuer did not match fehl.
  • cookie_secret muss 16, 24 oder 32 Bytes lang sein, zum Beispiel die Ausgabe von openssl rand -base64 32 | tr -- '+/' '-_'.
  • Behalten Sie den Scope profile bei: Casdoor gibt Gruppen und Rollen vom Userinfo-Endpunkt nur zurück, wenn profile gewährt wird.
  • upstreams ist Ihre Anwendung.

Starten Sie es:

oauth2-proxy --config oauth2-proxy.cfg

Öffnen Sie https://app.example.com. Nach der Anmeldung bei Casdoor erreichen Mitglieder von devs die Anwendung und alle anderen erhalten 403 Forbidden.

Zugriff stattdessen nach Rolle einschränken​

Um stattdessen eine Casdoor-Rolle zu prüfen, lesen Sie den Claim roles:

oidc_groups_claim = "roles"
allowed_groups = ["admin"]

allowed_groups enthält dann Rollennamen, ohne die Organisation.

Prüfen, was OAuth2 Proxy empfangen hat​

Öffnen Sie nach der Anmeldung https://app.example.com/oauth2/userinfo. Es zeigt die Gruppen an, die OAuth2 Proxy extrahiert hat:

{"user":"d1a5f427-...","email":"alice@example.com","groups":["devs"],"preferredUsername":"alice"}

Wenn groups leer ist, hat der Benutzer keine Gruppe oder Rolle in Casdoor oder der Claim-Name ist falsch. Wenn es lange JSON-Zeichenketten wie {"owner":"my-org","name":"admin",...} enthält, verwendet die Anwendung immer noch das Standardformat JWT mit oidc_groups_claim = "roles"; wechseln Sie das Format zu JWT-Standard.

Was Casdoor sendet​

Wie die Gruppen und Rollen des Benutzers OAuth2 Proxy erreichen, hängt vom Token format der Anwendung ab:

Token formatgroupsrolesUnverified email
JWT-Standardfrom userinfo, group namesfrom userinfo, role namessigns in
JWT-Customin the token if Groups is in Token fieldsin the token if you add a token attribute roles (see below)signs in
JWT (default)in the tokenrole objects, not usable for allowed_groupsrejected
JWT-Emptyin the tokenfrom userinfo, role namessigns in

Mit JWT-Standard trägt das Token selbst nur Standard-OIDC-Claims. OAuth2 Proxy sucht jeden Claim, der im Token fehlt, am Userinfo-Endpunkt von Casdoor nach, sodass groups und roles weiterhin eintreffen, einmal pro Anmeldung.

Token group format steuert die Gruppenwerte in allen Formaten: ID (Standard) ergibt my-org/devs, Name ergibt devs und Path ergibt my-org/parent/devs für verschachtelte Gruppen.

Um Rollennamen direkt ins Token aufzunehmen, verwenden Sie JWT-Custom und fügen Sie eine Zeile zu Token attributes hinzu:

NameCategoryValueType
rolesExisting FieldRolesArray

Wenn Token fields nicht leer ist, begrenzt es auch, was das Userinfo-Endpunkt zurückgibt (siehe Token fields). Nehmen Sie Groups auf (und Roles, wenn Sie Rollen aus userinfo lesen), oder lassen Sie es leer.

Wenn Sie das Standardformat JWT beibehalten müssen, fügen Sie insecure_oidc_allow_unverified_email = true hinzu, damit Benutzer mit unverifizierter E-Mail-Adresse sich anmelden können, und beschränken Sie den Zugriff nur auf groups.

Benutzerdaten an Ihre Anwendung übergeben​

OAuth2 Proxy fügt diese Header zu den weitergeleiteten Anfragen hinzu (pass_user_headers, standardmäßig aktiviert):

HeaderValue
X-Forwarded-UserCasdoor user ID (the sub claim)
X-Forwarded-Preferred-UsernameCasdoor-Benutzername, z. B. alice
X-Forwarded-EmailEmail address
X-Forwarded-GroupsGroups (or roles), comma separated

Stellen Sie sicher, dass Ihre Anwendung nur über OAuth2 Proxy erreichbar ist, da sonst jeder diese Header direkt senden kann.

Um OAuth2 Proxy als Forward-Auth-Endpunkt von Nginx (auth_request), Caddy (forward_auth) oder Traefik (forwardAuth) anstelle eines Reverse Proxies zu verwenden, leiten Sie den Proxy auf den Endpunkt /oauth2/auth; siehe Integrations in der OAuth2-Proxy-Dokumentation.

Fehlerbehebung​

SymptomCause and fix
issuer did not match the issuer returned by provider at startupoidc_issuer_url differs from the issuer in Casdoor's discovery document. Set origin in Casdoor's conf/app.conf to its public URL and use the same value here.
500 after sign-in, log says email in id_token ... isn't verifiedThe application uses the default JWT format and the user's email is not verified. Switch to JWT-Standard, or set insecure_oidc_allow_unverified_email = true.
403 Forbidden after sign-inThe user is not in allowed_groups. Open /oauth2/userinfo to see what OAuth2 Proxy received and compare it with Token group format.
Casdoor shows Redirect URI: ... doesn't exist in the allowed Redirect URI listAdd https://app.example.com/oauth2/callback to the application's Redirect URLs.