From e797504d50e35e2a66aba1c97ab386f08363132e Mon Sep 17 00:00:00 2001
From: Isolator acm <acm@Sunny.local>
Date: Mon, 22 Jun 2026 17:20:19 +0200
Subject: [PATCH] docs(readme): show the SSO-only (basic_login:false) config +
 when to use it
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The credentials section described `basic_login:false` in prose but only gave a
credentials-only JSON example. Add the missing SSO-only example (the flag set
alongside `idps`) and a one-line rationale — hide the password path when the
cluster has no password-authenticated CH users (pure JWT), noting that some
verifier setups still pass real CH users through, so it's about what the server
authenticates, not merely "uses OAuth". Also show the credentials-only config as
just `{}`.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QennTvGKAtJZrv9EpQagef
---
 README.md | 26 ++++++++++++++++++++++----
 1 file changed, 22 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index e99bb5d..760473e 100644
--- a/README.md
+++ b/README.md
@@ -110,12 +110,30 @@ one matches the token's `iss`, so no extra CH wiring is required to offer severa
 ### Credentials login (username / password)
 
 Alongside SSO, the sign-in screen offers a **ClickHouse username + password**
-path (HTTP Basic). It is shown by default; set top-level `"basic_login": false`
-in `config.json` to hide it and force SSO-only. A deployment with no OAuth at all
-can ship a credentials-only config (no `idps`):
+path (HTTP Basic), shown by default.
+
+**Hide it (SSO-only).** If the cluster has no password-authenticated CH users —
+e.g. it only accepts JWTs via a `token_processor`/verifier — the credentials path
+would just 401, so set top-level `"basic_login": false` to drop it and offer SSO
+only:
+
+```json
+{
+  "basic_login": false,
+  "idps": [ { "id": "google", "issuer": "https://accounts.google.com", "client_id": "…" } ]
+}
+```
+
+(Some verifier setups *do* pass real CH password users through — e.g. a cluster
+with a `demo` user still accepts `demo`/password — so whether to hide the path is
+about what that server actually authenticates, not just "does it use OAuth".)
+
+**Credentials-only (no SSO).** A deployment with no OAuth can omit `idps`
+entirely; the SSO buttons disappear and only the username/password form shows
+(`basic_login` defaults on):
 
 ```json
-{ "basic_login": true }
+{}
 ```
 
 Credentials authenticate against the **serving host** by default. The login