📝 Adds oauth2-proxy and nginx example

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'
+```
+
+<details>
+<summary>oauth2-proxy config</summary>
+
+```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-id>"
+client_secret         = "<client-secret>"
+cookie_secret         = "<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
+```
+
+</details>
+
+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
+
+<details>
+<summary>nginx site config</summary>
+
+```nginx
+map $auth_user $auth_user_local {
+    ""                  "";
+    ~^(?<lp>[^@]+)@.*   $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;
+    }
+}
+```
+
+</details>
+
+`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"

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