diff --git a/docs/authentication/header-auth.md b/docs/authentication/header-auth.md
index 4962ec09..c3ba0f11 100644
--- a/docs/authentication/header-auth.md
+++ b/docs/authentication/header-auth.md
@@ -9,6 +9,7 @@ Use this when you already run something like [Authelia](https://www.authelia.com
- [Configure Dashy](#configure-dashy)
- [Configure your proxy](#configure-your-proxy)
- [Logging out](#logging-out)
+- [Example: oauth2-proxy and nginx](#example-oauth2-proxy-and-nginx)
- [Troubleshooting](#troubleshooting)
- [Security notes](#security-notes)
- [How it works](#how-it-works)
@@ -64,6 +65,124 @@ Logging out then sends the browser to that URL, where the proxy can destroy its
The specific endpoint depends on your proxy, but for oauth2-proxy it's usually `/oauth2/sign_out` with an `rd` query param to chain your identity provider's logout, e.g. `/oauth2/sign_out?rd=https://sso.example.com/logout` (the `rd` domain must be in oauth2-proxy's `whitelist_domains`).
+---
+
+
+## Example: oauth2-proxy and nginx
+
+The following example was from [@vmario89](https://github.com/vmario89) (in [#2233](https://github.com/lissy93/dashy/issues/2233#issuecomment-4924556178)).
+
+[oauth2-proxy](https://oauth2-proxy.github.io/oauth2-proxy/) handles login against any OIDC or OAuth2 provider (Synology SSO here). nginx checks each request against its `/oauth2/auth` endpoint, then forwards the username to Dashy as `X-Remote-User`.
+
+Dashy config, on top of [the setup above](#configure-dashy). The whitelist is loopback because nginx proxies to Dashy on `127.0.0.1:4000`:
+
+```yaml
+appConfig:
+ auth:
+ logoutRedirectUrl: https://dashy.example.com/oauth2/sign_out?rd=https://sso.example.com/logout
+ headerAuth:
+ userHeader: X-Remote-User
+ proxyWhitelist:
+ - 127.0.0.1
+ - '::1'
+ - '::ffff:127.0.0.1'
+```
+
+
+oauth2-proxy config
+
+```ini
+provider = "oidc"
+oidc_issuer_url = "https://login.synology.nas/webman/sso"
+oidc_jwks_url = "https://login.synology.nas/webman/sso/openid-jwks.json"
+scope = "openid profile email"
+oidc_email_claim = "sub"
+client_id = ""
+client_secret = ""
+cookie_secret = "" # openssl rand -base64 32
+cookie_name = "cookie_dashy"
+cookie_domains = ".example.com"
+cookie_secure = true
+email_domains = [ "*" ]
+http_address = "127.0.0.1:4180"
+upstreams = [ "static://200" ]
+set_xauthrequest = true
+whitelist_domains = [ "dashy.example.com", "login.synology.nas" ]
+```
+
+And a systemd unit to run it:
+
+```ini
+[Unit]
+Description=OAuth2 Proxy (Dashy)
+After=network.target
+
+[Service]
+User=oauth2proxy
+Group=oauth2proxy
+ExecStart=/opt/oauth2-proxy/oauth2-proxy --config=/etc/oauth2-proxy/dashy.cfg --trusted-proxy-ip=127.0.0.1/32
+Restart=always
+RestartSec=10
+
+[Install]
+WantedBy=multi-user.target
+```
+
+
+
+The load-bearing options:
+
+- `set_xauthrequest = true` - returns the username on auth responses (`X-Auth-Request-User`) for nginx to pick up
+- `upstreams = [ "static://200" ]` - oauth2-proxy only answers auth checks here; nginx proxies to Dashy itself
+- `whitelist_domains` - must include the `rd=` logout domain, or the redirect is dropped
+- `--trusted-proxy-ip` - makes oauth2-proxy trust the `X-Forwarded-*` headers nginx sets
+
+
+nginx site config
+
+```nginx
+map $auth_user $auth_user_local {
+ "" "";
+ ~^(?[^@]+)@.* $lp;
+ default $auth_user;
+}
+
+server {
+ server_name dashy.example.com;
+ # TLS config here
+
+ location / {
+ auth_request /oauth2/auth;
+ auth_request_set $auth_user $upstream_http_x_auth_request_user;
+ proxy_set_header X-Remote-User $auth_user_local;
+ proxy_set_header Host $host;
+ proxy_set_header X-Real-IP $remote_addr;
+ proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+ proxy_set_header X-Forwarded-Proto $scheme;
+ error_page 401 = /oauth2/sign_in;
+ proxy_pass http://127.0.0.1:4000;
+ }
+
+ 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-Scheme $scheme;
+ proxy_set_header X-Forwarded-Proto $scheme;
+ proxy_set_header X-Forwarded-Host $host;
+ proxy_set_header X-Auth-Request-Redirect $request_uri;
+ proxy_set_header Content-Length "";
+ proxy_pass_request_body off;
+ }
+}
+```
+
+
+
+`auth_request_set` reads the username from oauth2-proxy's response, and the `map` strips `@domain` from it, since oauth2-proxy forwards an email but Dashy matches the bare names in `auth.users`.
+
+---
+
## Troubleshooting
#### 401 "Unauthorized - not from trusted proxy"
diff --git a/docs/authentication/other-auth-methods.md b/docs/authentication/other-auth-methods.md
index 30cb10bb..2cf52955 100644
--- a/docs/authentication/other-auth-methods.md
+++ b/docs/authentication/other-auth-methods.md
@@ -31,7 +31,7 @@ See the [Authelia docs](https://www.authelia.com/docs/) for the full setup guide
**Authentik** is heavier but gives you a proper admin UI, built-in OIDC/SAML support, and user self-service (password resets, enrollment flows, etc). Good if you want a single identity provider across many apps. See the [authentik Docker Compose install](https://docs.goauthentik.io/docs/installation/docker-compose) to get started, and the [authentik guide](./authentik.md) for Dashy-specific OIDC config.
-**OAuth2 Proxy** ([docs](https://oauth2-proxy.github.io/oauth2-proxy/)) is a thin forward-auth layer that puts any OIDC or OAuth2 provider (Google, GitHub, your own IdP) in front of apps that can't do it themselves. Point it at Dashy's [header auth](./header-auth.md) and it forwards the authenticated username, so you get provider login without Dashy needing to reach the provider directly.
+**OAuth2 Proxy** ([docs](https://oauth2-proxy.github.io/oauth2-proxy/)) is a thin forward-auth layer that puts any OIDC or OAuth2 provider (Google, GitHub, your own IdP) in front of apps that can't do it themselves. Point it at Dashy's [header auth](./header-auth.md) and it forwards the authenticated username, so you get provider login without Dashy needing to reach the provider directly. See the [oauth2-proxy example](./header-auth.md#example-oauth2-proxy-and-nginx) for the full nginx setup.
## Zero-trust tunnels