From c3b199361ce2e528e452478a14712ed32a420c46 Mon Sep 17 00:00:00 2001 From: Tobias Date: Mon, 13 May 2024 22:24:10 +0200 Subject: [PATCH] =?UTF-8?q?=F0=9F=A7=BE=20[docs](add)=20keycloak=20trouble?= =?UTF-8?q?shooting?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/authentication.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/docs/authentication.md b/docs/authentication.md index 016e905f..d7189b37 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: