Skip to content

armgit / dashy

Public Imported from GitHub
0

πŸš€ A self-hostable personal dashboard built for you. Includes status-checking, widgets, themes, icon packs, a UI editor and tons more!

πŸ›‚ Implements and documents the header auth

Alicia Sykes03a64d74902c
diff --git a/docs/authentication.md b/docs/authentication.md
index 578710dc..b9ce2487 100644
--- a/docs/authentication.md
+++ b/docs/authentication.md
@@ -529,6 +529,52 @@ sections:
```
---
+## Header Authentication
+
+Header authentication allows Dashy to trust an upstream reverse proxy to handle authentication. The proxy authenticates users and forwards their identity to Dashy via a configurable HTTP header (e.g. `REMOTE_USER`). This is the standard pattern used by [Authelia](https://www.authelia.com/), [Authentik](https://goauthentik.io/), Traefik's `forwardAuth`, Caddy's `forward_auth`, and Nginx's `auth_request`.
+
+This is useful when you already have a central authentication layer in front of your self-hosted services and want Dashy to automatically pick up the authenticated user without requiring a separate login.
+
+### Configuration
+
+```yaml
+appConfig:
+ auth:
+ enableHeaderAuth: true
+ users:
+ - user: alice
+ hash: 0a7b1d4c2e... # SHA-256 hash of password
+ type: admin
+ - user: bob
+ hash: 3f8e2b1a9d...
+ type: normal
+ headerAuth:
+ userHeader: REMOTE_USER
+ proxyWhitelist:
+ - 172.18.0.2
+ - 127.0.0.1
+```
+
+- **`userHeader`** - The HTTP header name containing the authenticated username. Defaults to `REMOTE_USER` if not specified.
+- **`proxyWhitelist`** - Required. An array of IP addresses that Dashy will accept the header from. Only requests originating from these IPs will be trusted. This prevents clients from spoofing the header directly.
+- **`users`** - Required. The header username is matched against this list to determine the user's role (`admin` or `normal`) and to generate the session token. Users must be defined here even though authentication is handled externally.
+
+### How it Works
+
+1. User visits Dashy, which is behind a reverse proxy (e.g. Authelia)
+2. The proxy authenticates the user and forwards the request with a header like `REMOTE_USER: alice`
+3. Dashy's server checks that the request comes from a whitelisted proxy IP, then returns the username via the `/get-user` endpoint
+4. The client matches the username against the configured users, generates a session token, and sets the auth cookie
+5. From this point, standard Dashy auth applies - `isLoggedIn()`, admin checks, and granular access controls all work as normal
+
+### Notes
+
+- The `proxyWhitelist` checks `req.socket.remoteAddress`, which is the direct connection source. If your proxy connects through Docker networking, use the container's internal IP (e.g. `172.18.0.2`), not the external IP
+- Logout clears Dashy's session cookie, but the user remains authenticated at the proxy level. Revisiting the page will re-authenticate automatically
+- Server-side endpoint protection (`ENABLE_HTTP_AUTH`) is separate from header auth. If you need both the proxy-based login flow and server-side API protection, configure both
+
+---
+
## Alternative Authentication Methods
If you are self-hosting Dashy, and require secure authentication to prevent unauthorized access, then you can either use Keycloak, or one of the following options:
diff --git a/server.js b/server.js
index 80ad559e..079ba586 100644
--- a/server.js
+++ b/server.js
@@ -77,18 +77,22 @@ const printWarning = (msg, error) => {
console.warn(`\x1b[103m\x1b[34m${msg}\x1b[0m\n`, error || ''); // eslint-disable-line no-console
};
-/* Load appConfig.auth.users from config (if present) for authorization purposes */
-function loadUserConfig() {
+/* Load appConfig.auth from config (if present) for authorization purposes */
+function loadAuthConfig() {
try {
const filePath = path.join(__dirname, process.env.USER_DATA_DIR || 'user-data', 'conf.yml');
const fileContents = fs.readFileSync(filePath, 'utf8');
const data = yaml.load(fileContents);
- return data?.appConfig?.auth?.users || null;
+ return data?.appConfig?.auth || {};
} catch (e) {
- return [];
+ return {};
}
}
+function loadUserConfig() {
+ return loadAuthConfig().users || null;
+}
+
/* Authorizer for ENABLE_HTTP_AUTH: validates credentials against conf.yml users */
function customAuthorizer(username, password) {
const sha256 = (input) => crypto.createHash('sha256').update(input).digest('hex').toUpperCase();
@@ -116,7 +120,8 @@ function customAuthorizer(username, password) {
/* If auth is enabled, setup auth for config access, otherwise skip */
function getBasicAuthMiddleware() {
- const confUsers = loadUserConfig();
+ const authConfig = loadAuthConfig();
+ const confUsers = authConfig.users || null;
const hasConfUsers = confUsers && confUsers.length > 0;
const useConfAuth = process.env.ENABLE_HTTP_AUTH && hasConfUsers;
const { BASIC_AUTH_USERNAME, BASIC_AUTH_PASSWORD } = process.env;
@@ -142,9 +147,22 @@ function getBasicAuthMiddleware() {
challenge: true,
unauthorizedResponse: () => 'Unauthorized - Incorrect username or password',
});
- } else {
- return (req, res, next) => next();
+ } else if (authConfig.enableHeaderAuth && authConfig.headerAuth) {
+ const { userHeader = 'REMOTE_USER', proxyWhitelist = [] } = authConfig.headerAuth;
+ return (req, res, next) => {
+ if (!proxyWhitelist.includes(req.socket.remoteAddress)) {
+ return res.status(401).json({ success: false, message: 'Unauthorized - not from trusted proxy' });
+ }
+ const user = req.headers[userHeader.toLowerCase()];
+ if (!user) {
+ return res.status(401).json({ success: false, message: 'Unauthorized - missing user header' });
+ }
+ req.auth = { user };
+ return next();
+ };
}
+
+ return (req, res, next) => next();
}
const protectConfig = getBasicAuthMiddleware();