SSD Nodes Learn Hosting plans →
Anleitungen Matt ConnorVon Matt Connor · Aktualisiert 2026-11-06

SSO für jede App mit oauth2-proxy einrichten

Schützen Sie eine Anwendung ohne eigenen Login mit OIDC: Konfiguration für oauth2-proxy in nginx oder Traefik sowie typische Cookie- und Redirect-Fehler.

Weitergeleitete Authentifizierung: Wie eine Anwendung ohne eigenen Login SSO erhält

oauth2-proxy stellt Single Sign-on für eine Anwendung bereit, die keinen eigenen Login hat. Das funktioniert, weil der vorgeschaltete Reverse Proxy jede Anfrage anhält, oauth2-proxy fragt, ob die Anfrage eine gültige Sitzung enthält, und die Anfrage nur bei positiver Antwort an das Upstream weiterleitet. Der Anwendungscode muss nicht geändert werden, weil die Anwendung diese Prüfung nie sieht.

Die Prüfung ist eine zusätzliche HTTP-Anfrage. Der Proxy sendet eine Kopie der Header der eingehenden Anfrage an /oauth2/auth und liest den Statuscode. 202 bedeutet, dass die Prüfung erfolgreich war. Der Proxy leitet dann die ursprüngliche Anfrage an die Anwendung weiter. 401 bedeutet, dass keine gültige Sitzung vorhanden ist. Der Proxy leitet den Browser dann an /oauth2/sign_in weiter. Dort wird standardmäßig eine Login-Seite angezeigt. /oauth2/start startet einen OpenID-Connect-(OIDC-)Login bei Ihrem Identity Provider. skip_provider_button = true veranlasst /oauth2/sign_in, den Login automatisch zu starten. OIDC ist die Identitätsschicht auf Basis von OAuth 2.0. Der Provider ist das System, das Sie bereits für Logins verwenden.

Dieses Muster hat in jedem Reverse Proxy einen eigenen Namen. Nginx nennt die Direktive auth_request. Traefik nennt die Middleware forwardAuth. Caddy bezeichnet sie als forward_auth. Auch der Dienst, der die Subanfrage beantwortet, kann ausgetauscht werden. oauth2-proxy ist eine verbreitete Wahl, weil es direkt OIDC spricht und keine eigene Datenbank benötigt.

Zeichnen Sie die Vertrauensgrenze, bevor Sie eine Konfiguration schreiben

Nach einer erfolgreichen Prüfung gibt oauth2-proxy die Identität als Response-Header zurück, und der Reverse Proxy übernimmt diese Header in die Upstream-Anfrage. Mit aktiviertem set_xauthrequest erhalten Sie X-Auth-Request-User und X-Auth-Request-Email. Die Anwendung liest diese Header und vertraut ihnen.

Das ist das gesamte Sicherheitsmodell. Die Konsequenz muss daher klar benannt werden: Alles, was eine TCP-Verbindung zum Anwendungsport herstellen kann, kann diese Header selbst setzen und sich als beliebiger Benutzer ausgeben. Ein einzelnes curl -H "X-Auth-Request-Email: admin@example.com" http://127.0.0.1:3000/ reicht für eine vollständige Umgehung aus, wenn es die Anwendung direkt erreicht.

Die Anwendung darf daher nur über den Proxy erreichbar sein. Löschen Sie bei Docker Compose das ports:-Mapping aus dem Anwendungsdienst, und belassen Sie ihn im internen Netzwerk. Dadurch kann nur der Proxy-Container eine Verbindung zu ihm herstellen. Binden Sie die Anwendung auf einem Bare-Metal-Host stattdessen an 127.0.0.1:3000 und nicht an 0.0.0.0:3000. Prüfen Sie anschließend, was tatsächlich erreichbar ist:

sudo ss -tlnp | grep 3000

Eine Zeile mit 0.0.0.0:3000 bedeutet, dass die Anwendung auf der öffentlichen IP-Adresse antwortet und Ihre Zugriffssperre nur Dekoration ist. 127.0.0.1:3000 ist die gewünschte Einstellung. Eine Firewall-Regel ist eine sinnvolle zweite Schutzschicht. Die Bind-Adresse bleibt jedoch wirksam, wenn ein anderes Tool Ihren Regelsatz löscht.

oauth2-proxy installieren

Stand Oktober 2026 ist v7.15.5 die aktuelle Version. Sie wurde am 1. Oktober 2026 veröffentlicht. Sie behebt zwei kritische Sicherheitsprobleme. Eines davon ermöglicht die Umgehung von skip_auth_routes und betrifft jede Version nach v7.5.0. Installieren Sie daher keine ältere Version. Installieren Sie die Binärdatei und prüfen Sie den Download:

cd /tmp
curl -fsSLO https://github.com/oauth2-proxy/oauth2-proxy/releases/download/v7.15.5/oauth2-proxy-v7.15.5.linux-amd64.tar.gz
curl -fsSLO https://github.com/oauth2-proxy/oauth2-proxy/releases/download/v7.15.5/oauth2-proxy-v7.15.5.linux-amd64.tar.gz-sha256sum.txt
sha256sum -c oauth2-proxy-v7.15.5.linux-amd64.tar.gz-sha256sum.txt
tar -xzf oauth2-proxy-v7.15.5.linux-amd64.tar.gz
sudo install -m 755 oauth2-proxy-v7.15.5.linux-amd64/oauth2-proxy /usr/local/bin/oauth2-proxy
oauth2-proxy --version

sha256sum -c muss eine Zeile ausgeben, die mit OK endet. Gibt der Befehl FAILED aus, beenden Sie den Vorgang und laden Sie die Datei erneut herunter, anstatt die Binärdatei auszuführen.

In Docker lautet das Image quay.io/oauth2-proxy/oauth2-proxy. Sie sollten den Tag fest vorgeben: quay.io/oauth2-proxy/oauth2-proxy:v7.15.5. Wenn der Tag auf latest gesetzt bleibt, wird aus einem routinemäßigen docker compose pull ein ungeplantes Upgrade des einen Prozesses, der alle Anwendungen auf dem Server schützt.

Das Session-Cookie ist verschlüsselt, und cookie_secret ist der Schlüssel. Der Verschlüsselungsschlüssel muss genau 16, 24 oder 32 Bytes lang sein, weil er als AES-Schlüssel (Advanced Encryption Standard) verwendet wird. oauth2-proxy akzeptiert einen URL-sicheren Base64-Wert, der beim Decodieren eine dieser Längen ergibt, oder ein unverschlüsseltes Secret mit einer dieser Längen. Andernfalls wird der Start mit einer Fehlermeldung zum Cookie-Secret abgebrochen. Der folgende Befehl erzeugt einen 44 Zeichen langen Wert, der einen 32-Byte-Schlüssel codiert.

openssl rand -base64 32 | tr -- '+/' '-_'

tr ist nicht nur eine kosmetische Anpassung. Damit wird das Standard-Base64-Alphabet in das URL-sichere Alphabet umgewandelt, das oauth2-proxy beim Decodieren des Secrets verwendet.

Für diesen Wert gelten zwei Regeln. Verwenden Sie für jedes Deployment ein anderes Secret. Wenn Sie mehr als eine oauth2-proxy-Instanz hinter derselben Domain betreiben, müssen alle dasselbe Secret verwenden, weil ein von einer Instanz verschlüsseltes Cookie von den anderen Instanzen gelesen werden können muss.

OAuth2-Proxy-Konfiguration schreiben

Legen Sie die Einstellungen in einer Datei ab, statt eine lange Befehlszeile zu verwenden. Dadurch erscheint das Client-Secret nie in der Ausgabe von ps.

# /etc/oauth2-proxy/oauth2-proxy.cfg
http_address = "127.0.0.1:4180"
reverse_proxy = true

provider = "oidc"
oidc_issuer_url = "https://id.example.com/application/o/myapp/"
client_id = "REPLACE_ME"
client_secret = "REPLACE_ME"

redirect_url = "https://app.example.com/oauth2/callback"
cookie_secret = "REPLACE_ME"
cookie_secure = true
cookie_domains = [".example.com"]
whitelist_domains = [".example.com"]

email_domains = ["*"]
set_xauthrequest = true
upstreams = ["static://202"]

reverse_proxy = true weist oauth2-proxy an, den X-Forwarded-*-Headern des vorgeschalteten Proxys zu vertrauen. Ohne diese Einstellung behandelt oauth2-proxy die Adresse des Proxys als Client-Adresse. Dadurch kann es falsch beurteilen, ob die Anfrage über HTTPS eingegangen ist.

trusted_proxy_ips begrenzt, welche Peers diese Header liefern dürfen. Standardmäßig wird jeder Absender als vertrauenswürdig eingestuft. Das ist hier nur sicher, weil http_address oauth2-proxy an 127.0.0.1 bindet. Wenn oauth2-proxy stattdessen an einem Docker-Netzwerk lauscht, setzen Sie diesen Wert auf die Adresse Ihres Reverse Proxys.

upstreams = ["static://202"] veranlasst oauth2-proxy, auf eine authentifizierte Anfrage mit 202 zu antworten und nichts weiterzuleiten. Das entspricht genau den Anforderungen von Forward Auth, weil der Reverse Proxy die Weiterleitung übernimmt. Bei der anderen Bereitstellungsform befindet sich oauth2-proxy mit upstreams = ["http://127.0.0.1:3000"] direkt im Anfragepfad, und auth_request wird überhaupt nicht verwendet. Das ist für eine einzelne Anwendung einfacher, skaliert aber nicht auf zehn Anwendungen.

email_domains = ["*"] lässt jede Adresse zu, die Ihr Provider authentifiziert. Beschränken Sie den Wert auf Ihre eigene Domain. Besser ist es, den Zugriff beim Provider über eine Gruppenbindung einzuschränken, weil Sie Benutzer bereits dort verwalten.

Führen Sie den Dienst unter systemd als eigenen Benutzer aus:

# /etc/systemd/system/oauth2-proxy.service
[Unit]
Description=oauth2-proxy
After=network-online.target
Wants=network-online.target

[Service]
User=oauth2-proxy
Group=oauth2-proxy
ExecStart=/usr/local/bin/oauth2-proxy --config=/etc/oauth2-proxy/oauth2-proxy.cfg
Restart=on-failure
ProtectSystem=strict
PrivateTmp=true
NoNewPrivileges=true

[Install]
WantedBy=multi-user.target
sudo useradd --system --no-create-home --shell /usr/sbin/nologin oauth2-proxy
sudo install -d -m 750 /etc/oauth2-proxy
sudo chown -R oauth2-proxy:oauth2-proxy /etc/oauth2-proxy
sudo chmod 600 /etc/oauth2-proxy/oauth2-proxy.cfg
sudo systemctl daemon-reload
sudo systemctl enable --now oauth2-proxy
curl -s http://127.0.0.1:4180/ping

Die Ausgabe von /ping mit OK zeigt, dass der Prozess gestartet wurde und seine Konfiguration geladen hat. Dabei handelt es sich um den eigenen Health-Endpunkt von oauth2-proxy. Er fordert nie eine Sitzung an. Wenn keine Antwort erfolgt, lesen Sie journalctl -u oauth2-proxy -n 50. Eine fehlerhafte Issuer-URL und ein Cookie-Secret mit falscher Länge führen beide bereits beim Start zum Fehler und werden dort angezeigt.

Registrieren Sie die Redirect-URI beim Provider

Erstellen Sie bei Ihrem Provider eine OIDC-Anwendung und setzen Sie deren Redirect-URI exakt auf den redirect_url aus der Konfiguration: https://app.example.com/oauth2/callback. Exakt bedeutet, dass Schema, Host, Port und Pfad Zeichen für Zeichen übereinstimmen. Ein abschließender Schrägstrich macht daraus eine andere URI.

Dies ist der häufigste Fehler in der gesamten Einrichtung. Er tritt auf, bevor oauth2-proxy überhaupt beteiligt ist. Der Provider weist die Autorisierungsanfrage zurück und zeigt seine eigene Fehlerseite an. Deshalb erscheint nichts im oauth2-proxy-Log. Ein Hinweis ist die Adressleiste: Der Browser befindet sich weiterhin auf der Domain Ihres Providers, und die Abfragezeichenfolge enthält error=invalid_request oder die Seite benennt direkt redirect_uri. Wenn Sie das sehen, korrigieren Sie den Anwendungseintrag beim Provider, nicht die Proxy-Konfiguration.

Kopieren Sie die Issuer-URL aus dem Provider, statt sie einzugeben. oauth2-proxy hängt /.well-known/openid-configuration an oidc_issuer_url an und ruft dieses Discovery-Dokument beim Start ab. Prüfen Sie es zuerst selbst:

curl -s https://id.example.com/application/o/myapp/.well-known/openid-configuration | head -c 400

JSON mit einem Schlüssel authorization_endpoint ist eine erste Prüfung. issuer im Dokument muss außerdem exakt mit oidc_issuer_url übereinstimmen. Ein 404-Fehler oder eine HTML-Fehlerseite bedeutet, dass die URL falsch ist. oauth2-proxy kann dann wegen desselben 404-Fehlers nicht starten. Wenn Sie noch keinen Provider ausgewählt haben, erläutert der Vergleich von Keycloak, Authentik und Zitadel die Unterschiede. Authentik als eigenen SSO-Server betreiben beschreibt den Provider-Teil genau dieser Einrichtung.

Nginx: auth_request

Nginx führt die vorgelagerte Authentifizierung mit auth_request durch. Die Direktive löst eine interne Sub-Anfrage aus und verzweigt anhand ihres Statuscodes.

# in the http context, next to your other maps
map $http_upgrade $connection_upgrade {
  default upgrade;
  ''      close;
}

server {
  listen 443 ssl;
  server_name app.example.com;

  location /oauth2/ {
    proxy_pass       http://127.0.0.1:4180;
    proxy_set_header Host                    $host;
    proxy_set_header X-Real-IP               $remote_addr;
    proxy_set_header X-Auth-Request-Redirect $request_uri;
  }

  location = /oauth2/auth {
    proxy_pass       http://127.0.0.1:4180;
    proxy_set_header Host             $host;
    proxy_set_header X-Real-IP        $remote_addr;
    proxy_set_header X-Forwarded-Uri  $request_uri;
    proxy_set_header Content-Length   "";
    proxy_pass_request_body           off;
  }

  location / {
    auth_request /oauth2/auth;
    error_page 401 = @oauth2_signin;

    auth_request_set $user  $upstream_http_x_auth_request_user;
    auth_request_set $email $upstream_http_x_auth_request_email;
    proxy_set_header X-User  $user;
    proxy_set_header X-Email $email;

    auth_request_set $auth_cookie $upstream_http_set_cookie;
    add_header Set-Cookie $auth_cookie;

    proxy_pass http://127.0.0.1:3000;
    proxy_set_header Host       $host;
    proxy_set_header Upgrade    $http_upgrade;
    proxy_set_header Connection $connection_upgrade;
  }

  location @oauth2_signin {
    return 302 /oauth2/sign_in?rd=$scheme://$host$request_uri;
  }
}

Drei Details sind dabei wichtig. proxy_pass_request_body off mit einem leeren Content-Length verhindert, dass nginx einen Request-Body an den Authentifizierungsendpunkt weiterleitet. Dieser benötigt nur die Header.

Das Paar aus auth_request_set $auth_cookie und add_header Set-Cookie übergibt ein aktualisiertes Sitzungscookie an den Browser. Fehlt es, bleibt cookie_refresh unbemerkt wirkungslos, weil nginx das Set-Cookie der Sub-Anfrage verwirft. Der Browser behält dann den alten Wert, bis die Sitzung abläuft. Dieses Paar verarbeitet ein Cookie. Bei aufgeteilten Sitzungscookies benötigen die übrigen Bestandteile eine zusätzliche Verarbeitung oder Sie verwenden eine Redis-Sitzungsspeicherung.

error_page 401 = @oauth2_signin wandelt eine fehlgeschlagene Prüfung in eine Anmeldung um. Ohne diese Direktive erhält ein nicht authentifizierter Besucher lediglich eine leere 401 Authorization Required-Seite und kann nicht fortfahren.

Testen Sie die Konfiguration immer vor dem Neuladen:

sudo nginx -t && sudo systemctl reload nginx

Falls Ihnen die umgebenden Direktiven noch nicht vertraut sind, beschreibt der Aufbau einer nginx-Reverse-Proxy-Konfiguration die darunterliegende Ebene.

Traefik: forwardAuth-Middleware

Traefik benötigt für diese Aufgabe zwei Middlewares. Eine führt die Prüfung durch. Die andere stellt die Anmeldeseite bereit, wenn die Prüfung fehlschlägt.

# dynamic configuration
http:
  middlewares:
    oauth-auth:
      forwardAuth:
        address: https://oauth.example.com/oauth2/auth
        trustForwardHeader: true
    oauth-errors:
      errors:
        status:
          - "401-403"
        service: oauth-backend
        query: "/oauth2/sign_in?rd={url}"

Binden Sie beide an den Router an, der Ihrer Anwendung vorgeschaltet ist, und zwar mit oauth-errors vor oauth-auth. Stellen Sie oauth2-proxy außerdem über einen eigenen Router unter oauth.example.com bereit, weil der Browser /oauth2/sign_in und /oauth2/callback erreichen muss, ohne die Prüfung zu durchlaufen. Setzen Sie für diesen separaten Login-Host redirect_url auf https://oauth.example.com/oauth2/callback und registrieren Sie diese URI beim Provider.

Mit der obigen oauth2-proxy-Konfiguration rendert /oauth2/sign_in eine Anmeldeseite. Für eine automatische Weiterleitung setzen Sie skip_provider_button = true in oauth2-proxy und ergänzen Sie statusRewrites: {"401": 302} in den errors-Einstellungen von Traefik. Ohne diese Umschreibung gibt Traefik die automatische Weiterleitung mit dem Status 401 zurück, und der Browser folgt ihr nicht. Die Umschreibung allein startet den Anmeldevorgang nicht.

trustForwardHeader: true vertraut eingehenden X-Forwarded-*-Headern. Traefik übergibt den ursprünglichen Host und die URI an oauth2-proxy. Diese Option ist in der aktuellen Traefik-Dokumentation veraltet. Setzen Sie whitelist_domains so, dass dieser Host ebenfalls abgedeckt ist. Andernfalls verwirft oauth2-proxy den Parameter rd als mögliches Open-Redirect-Risiko, und alle landen nach der Anmeldung unter /. Ein Traefik-Server ist normalerweise mehreren Anwendungen vorgeschaltet. Mehrere Docker-Compose-Anwendungen über eine Traefik-Instanz routen zeigt die Struktur der Router, in die sich dies einfügt.

Caddy: forward_auth

app.example.com {
  handle /oauth2/* {
    reverse_proxy 127.0.0.1:4180 {
      header_up X-Real-IP {remote_host}
      header_up X-Forwarded-Uri {uri}
    }
  }
  handle {
    forward_auth 127.0.0.1:4180 {
      uri /oauth2/auth
      header_up X-Real-IP {remote_host}
      copy_headers X-Auth-Request-User X-Auth-Request-Email
      @error status 401
      handle_response @error {
        redir * /oauth2/sign_in?rd={scheme}://{host}{uri}
      }
    }
    reverse_proxy 127.0.0.1:3000
  }
}

Die Reihenfolge ist wichtig. Der /oauth2/*-Block steht an erster Stelle und enthält kein forward_auth, weil ein nicht angemeldeter Besucher die Anmelde- und Callback-Pfade erreichen muss. Setzen Sie die Prüfung vor diese Pfade. Andernfalls leiten die Anmeldeanforderungen so lange auf sich selbst um, bis der Browser abbricht.

copy_headers überträgt die Identität in die Anfrage an das Upstream-System. Das funktioniert nur, wenn oauth2-proxy mit set_xauthrequest = true ausgeführt wird. Die Auswahl zwischen den Proxys ist eine eigene Frage. Der Vergleich von nginx, Caddy und Traefik erläutert sie.

Warum kehrt die Anmeldung zur Anmeldeseite zurück?

Sie melden sich beim Anbieter an, werden zurückgeleitet, und oauth2-proxy leitet Sie wieder zur Anmeldung zurück. Die Schleife bedeutet, dass oauth2-proxy bei der nächsten Anfrage keine gültige Sitzung akzeptiert. Das Sitzungscookie kann fehlen oder vorhanden sein und die Validierung nicht bestehen, beispielsweise wenn Instanzen unterschiedliche Cookie-Secrets verwenden. Öffnen Sie die Entwicklertools des Browsers, suchen Sie die Anfrage an /oauth2/callback, die auf die Rückleitung von Ihrem Anbieter folgt, und lesen Sie ihren Set-Cookie-Response-Header. Ein dort gesetztes Cookie, das in der nächsten Anfrage fehlt, wird vom Browser abgelehnt. Ist es vorhanden, prüfen Sie das Server-Log auf Validierungsfehler wie cookie signature not valid und stellen Sie sicher, dass alle Instanzen dasselbe Secret verwenden.

Wenn das fehlende Cookie das CSRF-Cookie ist, das oauth2-proxy beim Start der Anmeldung gesetzt hat, entsteht keine Schleife. Der Ablauf endet beim Callback, und das Log nennt den Fall:

No cookies were found in OAuth callback.

oder, wenn ein anderes Cookie angekommen ist, das richtige jedoch nicht:

Cookies were found in OAuth callback, but none was a CSRF cookie.

CSRF steht für Cross-Site Request Forgery. Dieses Cookie stellt sicher, dass ein Callback der Anmeldung zugeordnet werden kann, die ihn gestartet hat. Der Browser zeigt eine 403-Fehlerseite mit folgendem Inhalt:

Login Failed: Unable to find a valid CSRF token. Please try again.

Für fehlende Cookies gelten die ersten drei Ursachen unten. Eine weitere Ursache für Validierungsfehler ist eine Zeitabweichung. Prüfen Sie diese vier Ursachen in der angegebenen Reihenfolge.

  1. cookie_secure = true, während der Browser die Website über unverschlüsseltes HTTP aufgerufen hat. Außer bei localhost speichert ein Browser kein mit Secure markiertes Cookie für einen http://-Origin. Daher wird es nie zurückgesendet. Beenden Sie TLS (Transport Layer Security) ordnungsgemäß oder setzen Sie cookie_secure = false nur für Tests auf localhost.
  2. Ein cookie_domains-Wert, der den Hostnamen in der Adressleiste nicht abdeckt. .example.com gilt für app.example.com und hat für app.example.net keinerlei Wirkung.
  3. Der Browser verwirft das Cookie. Eine strikte Datenschutz-Erweiterung oder die Blockierung von Drittanbieter-Cookies kann _oauth2_proxy_csrf zwischen der ausgehenden Weiterleitung und dem Callback entfernen oder anschließend das Sitzungscookie löschen.
  4. Zeitabweichung. Geht die Serverzeit der des Anbieters deutlich voraus, kann das ID-Token als abgelaufen erscheinen und die Validierung fehlschlagen. timedatectl sollte System clock synchronized: yes melden.

Eine weitere Ursache kann den CSRF-Fehler auslösen, obwohl nichts falsch konfiguriert ist. Standardmäßig verwendet oauth2-proxy ein einzelnes CSRF-Cookie. Daher überschreiben sich zwei Tabs, die gleichzeitig eine Anmeldung starten. cookie_csrf_per_request = true weist jeder Anmeldung ein eigenes Cookie zu.

Beobachten Sie den Ablauf serverseitig, statt zu vermuten:

sudo journalctl -u oauth2-proxy -f

Öffnen Sie die Anwendung in einem privaten Fenster. Jede Anfrage wird mit ihrem Status protokolliert. Eine unmittelbar von einer weiteren Weiterleitung zur Anmeldung gefolgte Callback-Anfrage ist dann in der Aufzeichnung als Schleife erkennbar.

Pfade, die den Login umgehen müssen: APIs, Webhooks und WebSockets

Forward Auth setzt einen Browser mit Cookie voraus. Aufrufer ohne Browser funktionieren damit nicht.

Ein API-Client, der Authorization: Bearer <token> sendet, hat kein Cookie. Daher leiten die obigen Proxy-Konfigurationen ihn zur Login-Seite von oauth2-proxy weiter, sofern die Bearer-Token-Authentifizierung nicht aktiviert ist. Dafür gibt es zwei saubere Lösungen. Mit skip_jwt_bearer_tokens = true akzeptiert oauth2-proxy ein gültiges JWT (JSON Web Token) als Bearer-Token vom konfigurierten Issuer, wenn das Token eine für diesen Client akzeptierte Audience enthält. Das ist die richtige Lösung, wenn Ihre API-Clients bereits geeignete Tokens vom Provider erhalten. Der Wert aud im Token muss mit client_id oder mit einer über extra_jwt_issuers konfigurierten Audience übereinstimmen. Andernfalls nehmen Sie den Pfad von der Prüfung aus:

skip_auth_routes = [
  "^/api/",
  "POST=^/webhook/",
  "GET=^/healthz$"
]

Jeder Wert ist ein regulärer Ausdruck, der gegen den dekodierten Pfad ohne Query-Parameter geprüft wird. Optional kann ihm eine HTTP-Methode und = vorangestellt werden. POST=^/webhook/ lässt den Webhook-Empfänger für POST offen, während ein Benutzer, der denselben Pfad im Browser aufruft, weiterhin den Login sieht, sofern die Authentifizierungsanfrage die ursprüngliche Methode beibehält. Nginx auth_request und Caddy forward_auth führen GET-Prüfungen durch. Methodenspezifische Ausnahmen benötigen in diesen Umgebungen daher ein separates Routing im Reverse Proxy. Jeder Eintrag ist eine Lücke in Ihrer Zugriffssperre. Verankern Sie die Ausdrücke deshalb mit ^ und halten Sie sie so eng wie es der Aufrufer erlaubt.

Verwenden Sie v7.15.5 oder eine spätere Version, bevor Sie sich darauf verlassen. Frühere Versionen ab v7.5.0 konnten dazu gebracht werden, einen geschützten Pfad bei einer Anfrage mit Dot-Segmenten, einem doppelten führenden Schrägstrich oder einem Semikolon von der Prüfung auszunehmen (Hinweis GHSA-63jm-59jj-478j). Auch das Verankern der Ausdrücke verhinderte dies nicht. Die korrigierte Version nimmt solche mehrdeutigen Pfade nicht mehr von der Prüfung aus. Prüfen Sie daher nach dem Upgrade, ob Ihre öffentlichen Routen weiterhin übereinstimmen.

Bei WebSockets liegt der häufigste Fehler. Die Upgrade-Anfrage ist ein gewöhnlicher HTTP-GET mit denselben Cookies wie jede andere Anfrage. Sie passiert die Prüfung daher normal und benötigt keine Ausnahme. Das Problem liegt beim Proxying. Ohne die Header Upgrade und Connection am geschützten Location-Block wird das Upgrade nicht abgeschlossen. Der Client der Anwendung wiederholt die Anfrage dann dauerhaft und zeigt eine WebSocket connection ... failed-Meldung in der Browserkonsole. Eine Ausnahme für den Pfad behebt das Problem nicht, weil die Anfrage bereits autorisiert war.

Eine tatsächliche Einschränkung bleibt. Die Prüfung läuft nur einmal beim Upgrade. Ein WebSocket, der stundenlang geöffnet bleibt, wird nicht erneut geprüft. Wenn Sie einen Benutzer beim Provider entfernen, wird dessen bereits bestehende Verbindung daher nicht geschlossen. Starten Sie die Anwendung neu, um aktive Verbindungen zu trennen.

Standardmäßig befindet sich die gesamte Sitzung im Cookie und wird mit Ihrem cookie_secret verschlüsselt. Dadurch bleibt oauth2-proxy zustandslos und benötigt keinen zusätzlichen Dienst. Die Größe ist jedoch begrenzt, weil Browser einen Cookie auf etwa 4 KB begrenzen. Wenn das ID-Token eine lange Liste von Gruppen-Claims enthält, teilt oauth2-proxy die Sitzung auf _oauth2_proxy_0, _oauth2_proxy_1 und weitere Cookies auf. Nach wenigen Teilen werden die Request-Header so groß, dass nginx mit 400 Request Header Or Cookie Too Large antwortet, bevor die Anwendung den Request überhaupt erhält.

Stellen Sie die Sitzung in diesem Fall serverseitig bereit:

session_store_type = "redis"
redis_connection_url = "redis://127.0.0.1:6379"

Der Browser enthält dann nur ein kurzes Ticket. Die verschlüsselte Sitzung liegt in Redis. Dafür muss ein zusätzlicher Dienst dauerhaft verfügbar sein. Wenn Redis ausfällt, kann oauth2-proxy Sitzungen nicht laden. Gehen die gespeicherten Sitzungsdaten verloren, müssen sich alle Benutzer erneut anmelden. Der Cookie-Speicher hat ebenfalls einen eigenen Nachteil: Zwei Requests, die dieselbe Sitzung gleichzeitig aktualisieren, können miteinander in Konflikt geraten und eine erneute Anmeldung erzwingen.

Was Forward Auth nicht leistet

Forward Auth ist eine Zugangskontrolle. Es ist keine Autorisierung innerhalb der Anwendung. Dieser Unterschied entscheidet, ob der Ansatz für Ihren Anwendungsfall geeignet ist.

Sobald ein Benutzer die Zugangskontrolle passiert hat, sieht die Anwendung genau das, was sie zuvor gesehen hat. Verfügt die Anwendung über eigene Rollen, ergänzt Forward Auth diese nicht. Eine Ausnahme gilt, wenn die Anwendung headerbasierte Authentifizierung unterstützt und einen Header einem Benutzerkonto zuordnet. Grafana unterstützt dies über seine auth.proxy-Einstellungen. Die meisten selbst gehosteten Anwendungen unterstützen es nicht. Für die Anwendung ist dann jeder Benutzer, der die Zugangskontrolle passiert, dieselbe einzelne Identität. Diese Identität hat häufig Administratorrechte.

Auch die eigenen API-Tokens der Anwendung werden dadurch nicht geschützt. Ein von der Anwendung ausgestelltes Personal Access Token authentifiziert den Zugriff auf die Anwendung, nicht auf oauth2-proxy. Das Token funktioniert daher nicht mehr, sobald die Zugangskontrolle davorsteht. Wenn Sie den API-Pfad ausnehmen, funktioniert es wieder. Dann ist dieses Token jedoch die einzige Schutzmaßnahme für den Pfad. Sie betreiben nun zwei Authentifizierungssysteme für einen Dienst. SSO deckt nur eines davon ab.

Die dritte Lücke betrifft den Widerruf. Wenn Sie einen Benutzer bei Ihrem Identity Provider löschen, werden neue Anmeldungen verhindert. Eine bestehende Sitzung prüft oauth2-proxy jedoch erst erneut beim Identity Provider, wenn cookie_refresh abläuft. Bei deaktivierter Aktualisierung bleibt das Session-Cookie bis zu seinem Ablauf gültig. cookie_expire ist standardmäßig auf 168 Stunden gesetzt. Dadurch kann eine gerade entfernte Person noch eine Woche lang Zugriff haben. Setzen Sie cookie_refresh auf einen kurzen Wert, beispielsweise eine Stunde. Wenn der Identity Provider die Aktualisierung ablehnt, weil das Refresh-Token des Benutzers nicht mehr gültig ist, löscht oauth2-proxy die Sitzung. Bei der nächsten Anfrage, die eine Aktualisierung auslöst, ist dann eine neue Anmeldung erforderlich. Nicht jeder Identity Provider unterstützt die Aktualisierung. Testen Sie dieses Verhalten daher mit Ihrem Provider.

Auch die Audit-Spur endet an der Zugangskontrolle. oauth2-proxy protokolliert, wer sie passiert hat und wann. Die Anwendung protokolliert dagegen nur eine nicht benannte Sitzung. Wenn Sie nachvollziehen müssen, wer eine Einstellung geändert hat, ist die Übernahme der Identität per Header in der Anwendung die Mindestanforderung. Echte Benutzerkonten mit individuellen Berechtigungen sind die zuverlässige Lösung.

Wenn das Bezahlen für SSO die bessere Lösung ist

Forward Auth ist das richtige Werkzeug, wenn eine Anwendung überhaupt keine Anmeldung oder nur ein gemeinsames Passwort bietet und Sie einen zentralen Ort zum Hinzufügen und Entfernen von Benutzern benötigen. Die Einrichtung kostet einen Nachmittag und einen zusätzlichen Prozess. Sie funktioniert mit jeder Anwendung, die HTTP spricht.

Das Werkzeug ist ungeeignet, wenn verschiedene Personen innerhalb derselben Anwendung unterschiedliche Berechtigungen benötigen. Ein vorgeschaltetes Zugriffstor kann nicht ausdrücken: „Ana darf die Dashboards bearbeiten, Bo darf sie nur lesen.“ Wenn der Anbieter eine SSO-Stufe verkauft, ist die Zuordnung von Gruppen zu Rollen meist genau das, wofür Sie bezahlen. Diese Zuordnung mit Headern und Proxy-Regeln nachzubauen, ist fehleranfälliger, als dafür zu bezahlen. Das Preismodell hinter diesen SSO-Stufen sollten Sie lesen, bevor Sie sich für eine der beiden Varianten entscheiden.

Jede Anwendung mit einem mobilen oder Desktop-Client, der keine Browser-Cookies überträgt, wird bei jeder Anfrage mit dem Zugriffstor in Konflikt geraten.

FAQ

Was ist Forward Auth?

Forward Auth ist ein Muster, bei dem der Reverse Proxy vor der Weiterleitung an das Upstream-Backend einen separaten Authentifizierungsdienst zu jeder eingehenden Anfrage befragt. Der Proxy sendet die Request-Header an einen Endpunkt wie /oauth2/auth und liest den Statuscode aus. 202 bedeutet, dass die Anfrage zugelassen ist. Die ursprüngliche Anfrage wird an die Anwendung weitergeleitet. 401 bedeutet, dass keine gültige Sitzung vorhanden ist. Der Proxy leitet den Browser deshalb zur Anmeldung weiter. Nginx implementiert dies mit der Direktive auth_request, Traefik mit der Middleware forwardAuth und Caddy mit forward_auth.

Warum leitet mich oauth2-proxy in einer Schleife immer wieder zur Anmeldeseite weiter?

Das Session-Cookie fehlt oder die Validierung schlägt fehl. Deshalb findet jede Prüfung keine gültige Sitzung und leitet Sie wieder zur Anmeldung weiter. Instanzen mit unterschiedlichen Cookie-Secrets lehnen die Cookies der jeweils anderen Instanz ab. Eine weitere Ursache ist cookie_secure = true auf einer Website, die der Browser über unverschlüsseltes HTTP erreicht hat. Ein Browser speichert ein Secure-Cookie auf einer http://-Origin außerhalb von localhost nicht. Prüfen Sie außerdem, ob der Wert von cookie_domains den Hostnamen in der Adressleiste abdeckt. Lesen Sie in den Entwicklerwerkzeugen des Browsers den Set-Cookie-Header der /oauth2/callback-Antwort aus, um festzustellen, welches Cookie fehlt. Wenn das Cookie zurückgesendet wird, prüfen Sie das Server-Log auf Validierungsfehler. Wenn das CSRF-Cookie fehlt, erhalten Sie statt einer Schleife eine 403-Seite mit dem Text Login Failed: Unable to find a valid CSRF token. Please try again.. Im Log steht No cookies were found in OAuth callback., wenn keine Cookies eingegangen sind.

Wie lasse ich einen API-Client oder einen Webhook durch oauth2-proxy zu?

Verwenden Sie skip_auth_routes mit einem regulären Ausdruck, der am Anfang und Ende verankert ist, und beschränken Sie ihn optional auf eine HTTP-Methode, zum Beispiel POST=^/webhook/. Verwenden Sie v7.15.5 oder höher. Diese Version behebt eine kritische Umgehung dieser Ausnahmen. Methodenspezifische Ausnahmen erfordern, dass die Authentifizierungsanfrage die ursprüngliche Methode beibehält. Die Nginx- und Caddy-Beispiele führen GET-Prüfungen durch. Behandeln Sie diese Ausnahmen deshalb im Routing des Reverse Proxy. Wenn Ihre API-Clients bereits gültige JWTs besitzen, die vom konfigurierten Provider mit einer akzeptierten Audience ausgestellt wurden, akzeptiert skip_jwt_bearer_tokens = true diese Tokens anstelle eines Cookies. Der Pfad bleibt dabei geschützt. Die Audience muss client_id entsprechen oder über extra_jwt_issuers konfiguriert sein. Alles, was in skip_auth_routes aufgeführt ist, ist für alle nicht authentifiziert. Halten Sie daher jeden Ausdruck so eng wie es der Aufrufer zulässt.

Gewährt oauth2-proxy der Anwendung benutzerbezogene Berechtigungen?

Nein. oauth2-proxy ist ein Zugangsschutz, aber kein Autorisierungssystem. Es entscheidet, wer die Anwendung erreicht. Für die Anwendung sehen alle zugelassenen Benutzer identisch aus, sofern die Anwendung Identitäts-Header ausliest und diese Konten zuordnet. Grafana kann dies über seine auth.proxy-Einstellungen umsetzen. Die meisten selbst gehosteten Anwendungen können dies nicht. Daher verwenden alle Personen hinter dem Zugangsschutz dieselbe Identität, unter der die Anwendung ausgeführt wird.

Kann jemand oauth2-proxy umgehen, indem er den Identitäts-Header selbst setzt?

Ja, wenn die Person die Anwendung direkt erreichen kann. Die Identität wird als einfacher Header wie X-Auth-Request-Email übertragen. Die Anwendung vertraut den empfangenen Daten. Jeder, der eine Verbindung zum Anwendungsport öffnen kann, kann diesen Header senden und sich als beliebiger Benutzer ausgeben. Binden Sie die Anwendung an 127.0.0.1 oder lassen Sie sie in einem internen Docker-Netzwerk ohne veröffentlichten Port laufen. Bestätigen Sie dies mit sudo ss -tlnp.

War dieser Artikel hilfreich?

#oauth2-proxy#sso#oidc#reverse-proxy#forward-auth