🚀 A self-hostable personal dashboard built for you. Includes status-checking, widgets, themes, icon packs, a UI editor and tons more!
Vue awesomedashboarddockerhomelabhomepagemitnodejsorganizationproductivitypwaself-hostedstartpagevue
Untested documentation for headerAuth
Todd E Johnson756d640d06b8
diff --git a/docs/authentication.md b/docs/authentication.mdindex 535cc4ba..84d08e14 100644--- a/docs/authentication.md+++ b/docs/authentication.md@@ -194,20 +194,17 @@ Your app is now secured :) When you load Dashy, it will redirect to your KeycloaFrom within the Keycloak console, you can then configure things like time-outs, password policies, etc. You can also backup your full Keycloak config, and it is recommended to do this, along with your Dashy config. You can spin up both Dashy and Keycloak simultaneously and restore both applications configs using a `docker-compose.yml` file, and this is recommended.+**[⬆️ Back to Top](#authentication)**+----## Alternative Authentication Methods+## Header Authentciation-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:+### 1. Web Server/Reverse Proxy-- [Authentication Server](#authentication-server) - Put Dashy behind a self-hosted auth server-- [VPN](#vpn) - Use a VPN to tunnel into the network where Dashy is running-- [IP-Based Access](#ip-based-access) - Disallow access from all IP addresses, except your own-- [Web Server Authentication](#web-server-authentication) - Enable user control within your web server or proxy-- [OAuth Services](#oauth-services) - Implement a user management system using a cloud provider-- [Password Protection (for cloud providers)](#static-site-hosting-providers) - Enable password-protection on your site+Most web servers make password protecting certain apps very easy. Note that you should also set up HTTPS and have a valid certificate in order for this to be secure.-### Authentication Server+These are only an example. Please refer to your web server/reverse proxy for how to implement basic auth, set the correct headers, and ensure the headers aren't being forwarded from the client where they could be spoofed.#### Authelia@@ -221,56 +218,6 @@ If you are self-hosting Dashy, and require secure authentication to prevent unauFor more information, see the [Authelia docs](https://www.authelia.com/docs/)-### VPN--A catch-all solution to accessing services running from your home network remotely is to use a VPN. It means you do not need to worry about implementing complex authentication rules, or trusting the login implementation of individual applications. However it can be inconvenient to use on a day-to-day basis, and some public and corporate WiFi block VPN connections. Two popular VPN protocols are [OpenVPN](https://openvpn.net/) and [WireGuard](https://www.wireguard.com/)--### IP-Based Access--If you have a static IP or use a VPN to access your running services, then you can use conditional access to block access to Dashy from everyone except users of your pre-defined IP address. This feature is offered by most cloud providers, and supported by most web servers.--#### Apache--In Apache, this is configured in your `.htaccess` file in Dashy's root folder, and should look something like:--```text-Order Deny,Allow-Deny from all-Allow from [your-ip]-```--#### NGINX--In NGINX you can specify [control access](https://docs.nginx.com/nginx/admin-guide/security-controls/controlling-access-proxied-http/) rules for a given site in your `nginx.conf` or hosts file. For example:--```text-server {- listen 80;- server_name www.dashy.example.com;- location / {- root /path/to/dashy/;- passenger_enabled on;- allow [your-ip];- deny all;- }- }-```--#### Caddy--In Caddy, [Request Matchers](https://caddyserver.com/docs/caddyfile/matchers) can be used to filter requests--```text-dashy.site {- @public_networks not remote_ip [your-ip]- respond @public_networks "Access denied" 403-}-```--### Web Server Authentication--Most web servers make password protecting certain apps very easy. Note that you should also set up HTTPS and have a valid certificate in order for this to be secure.-#### ApacheFirst crate a `.htaccess` file in Dashy's route directory. Specify the auth type and path to where you want to store the password file (usually the same folder). For example:@@ -280,6 +227,10 @@ AuthType BasicAuthName "Please Sign into Dashy"AuthUserFile /path/dashy/.htpasswdrequire valid-user+ProxyPreserveHost On+ProxyPass / http://127.0.0.1:8080/+ProxyPassReverse / http://127.0.0.1:8080/+RequestHeader set X-Remote-User expr=%{REMOTE_USER}```Then create a `.htpasswd` file in the same directory. List users and their hashed passwords here, with one user on each line, and a colon between username and password (e.g. `[username]:[hashed-password]`). You will need to generate an MD5 hash of your desired password, this can be done with an [online tool](https://www.web2generators.com/apache-tools/htpasswd-generator). Your file will look something like:@@ -288,6 +239,8 @@ Then create a `.htpasswd` file in the same directory. List users and their hashealicia:$apr1$jv0spemw$RzOX5/GgY69JMkgV6u16l0```+This will use the X-Remote-User header. This can also be expanded by [mod_auth_ldap, mod_auth_digest, mod_auth_mellon, ...](https://httpd.apache.org/docs/2.4/mod/#A)+#### NGINXNGINX has an [authentication module](https://nginx.org/en/docs/http/ngx_http_auth_basic_module.html) which can be used to add passwords to given sites, and is fairly simple to set up. Similar to above, you will need to create a `.htpasswd` file. Then just enable auth and specify the path to that file, for example:@@ -296,6 +249,9 @@ NGINX has an [authentication module](https://nginx.org/en/docs/http/ngx_http_autlocation / {auth_basic "closed site";auth_basic_user_file conf/htpasswd;+ proxy_pass http://127.0.0.1:8080;+ proxy_set_header X-Forwarded-For $remote_addr;+ proxy_set_header X-Remote-User $remote_user;}```@@ -304,6 +260,10 @@ location / {Caddy has a [basic-auth](https://caddyserver.com/docs/caddyfile/directives/basicauth) directive, where you specify a username and hash. The password hash needs to be base-64 encoded, the [`caddy hash-password`](https://caddyserver.com/docs/command-line#caddy-hash-password) command can help with this. For example:```text+reverse_proxy localhost:8080 {+ header_up -Authorization+ header_up +X-Remote-User {username}+}basicauth /secret/* {alicia JDJhJDEwJEVCNmdaNEg2Ti5iejRMYkF3MFZhZ3VtV3E1SzBWZEZ5Q3VWc0tzOEJwZE9TaFlZdEVkZDhX}@@ -318,7 +278,7 @@ You can use the [mod_auth](https://doc.lighttpd.net/lighttpd2/mod_auth.html) modThen in your `lighttpd.conf` file (usually in the `/etc/lighttpd/` directory), load in the mod_auth module, and configure it's directives. For example:```text-server.modules += ( "mod_auth" )+server.modules += ( "mod_auth","mod_proxy" )auth.debug = 2auth.backend = "plain"auth.backend.plain.userfile = "/home/lighttpd/.lighttpdpassword"@@ -328,17 +288,115 @@ $HTTP["host"] == "dashy.my-domain.net" {server.errorlog = "/var/log/lighttpd/dashy.my-domain.net/error.log"accesslog.filename = "/var/log/lighttpd/dashy.my-domain.net/access.log"auth.require = (- "/docs/" => (+ "" => ("method" => "basic","realm" => "Password protected area","require" => "user=alicia"))+ proxy.server = ("" => (( "host" => "127.0.0.1", "port" => 8080 )))+ proxy.forwarded = ( "for" => 1,+ "proto" => 1,+ "remote_user" => 1+ )}```Restart your web server for changes to take effect.++### 2. Dashy Configuration++With Header Authentication the web server/reverse proxy can add headers that Dashy will trust to be the valid authenticated user. You need to understand how your web server or reverse proxy works and trust it to add these details.++Even though we are trusting the web server for authentication we still use the Dashy user system for groups and rights. [See Setting Up Authentication](#setting-up-authentication) if you haven't set that up yet.++Below is the recomended Header Auth Configuration including some users.++```yaml+appConfig:+ ...+ auth:+ users:+ - user: alicia+ hash: 4D1E58C90B3B94BCAD9848ECCACD6D2A8C9FBC5CA913304BBA5CDEAB36FEEFA3+ type: admin+ - user: bob+ hash: 5E884898DA28047151D0E56F8DC6292773603D0D6AABBDD62A11EF721D1542D8+ enableHeaderAuth: true+ headerAuth:+ userHeader: X-Remote-User+ proxyWhitelist:+ - 127.0.0.1+ - '::1'+```++This allows you to use the standard `hideForUsers`, `showForUsers`, `hideForGroup`, and `showForGroup`. The header can not set the group. This must be done by the `auth.users` config.++++---++## 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:++- [Authentication Server](#authentication-server) - Put Dashy behind a self-hosted auth server+- [VPN](#vpn) - Use a VPN to tunnel into the network where Dashy is running+- [IP-Based Access](#ip-based-access) - Disallow access from all IP addresses, except your own+- [Web Server Authentication](#web-server-authentication) - Enable user control within your web server or proxy+- [OAuth Services](#oauth-services) - Implement a user management system using a cloud provider+- [Password Protection (for cloud providers)](#static-site-hosting-providers) - Enable password-protection on your site++### Authentication Server+++### VPN++A catch-all solution to accessing services running from your home network remotely is to use a VPN. It means you do not need to worry about implementing complex authentication rules, or trusting the login implementation of individual applications. However it can be inconvenient to use on a day-to-day basis, and some public and corporate WiFi block VPN connections. Two popular VPN protocols are [OpenVPN](https://openvpn.net/) and [WireGuard](https://www.wireguard.com/)++### IP-Based Access++If you have a static IP or use a VPN to access your running services, then you can use conditional access to block access to Dashy from everyone except users of your pre-defined IP address. This feature is offered by most cloud providers, and supported by most web servers.++#### Apache++In Apache, this is configured in your `.htaccess` file in Dashy's root folder, and should look something like:++```text+Order Deny,Allow+Deny from all+Allow from [your-ip]+```++#### NGINX++In NGINX you can specify [control access](https://docs.nginx.com/nginx/admin-guide/security-controls/controlling-access-proxied-http/) rules for a given site in your `nginx.conf` or hosts file. For example:++```text+server {+ listen 80;+ server_name www.dashy.example.com;+ location / {+ root /path/to/dashy/;+ passenger_enabled on;+ allow [your-ip];+ deny all;+ }+ }+```++#### Caddy++In Caddy, [Request Matchers](https://caddyserver.com/docs/caddyfile/matchers) can be used to filter requests++```text+dashy.site {+ @public_networks not remote_ip [your-ip]+ respond @public_networks "Access denied" 403+}+```+### OAuth ServicesThere are also authentication services, such as [Ory.sh](https://www.ory.sh/), [Okta](https://developer.okta.com/), [Auth0](https://auth0.com/), [Firebase](https://firebase.google.com/docs/auth/). Implementing one of these solutions would involve some changes to the [`Auth.js`](https://github.com/Lissy93/dashy/blob/master/src/utils/Auth.js) file, but should be fairly straightforward.diff --git a/docs/configuring.md b/docs/configuring.mdindex 9f628b01..5edfcb4a 100644--- a/docs/configuring.md+++ b/docs/configuring.md@@ -36,6 +36,7 @@ The following file provides a reference of all supported configuration options.- [`auth`](#appconfigauth-optional) - Built-in authentication setup- [`users`](#appconfigauthusers-optional) - List or users (for simple auth)- [`keycloak`](#appconfigauthkeycloak-optional) - Auth config for Keycloak+ - [`headerAuth`](#appconfigauthheaderauth-optional) - Auth config for HeaderAuth- [**`sections`**](#section) - List of sections- [`displayData`](#sectiondisplaydata-optional) - Section display settings- [`show/hideForKeycloakUsers`](#sectiondisplaydatahideforkeycloakusers-sectiondisplaydatashowforkeycloakusers-itemdisplaydatahideforkeycloakusers-and-itemdisplaydatashowforkeycloakusers) - Set user controls@@ -147,6 +148,8 @@ The following file provides a reference of all supported configuration options.**`users`** | `array` | _Optional_ | An array of objects containing usernames and hashed passwords. If this is not provided, then authentication will be off by default, and you will not need any credentials to access the app. See [`appConfig.auth.users`](#appconfigauthusers-optional). <br>**Note** this method of authentication is handled on the client side, so for security critical situations, it is recommended to use an [alternate authentication method](/docs/authentication.md#alternative-authentication-methods).**`enableKeycloak`** | `boolean` | _Optional_ | If set to `true`, then authentication using Keycloak will be enabled. Note that you need to have an instance running, and have also configured `auth.keycloak`. Defaults to `false`**`keycloak`** | `object` | _Optional_ | Config options to point Dashy to your Keycloak server. Requires `enableKeycloak: true`. See [`auth.keycloak`](#appconfigauthkeycloak-optional) for more info+**`enableHeaderAuth`** | `boolean` | _Optional_ | If set to `true`, then authentication using HeaderAuth will be enabled. Note that you need to have your web server/reverse proxy running, and have also configured `auth.headerAuth`. Defaults to `false`+**`headerAuth`** | `object` | _Optional_ | Config options to point Dashy to your headers for authentication. Requires `enableHeaderAuth: true`. See [`auth.headerAuth`](#appconfigauthheaderauth-optional) for more info**`enableGuestAccess`** | `boolean` | _Optional_ | When set to `true`, an unauthenticated user will be able to access the dashboard, with read-only access, without having to login. Requires `auth.users` to be configured. Defaults to `false`.For more info, see the **[Authentication Docs](/docs/authentication.md)**@@ -174,6 +177,15 @@ For more info, see the **[Authentication Docs](/docs/authentication.md)****[⬆️ Back to Top](#configuring)**+## `appConfig.auth.headerAuth` _(optional)_++**Field** | **Type** | **Required**| **Description**+--- | --- | --- | ---+**`userHeader`** | `string` | _Optional_ | The Header name which contains username (default: REMOTE_USER). Case insensitive+**`proxyWhitelist`** | `array` | Required | An array of Upstream proxy servers to expect authencticated requests from++**[⬆️ Back to Top](#configuring)**+## `appConfig.webSearch` _(optional)_**Field** | **Type** | **Required**| **Description**