docs: add Keycloak SSO setup guide

.env.example

@@ -85,6 +85,11 @@ LOG_LEVEL=info
 # both Keycloak clients ("mcp-gateway" for the gateway's own /admin UI,
 # "contextforge-web-ui" for this BFF) are seeded directly in that repo's
 # infra/keycloak/realm-export.json, no manual admin-console setup needed.
+#
+# Setting this up against a Keycloak that ISN'T mcp-context-forge's own
+# compose-sso stack (e.g. a real deployment)? See docs/sso-keycloak-setup.md
+# for client registration, the redirect-URI gotcha, and the gateway-side
+# trusted_for_api_auth step it also requires.
 SSO_ENABLED=false
 # SSO_KEYCLOAK_BASE_URL=http://localhost:8180
 # Only needed if the browser-facing Keycloak host differs from the one above

.env.prod.example

@@ -60,6 +60,8 @@ LOG_LEVEL=info
 
 # Keycloak SSO login. Leave SSO_ENABLED=false to skip. When enabled,
 # BASE_URL/REALM/CLIENT_ID/CLIENT_SECRET are required; PUBLIC_BASE_URL is optional, SCOPES/TTL default.
+# Full setup (Keycloak client registration, redirect-URI gotcha, the
+# gateway-side trusted_for_api_auth step): docs/sso-keycloak-setup.md
 SSO_ENABLED=false
 SSO_KEYCLOAK_BASE_URL=
 # Only needed if the browser-facing Keycloak host differs from the one above.

docs/DOCKER.md

@@ -101,6 +101,14 @@ the compose default). If you see the `memory-redis` warning in
 `docker compose logs app` and didn't ask for it, check `.env` isn't
 setting `REDIS_URL=memory://`.
 
+## SSO (Keycloak)
+
+`SSO_ENABLED=false` by default — the container boots the same either way,
+nothing extra to configure for a plain password-login deployment. Turning
+it on needs a Keycloak client registered for this BFF (separate from the
+gateway's own) and a one-time gateway-side admin-API step with no env var
+equivalent — see [`sso-keycloak-setup.md`](./sso-keycloak-setup.md).
+
 ## Local TLS (self-signed certs)
 
 `npm run certs` generates a self-signed cert/key pair for local HTTPS