📝 Adds docs for Keycloak authentication

2024-11-23 12:43:52 +03:00 · 2021-08-21 22:44:12 +01:00 · 2021-08-21 22:44:12 +01:00 · 75ec158f85
commit 75ec158f85
parent 3543116451
2 changed files with 92 additions and 14 deletions
--- a/README.md
+++ b/README.md
@ -64,8 +64,8 @@
 - Option to show service status for each of your apps / links, for basic availability and uptime monitoring
 - Choose how to launch apps, either in your browser, a pop-up modal or workspace view
 - Option for full-screen background image, custom nav-bar links, html footer, title, and more
- Encrypted cloud backup and restore feature available
- Optional authentication, requiring admins and non-privileged users to log in
+- Optional encrypted cloud backup and restore feature available
+- Optional authentication with multi-user support and configurable privileges for protecting your dashboard
 - Small bundle size, fully responsive UI and PWA makes the app easy to use on any device
 - Easy to setup with Docker, or on bare metal, or with 1-Click cloud deployment
 - Multi-language support, with more languages being added regularly
@ -243,18 +243,22 @@ You can also specify an time interval in seconds under `appConfig.statusCheckInt

 > For full authentication 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.
+Dashy has full support for [Keycloak](https://www.keycloak.org/), for securing your dashboard.
+
+There is also a simple login feature for basic access control, which doesn't require any additional setup. 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:
+    users:
    - user: alicia
      hash: 4D1E58C90B3B94BCAD9848ECCACD6D2A8C9FBC5CA913304BBA5CDEAB36FEEFA3
+      type: admin
 ```

-By default, when authentication is configured no user can access your dashboard without first logging in. If you would like to allow for read-only access by unauthenticated users, then you can enable guest mode, by setting `appConfig.enableGuestAccess: true`.
+**Guest Access**: By default, when authentication is configured no user can access your dashboard without first logging in. If you would like to allow for read-only access by unauthenticated users, then you can enable guest mode, by setting `appConfig.auth.enableGuestAccess: true`.

-**Note**: At present, access control is handled on the frontend, and therefore in security-critical situations, it is recommended to use an alternate method for authentication, such as [Authelia](https://www.authelia.com/), a VPN or web server and firewall rules. Instructions for setting this up can be found [in the docs](docs/authentication.md#alternative-authentication-methods).
+**Note**: Using the above method involved access control being handled on the frontend, and therefore in security-critical situations, it is recommended to use an alternate method for authentication. Keycloak is [natively supported](docs/authentication.md#keycloak), but you could also use [Authelia](https://www.authelia.com/), a VPN or web server and firewall rules. Instructions for all of these can be found [in the docs](docs/authentication.md#alternative-authentication-methods).

 <p align="center">
  <img
@ -265,6 +269,10 @@ By default, when authentication is configured no user can access your dashboard
  />
 </p>

+**Granular Controls**: With basic login, it is also possible to control which sections are visible to which users. Under the `displayData` property of a section, you can pass an array of usernames to  one of the following attributes:
+- `hideForUsers` - Section will be visible to all users, except for those specified in this list
+- `showForUsers` - Section will be hidden from all users, except for those specified in this list
+- `hideForGuests` - Section will be visible for all logged in users, but not for guests (if guest access is enabled)

 **[⬆️ Back to Top](#dashy)**

--- a/docs/authentication.md
+++ b/docs/authentication.md
@ -1,10 +1,14 @@
 # Authentication

- [Built-In Login Feature](#authentication)
+- [Built-In Login Feature](#built-in-auth)
 	- [Setting Up Authentication](#setting-up-authentication)
 	- [Hash Password](#hash-password)
 	- [Logging In and Out](#logging-in-and-out)
 	- [Security](#security)
+- [Keycloak Auth](#keycloak)
+  - [1. Deploying Keycloak](#1-deploy-deycloak)
+  - [2. Setting up Keycloak](#2-setup-keycloak-users)
+  - [3. Configuring Dashy for Keycloak](#3-enable-keycloak-in-dashy-config-file)
 - [Alternative Authentication Methods](#alternative-authentication-methods)
 	- [VPN](#vpn)
 	- [IP-Based Access](#ip-based-access)
@ -14,32 +18,35 @@

 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
+## Built-In Auth
+
+### Setting Up Authentication
 The `auth` property takes an array of users. Each user needs to include a username, hash and optional user type (`admin` or `normal`). The hash property is a [SHA-256 Hash](https://en.wikipedia.org/wiki/SHA-2) of your desired password. 

 For example:
 ```yaml
 appConfig:
  auth:
+    users:
    - user: alicia
      hash: 4D1E58C90B3B94BCAD9848ECCACD6D2A8C9FBC5CA913304BBA5CDEAB36FEEFA3
      type: admin
-    - user: edward
+    - user: bob
      hash: 5E884898DA28047151D0E56F8DC6292773603D0D6AABBDD62A11EF721D1542D8
-      type: admin
 ```
-## Hash Password
+
+### Hash Password
 Dashy uses [SHA-256 Hash](https://en.wikipedia.org/wiki/Sha-256), a 64-character string, which you can generate using an online tool, such as [this one](https://passwordsgenerator.net/sha256-hash-generator/) or [CyberChef](https://gchq.github.io/CyberChef/) (which can be self-hosted/ ran locally).

 A hash is a one-way cryptographic function, meaning that it is easy to generate a hash for a given password, but very hard to determine the original password for a given hash. This means, that so long as your password is long, strong and unique, it is safe to store it's hash in the clear. Having said that, you should never reuse passwords, hashes can be cracked by iterating over known password lists, generating a hash of each.

-## Logging In and Out
+### Logging In and Out
 Once authentication is enabled, so long as there is no valid token in cookie storage, the application will redirect the user to the login page. When the user enters credentials in the login page, they will be checked, and if valid, then a token will be generated, and they can be redirected to the home page. If credentials are invalid, then an error message will be shown, and they will remain on the login page. Once in the application, to log out the user can click the logout button (in the top-right), which will clear cookie storage, causing them to be redirected back to the login page.

-## Enabling Guest Access
+### Enabling Guest Access
 With authentication setup, by default no access is allowed to your dashboard without first logging in with valid credentials. Guest mode can be enabled to allow for read-only access to a secured dashboard by any user, without the need to log in. A guest user cannot write any changes to the config file, but can apply modifications locally (stored in their browser). You can enable guest access, by setting `appConfig.enableGuestAccess: true`.

-## Granular Access
+### Granular Access
 You can use the following properties to make certain sections only visible to some users, or hide sections from guests.
 - `hideForUsers` - Section will be visible to all users, except for those specified in this list
 - `showForUsers` - Section will be hidden from all users, except for those specified in this list
@ -66,7 +73,7 @@ For Example:
    ...
 ```

-## Security
+### Security
 Since all authentication is happening entirely on the client-side, it is vulnerable to manipulation by an adversary. An attacker could look at the source code, find the function used generate the auth token, then decode the minified JavaScript to find the hash, and manually generate a token using it, then just insert that value as a cookie using the console, and become a logged in user. Therefore, if you need secure authentication for your app, it is strongly recommended to implement this using your web server, or use a VPN to control access to Dashy. The purpose of the login page is merely to prevent immediate unauthorized access to your homepage.

 Addressing this is on the todo list, and there are several potential solutions:
@ -78,6 +85,69 @@ Addressing this is on the todo list, and there are several potential solutions:

 ---

+## Keycloak
+
+Dashy also supports using a [Keycloack](https://www.keycloak.org/) authentication server.
+
+[Keycloak](https://www.keycloak.org/about.html) is a Java-based [open source](https://github.com/keycloak/keycloak), high-performance, secure authentication system, supported by [RedHad](https://www.redhat.com/en). It is easy to setup ([with Docker](https://quay.io/repository/keycloak/keycloak)), and enables you to secure multiple self-hosted applications with single-sign on using standard protocols (OpenID Connect, OAuth 2.0, SAML 2.0 and social login). It's also very customizable, you can write or use custom [themes](https://wjw465150.gitbooks.io/keycloak-documentation/content/server_development/topics/themes.html), [plugins](https://www.keycloak.org/extensions.html), [password policies](https://wjw465150.gitbooks.io/keycloak-documentation/content/server_admin/topics/authentication/password-policies.html) and more.
+The following guide will walk you through setting up Keycloak with Dashy. If you already have a Keycloak instance configured, then skip to Step 3.
+
+### 1. Deploy Keycloak
+
+First thing to do is to spin up a new instance of Keycloak. You will need [Docker installed](https://docs.docker.com/engine/install/), and can then choose a tag, and pull the container from [quay.io/keycloak/keycloak](https://quay.io/repository/keycloak/keycloak)
+
+Use the following run command, replacing the attributes (default credentials, port and name), or incorporate this into your docker-compose file.
+
+```bash
+docker run -d \
+  -p 8081:8080 \
+  --name auth-server \
+  -e KEYCLOAK_USER=admin \
+  -e KEYCLOAK_PASSWORD=admin \
+  quay.io/keycloak/keycloak:15.0.2
+```
+
+If you need to pull from DockerHub, a non-official image is available [here](https://registry.hub.docker.com/r/jboss/keycloak). Or if you would prefer not to use Docker, you can also directly install Keycloak from source, following [this guide](https://www.keycloak.org/docs/latest/getting_started/index.html).
+
+You should now be able to access the Keycloak web interface, using the port specified above (e.g. `http://127.0.0.1:8081`), login with the default credentials, and when prompted create a new password.
+
+### 2. Setup Keycloak Users
+
+Before we can use Keycloak, we must first set it up with some users. Keycloak uses Realms (similar to tenants) to create isolated groups of users. You must create a Realm before you will be able to add your first user. 
+1. Head over to the admin console
+2. In the top-left corner there is a dropdown called 'Master', hover over it and then click 'Add Realm'
+3. Give your realm a name, and hit 'Create'
+
+You can now create your first user.
+1. In the left-hand menu, click 'Users', then 'Add User'
+2. Fill in the form, including username and hit 'Save'
+3. Under the 'Credentials' tab, give the new user an initial password. They will be prompted to change this after first login
+
+The last thing we need to do in the Keycloak admin console is to create a new client
+1. Within your new realm, navigate to 'Clients' on the left-hand side, then click 'Create' in the top-right
+2. Choose a 'Client ID', set 'Client Protocol' to 'openid-connect', and for 'Valid Redirect URIs' put a URL pattern to where you're hosting Dashy (if you're just testing locally, then * is fine), and do the same for the 'Web Origins' field
+3. Make note of your client-id, and click 'Save'
+
+### 3. Enable Keycloak in Dashy Config File
+Now that your Keycloak instance is up and running, all that's left to do is to configure Dashy to use it. Under `appConfig`, set `auth.enableKeycloak: true`, then fill in the details in `auth.keycloak`, including: `serverUrl` - the URL where your Keycloak instance is hosted, `realm` - the name you gave your Realm, and `clientId` - the Client ID you chose.
+For example:
+
+```yaml
+appConfig:
+  ...
+  auth:
+    enableKeycloak: true
+    keycloak:
+      serverUrl: 'http://localhost:8081'
+      realm: 'alicia-homelab'
+      clientId: 'dashy'
+```
+Your app is now secured :) When you load Dashy, it will redirect to your Keycloak login page, and any user without valid credentials will be prevented from accessing your dashboard.
+
+From within the Keycloak console, you can then configure things like user permissions, time outs, password policies, access, etc
+
+---
+
 ## Alternative Authentication Methods

 If you are self-hosting Dashy, and require secure authentication to prevent unauthorized access, you have several options: