From 314019abcdcdb956963069bb7d996e8018930971 Mon Sep 17 00:00:00 2001 From: Matthias Linhuber Date: Thu, 27 Aug 2026 19:51:27 +0200 Subject: [PATCH] docs: correct the Keycloak client redirect URIs, and add the two lists that were missing The client needs redirect URIs for the landing and instance hosts only, not for all four of the installation's hostnames - the REST service host and the `*.webview.instance.` wildcard take no part in the browser redirect flow. Two settings that were previously shown as `+`, and therefore never actually described, are required: Valid post logout redirect URIs https:/// https:///* Web origins https:// https://instance. The post-logout list needs both the bare `/` and the `/*` form. Every value carries the https:// scheme. The previous text went further than being incomplete: it warned "All four, not two" and told readers that listing only the landing and instance hosts was a mistake that would break webviews. That is the correct configuration, so the warning would have led people to add entries they do not need. Replaced with a note saying the other two hosts are deliberately absent, since the next person to see two entries where four hostnames exist will otherwise assume it is a bug. Four hostnames remains right for DNS and certificates. Only the client differs. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_019qeiQRFu8xAMRYWPdZewjG --- docs/admins/install/adding-an-installation.md | 5 +- docs/admins/install/prerequisites.md | 5 +- docs/admins/platform/access-control.md | 46 ++++++++++++------- 3 files changed, 36 insertions(+), 20 deletions(-) diff --git a/docs/admins/install/adding-an-installation.md b/docs/admins/install/adding-an-installation.md index 8ce6efa..ccdfd60 100644 --- a/docs/admins/install/adding-an-installation.md +++ b/docs/admins/install/adding-an-installation.md @@ -69,8 +69,9 @@ Read the diff, then run it again with `dry_run: false`. ## 4. Outside the repositories - **DNS** for all four hostnames. -- **Keycloak**: a client matching `clientId`, with redirect URIs for all four - hosts. A wrong realm or client fails at login, not at deploy, so nothing in CI +- **Keycloak**: a client matching `clientId`, with redirect URIs for the landing + and instance hosts, post-logout redirect URIs for the landing host, and web + origins for both. See [Access Control](../platform/access-control.md). catches it. - **The webview wildcard certificate**, which cert-manager cannot issue over HTTP-01. It goes in the cluster's bootstrap environment as diff --git a/docs/admins/install/prerequisites.md b/docs/admins/install/prerequisites.md index 3f77503..e59532f 100644 --- a/docs/admins/install/prerequisites.md +++ b/docs/admins/install/prerequisites.md @@ -142,8 +142,9 @@ EduIDE authenticates through OIDC, tested against Keycloak. You need: - A realm your students can authenticate to. - A **public** client — EduIDE's landing page is a browser application and holds no secret. -- Redirect URIs for **all four** of the installation's hostnames. Three is a - common mistake and breaks webviews specifically. +- Redirect URIs for the landing page and instance hosts, post-logout redirect + URIs for the landing host, and web origins for both. Four hostnames need DNS + and certificates, but the Keycloak client only names two of them. See [Access Control](../platform/access-control.md) for the full client setup. diff --git a/docs/admins/platform/access-control.md b/docs/admins/platform/access-control.md index 94e6451..76c7341 100644 --- a/docs/admins/platform/access-control.md +++ b/docs/admins/platform/access-control.md @@ -53,27 +53,41 @@ Click **Next**. Set URLs based on the target environment domain. For production: ``` -Root URL: https:// -Home URL: https:// +Root URL: https:// +Home URL: https:// Valid redirect URIs: https:///* - https://service./* https://instance./* - https://*.webview.instance./* -Valid post-logout redirect URIs: + -Web origins: + +Valid post logout redirect URIs: + https:/// + https:///* +Web origins: + https:// + https://instance. ``` -:::warning All four, not two -An installation serves four hostnames and every one of them takes part in the -login flow. Listing only the landing and instance hosts is a common mistake with -a confusing result: login appears to work, and then **webviews inside the IDE -fail to authenticate** — a failure users hit days later and report as "previews -are broken". +Every entry carries the `https://` scheme. The redirect URIs and web origins +cover **two** hosts, the landing page and the instance host; the post-logout +entries cover the landing host only, and need both the bare `/` and the `/*` +form. + +For an installation at `eduide.example.edu` that is: -Substitute your own landing host; for an installation at `eduide.example.edu` -the four are `eduide.example.edu`, `service.eduide.example.edu`, -`instance.eduide.example.edu` and `*.webview.instance.eduide.example.edu`. +| Setting | Values | +|---|---| +| Valid redirect URIs | `https://eduide.example.edu/*`
`https://instance.eduide.example.edu/*` | +| Valid post logout redirect URIs | `https://eduide.example.edu/`
`https://eduide.example.edu/*` | +| Web origins | `https://eduide.example.edu`
`https://instance.eduide.example.edu` | + +:::note The service and webview hosts are deliberately absent +An installation serves four hostnames, but only two of them appear here. The +REST service host and the `*.webview.instance.` wildcard do not take part in the +browser redirect flow, so adding them is unnecessary. Do not "fix" this list by +padding it out to four. + +Four hostnames **is** the right number for DNS and for certificates - see +[Certificates and DNS](../install/certificates.md). Only the Keycloak client is +different. ::: Repeat this for each installation — one client per installation, because each @@ -191,7 +205,7 @@ openssl rand -base64 32 The browser redirects continuously between the application and Keycloak. Causes and fixes: -- **Incorrect redirect URI** — verify that both the landing page and instance domains are in the client's valid redirect URIs, including the `/*` wildcard suffix +- **Incorrect redirect URI** — verify that the landing page and instance hosts are both in the client's valid redirect URIs, each with the `/*` suffix, and that the web origins list both hosts without a suffix - **Cookie secret mismatch** — confirm `THEIA_KEYCLOAK_COOKIE_SECRET` in GitHub secrets matches what was deployed - **HTTP/HTTPS mismatch** — all redirect URIs and the environment URL must use HTTPS