π A self-hostable personal dashboard built for you. Includes status-checking, widgets, themes, icon packs, a UI editor and tons more!
Vue awesomedashboarddockerhomelabhomepagemitnodejsorganizationproductivitypwaself-hostedstartpagevue
π Adds oauth2-proxy and nginx example
Alicia Sykes7cfaf9eafeec
diff --git a/docs/authentication/header-auth.md b/docs/authentication/header-auth.mdindex 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 itsThe 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"diff --git a/docs/authentication/other-auth-methods.md b/docs/authentication/other-auth-methods.mdindex 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