From 79406f48707e0a33a47660fbb036a7c98a07dc9e Mon Sep 17 00:00:00 2001 From: Liss-Bot Date: Mon, 13 May 2024 20:57:51 +0000 Subject: [PATCH] Update documentation --- docs/authentication.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/docs/authentication.md b/docs/authentication.md index 061eb3d1..4d005517 100644 --- a/docs/authentication.md +++ b/docs/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) @@ -251,6 +252,26 @@ Your app is now secured :) When you load Dashy, it will redirect to your Keycloa From 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. +--- + +### 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: