diff --git a/README.md b/README.md index bd20c823..4b8e0ab6 100644 --- a/README.md +++ b/README.md @@ -134,6 +134,24 @@ All data is encrypted before being sent to the backend. In Dashy, this is done i --- +## Authentication 💂 + +> For full development documentation, see: [**Authentication**](./docs/authentication.md) + +Dashy has a built-in login feature, which can be used for basic access control. To enable this feature, add an `auth` attribute under `appConfig`, containing an array of users, each with a username, SHA-256 hashed password and optional user type. + +```yaml +appConfig: + auth: + - user: alicia + hash: 4D1E58C90B3B94BCAD9848ECCACD6D2A8C9FBC5CA913304BBA5CDEAB36FEEFA3 +``` +At present, access control is handles on the frontend, and therefore in security-critical applications, it is recommended to use VPN access for authentication. + +**[⬆️ Back to Top](#dashy)** + +--- + ## Developing 🧱 > For full development documentation, see: [**Developing**](./docs/developing.md) diff --git a/docs/authentication.md b/docs/authentication.md index a8b82e84..d78d0e69 100644 --- a/docs/authentication.md +++ b/docs/authentication.md @@ -1,6 +1,6 @@ # Authentication -- [Build-In Login Feature](#authentication) +- [Built-In Login Feature](#authentication) - [Setting Up Authentication](#setting-up-authentication) - [Hash Password](#hash-password) - [Logging In and Out](#logging-in-and-out) @@ -12,7 +12,6 @@ - [OAuth Services](#oauth-services) - [Auth on Cloud Hosting Services](#static-site-hosting-providers) - Dashy has a basic login page included, and frontend authentication. You can enable this by adding users to the `auth` section under `appConfig` in your `conf.yml`. If this section is not specified, then no authentication will be required to access the app, and it the homepage will resolve to your dashboard. ## Setting Up Authentication @@ -56,14 +55,13 @@ If you are hosting Dashy locally, and require remote access, it is recommend to - OAuth Services - Password Protection (for cloud providers) - ### VPN -The most secure method for accessing Dashy and other self-hosted services remotely is through a VPN connection, using something like [OpenVPN]() or [WireGuard]() +The most secure method for accessing Dashy and other self-hosted services remotely is through a VPN connection, using something like [OpenVPN](https://openvpn.net/) or [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 +##### Apache In Apache, this is configured in your `.htaccess` file in Dashy's root folder, and should look something like: ``` Order Deny,Allow @@ -71,7 +69,7 @@ Deny from all Allow from [your-ip] ``` -#### NGINX +##### 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: ``` server { @@ -86,7 +84,7 @@ server { } ``` -#### Caddy +##### Caddy In Caddy, [Request Matchers](https://caddyserver.com/docs/caddyfile/matchers) can be used to filter requests ``` dashy.site { @@ -98,7 +96,7 @@ dashy.site { ### 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. -#### Apache +##### Apache First 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: ``` AuthType Basic @@ -112,7 +110,7 @@ Then create a `.htpasswd` file in the same directory. List users and their hashe alicia:$apr1$jv0spemw$RzOX5/GgY69JMkgV6u16l0 ``` -#### NGINX +##### NGINX NGINX 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: ``` location / { @@ -120,7 +118,7 @@ location / { auth_basic_user_file conf/htpasswd; } ``` -#### Caddy +##### Caddy 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: ``` basicauth /secret/* { @@ -128,7 +126,7 @@ basicauth /secret/* { } ``` -#### Lighttpd +##### Lighttpd You can use the [mod_auth](https://doc.lighttpd.net/lighttpd2/mod_auth.html) module to secure your site with Lighttpd. Like with Apache, you need to first create a password file listing your usersnames and hashed passwords, but in Lighttpd, it's usually called `.lighttpdpassword`. Then in your `lighttpd.conf` file (usually in the `/etc/lighttpd/` directory), load in the mod_auth module, and configure it's directives. For example: diff --git a/docs/getting-started.md b/docs/getting-started.md index a2aa4222..cf44a0fe 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -305,5 +305,7 @@ Then restart Apache, with `sudo systemctl restart apache2` ## Authentication +Dashy has built-in client-side authentication, but for security-critical situations, it is recommend to either use a VPN for access, or implement your own authentication using your cloud provider, web server or firewall rules. For more info, see **[Authentication Docs](/docs/authentication.md)**. + **[⬆️ Back to Top](#getting-started)**