Merge pull request #1581 from CrazyWolf13/master

🧾 [docs](add) keycloak troubleshooting

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: