diff --git a/authentication.md b/authentication.md index 4430d9b..d7189b3 100644 --- a/authentication.md +++ b/authentication.md @@ -14,6 +14,7 @@ - [Deploying Keycloak](#1-deploy-keycloak) - [Setting up Keycloak](#2-setup-keycloak-users) - [Configuring Dashy for Keycloak](#3-enable-keycloak-in-dashy-config-file) + - [Toubleshooting Keycloak](#troubleshooting-keycloak) - [Alternative Authentication Methods](#alternative-authentication-methods) - [VPN](#vpn) - [IP-Based Access](#ip-based-access) @@ -253,6 +254,67 @@ From within the Keycloak console, you can then configure things like time-outs, --- +### Troubleshooting Keycloak + +If you encounter issues with your Keycloak setup, follow these steps to troubleshoot and resolve common problems. + +1. Client Authentication Issue +Problem: Redirect loop, if client authentication is enabled. +Solution: Switch off "client authentication" in "TC clients" -> "Advanced" settings. + +2. Double URL +Problem: If you get redirected to "https://dashy.my.domain/#iss=https://keycloak.my.domain/realms/my-realm" +Solution: Make sure to turn on "Exclude Issuer From Authentication Response" in "TC clients" -> "Advanced" -> "OpenID Connect Compatibility Modes" + +3. Problems with mutiple Dashy Pages +Problem: Refreshing or logging out of dashy results in an "invalid_redirect_uri" error. +Solution: In "TC clients" -> "Access settings" -> "Root URL" https://dashy.my.domain/, valid redirect URIs must be /* + +--- + +## OIDC + +Dashy also supports using a general [OIDC compatible](https://openid.net/connect/) authentication server. In order to use it, the authentication section needs to be configured: + +```yaml +appConfig: + auth: + enableOidc: true + oidc: + clientId: [registered client id] + endpoint: [OIDC endpoint] +``` + +Because Dashy is a SPA, a [public client](https://datatracker.ietf.org/doc/html/rfc6749#section-2.1) registration with PKCE is needed. + +An example for Authelia is shared below, but other OIDC systems can be used: + +```yaml +identity_providers: + oidc: + clients: + - client_id: dashy + client_name: dashy + public: true + authorization_policy: 'one_factor' + require_pkce: true + pkce_challenge_method: 'S256' + redirect_uris: + - https://dashy.local # should point to your dashy endpoint + grant_types: + - authorization_code + scopes: + - 'openid' + - 'profile' + - 'roles' + - 'email' + - 'groups' +``` + +Groups and roles will be populated and available for controlling display similar to [Keycloak](#Keycloak) abvoe. + +--- + ## 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/configuring.md b/configuring.md index 3bcb0d4..acf9357 100644 --- a/configuring.md +++ b/configuring.md @@ -158,6 +158,8 @@ The following file provides a reference of all supported configuration options. **`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 +**`enableOidc`** | `boolean` | _Optional_ | If set to `true`, then authentication using OIDC will be enabled. Note that you need to have a configured OIDC server and configure it with `auth.oidc`. Defaults to `false` +**`oidc`** | `object` | _Optional_ | Config options to point Dash to your OIDC configuration. Request `enableOidc: true`. See [`auth.oidc`](#appconfigauthoidc-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)** @@ -194,6 +196,15 @@ For more info, see the **[Authentication Docs](/docs/authentication.md)** **[⬆️ Back to Top](#configuring)** +## `appConfig.auth.oidc` _(optional)_ + +**Field** | **Type** | **Required**| **Description** +--- | --- | --- | --- +**`clientId`** | `string` | Required | The client id registered in the OIDC server +**`endpoint`** | `string` | Required | The URL of the OIDC server that should be used. + +**[⬆️ Back to Top](#configuring)** + ## `appConfig.webSearch` _(optional)_ **Field** | **Type** | **Required**| **Description** diff --git a/credits.md b/credits.md index b681413..af1032e 100644 --- a/credits.md +++ b/credits.md @@ -140,13 +140,6 @@ Forward Email - Open-source & Privacy-focused Email Service (2023) - - - lamtrinhdev -
- LamTrinh.Dev - - Bastii717 @@ -174,15 +167,15 @@
Null - - + terminaltrove
Terminal Trove - + + NixyJuppie @@ -239,20 +232,20 @@ Snyk Bot - - - azerioxal -
- Kenneth Church - - - CrazyWolf13
Tobias + + + + + azerioxal +
+ Kenneth Church + @@ -548,6 +541,13 @@ + + + twsouthwick +
+ Taylor Southwick + + GuilhermeLCS95 @@ -582,15 +582,15 @@
Stephen Rigney - + + a-mnich
Alexander Mnich - - + alayham @@ -605,6 +605,13 @@ Alessandro Del Prete + + + turnrye +
+ Ryan Turner + + sachahjkl @@ -618,7 +625,8 @@
Shazz - + + ThinkSalat @@ -632,8 +640,7 @@
Null - - + Smexhy @@ -661,20 +668,6 @@
Steven Kast - - - - twsouthwick -
- Taylor Southwick - - - - - turnrye -
- Ryan Turner - @@ -734,6 +727,13 @@ Mert Sefa AKGUN + + + maximemoreillon +
+ Maxime Moreillon + + AmadeusGraves @@ -754,15 +754,15 @@
José Ignacio - + + soaibsafi
Soaibuzzaman - - + pablomalo @@ -797,15 +797,15 @@
Null - + + jnach
Jnach - - + imlonghao @@ -840,15 +840,15 @@
Nico - + + baifengheixi
Null - - + allozavrr @@ -864,10 +864,10 @@ - - maximemoreillon + + Glitch3dPenguin
- Maxime Moreillon + Max Kulik @@ -883,15 +883,15 @@
Eduardo Gomez - + + Dylan-Bs
Dylan Bersans - - + dyauss @@ -926,15 +926,15 @@
Null - + + skaarj1989
David - - + clsty @@ -969,15 +969,15 @@
Jyotirmoy Bandyopadhyaya [Bravo68] - + + AaronPorts
Artyom - - + alydemah @@ -999,13 +999,6 @@ 0n1cOn3 - - - Glitch3dPenguin -
- Max Kulik - - markusdd @@ -1121,6 +1114,13 @@ FormatToday + + + pvillaverde +
+ Fedello + + ethan-hann