From 7cfaf9eafeec7b27547eeb07760a4becc6aaa737 Mon Sep 17 00:00:00 2001 From: Alicia Sykes Date: Thu, 9 Jul 2026 19:28:59 +0100 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20Adds=20oauth2-proxy=20and=20ngin?= =?UTF-8?q?x=20example?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/authentication/header-auth.md | 119 ++++++++++++++++++++++ docs/authentication/other-auth-methods.md | 2 +- 2 files changed, 120 insertions(+), 1 deletion(-) 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