Repository navigation
Description
Summary
ch-oauth-ldap authenticates ephemeral ClickHouse users and maps their roles on every tracked ClickHouse build, but distributed-query authorization with externally assigned roles depends on two upstream ClickHouse bugs. This issue tracks the compatibility matrix, the upstream fixes, and the work to bring 24.8 Altinity Stable back to full support once a bugfix release carries them.
Verified live by integration/clickhouse/run-all-builds.sh (see integration/clickhouse/lib/expectations.sh for the per-build expectations and docs/ch-oauth-ldap-operator-guide.md §1 for the operator-facing statement).
Compatibility matrix (as of 2026-08-29)
| Capability | 24.8 (24.8.11.51285.altinitystable) |
25.3 | 25.8 (25.8.28.10001.altinitystable) |
26.3 |
|---|---|---|---|---|
Ephemeral-user auth, currentUser(), dynamic currentRoles(), role refresh on reconnect, local-user precedence |
✅ | ✅ | ✅ | ✅ |
Distributed query over base tables keeps the pushed external roles on remote nodes |
❌ expected-fail (bug 1) | ❌ expected-fail (bug 1) | ✅ | ✅ |
Distributed query over a normal VIEW keeps the pushed external roles |
❌ (bug 2) | ❌ (bug 2) | ❌ (bug 2) | ❌ (bug 2) |
LDAP search_limit overflow (257 mapped roles vs <search_limit>256</search_limit>) |
auth fails closed (HTTP 403), measured | not measured (fixture fails closed on untracked lines) | auth fails closed (HTTP 403), measured | not measured |
24.8 and 25.8 are the tracked builds (run-all-builds.sh); 25.3 and 26.3 were characterized in a one-off sweep and can be run ad hoc via PHASE3_CH_IMAGE.
The two upstream bugs
- Pushed external roles are filtered against the ephemeral user's (empty) local grants on the remote node — External roles are not transferred during LDAP authentication when querying a distributed table. ClickHouse/ClickHouse#78791, fixed by Fix passing of external roles in interserver query (and better test) ClickHouse/ClickHouse#79099 ("Fix passing of external roles in interserver query", merged 2025-06-09). 24.8 contains #70332 (the
push_external_roles_in_interserver_queriesmechanism) so the roles are pushed and the remote logsexternal_roles applied, but the query is still denied. No 24.8 Altinity Stable release through 24.8.14.10547 carries #79099. Fixed in 25.8+. - Pushed external roles are lost when the remote query reads through a normal VIEW (
ContextDatacopy constructor omitsexternal_roles) — Pushed external roles (push_external_roles_in_interserver_queries) are lost when the remote que 8000 ry reads through a normal VIEW ClickHouse/ClickHouse#116840, filed by us 2026-08-28, open, reproduces on every line through 26.3. The fixture tracks it as an expected-fail canary (scenario H view oracle) so a fix is detected automatically.
What "24.8 fully supported" requires
- An Altinity Stable 24.8.x bugfix release that backports #79099 (bug 1). Bug 2 (#116840) additionally needs an upstream fix and its backport; until then VIEW-based distributed authorization stays unsupported on every line, and that is documented rather than blocked on.
Work items when such a release exists
- Add the new 24.8.x image to
integration/clickhouse/run-all-builds.sh(keep the current 24.8.11 baseline until the new one is verified, then replace or keep both). - Flip
H_base_table_propagation:24.8fromexpected_failtomust_passinintegration/clickhouse/lib/expectations.shonly after./integration/clickhouse/run-all-builds.shshows scenario H passing on that image (the fixture fails closed if an expectation is wrong in either direction). - If the release also carries a fix for #116840: flip
H_view_propagation:<line>tomust_passfor that line (the view canary will start reporting an unexpected pass, which is the signal). - Re-measure scenario G' (
search_limitoverflow consequence) on the new build;search_limit_overflow_expectation_for/search_limit_overflow_wire_tupleinexpectations.shmust be extended for any new build line (theydieon unknown lines by design). - Update the compatibility wording in
README.md("Wiring ClickHouse toch-oauth-ldap"),docs/ch-oauth-ldap-operator-guide.md§1,integration/clickhouse/README.md, and issue Implement LDAP OAuth helper for ephemeral ClickHouse users and dynamic roles #19's "Compatibility target" —internal/securitytest/docs_contract_test.goenforces the ≥25.8 qualification phrase, so update the test's required-phrase list in the same PR. - Re-run
./integration/clickhouse/run-ha.shon the new build (the HA fixture uses the default ClickHouse image).
References
- Issue Implement LDAP OAuth helper for ephemeral ClickHouse users and dynamic roles #19 (implementation; "Compatibility target" section and the
<!-- ship-log -->comment, phase 3 handoff, for the root-cause analysis). - ADR ADR: Add LDAP↔OAuth bridge for ephemeral ClickHouse users and dynamic role mapping #16 Amendments (distributed-query criterion qualified).
- External roles are not transferred during LDAP authentication when querying a distributed table. ClickHouse/ClickHouse#78791, #79099, #116840, #70332.
Activity
fix(#30): record 26.8's peeled commit, not its annotated tag object
docs(#30): re-attest §11.6 and record both review findings in §11.7
docs(#30): correct stale head-equality prose and complete §4's 26.x c…
Merge pull request #54 from Altinity/feat/33-clickhouse-26x-tracked-l…
BorisTyshkevich commentedon Aug 31, 2026
Update: 26.3 and 26.8 are now tracked lines (#54, merged)
The core ask of this issue is unchanged and still blocked. 24.8 full support needs an Altinity Stable 24.8.x carrying #79099, and none exists: the newest 24.8 Altinity Stable image is still
24.8.14.10547.altinitystable(pushed 2026-07-23), the same ceiling this issue already records. Nothing below changes that.What did change is the matrix around it.
26.3and26.8are now full tracked lines inrun-all-builds.sh, with audited source provenance and a captured wire corpus each, and the two previously "not measured"search_limitcells are now measured.Compatibility matrix (updated 2026-08-31)
currentUser(), dynamiccurrentRoles(), role refresh, local-user precedenceDistributedover base tables keeps pushed external rolesDistributedover a normal VIEW keeps pushed external rolessearch_limitoverflow (257 roles vs 256)Tracked builds are now
24.8,25.8,26.3,26.8.25.3remains the only characterized-but-untracked line, runnable ad hoc viaPHASE3_CH_IMAGE.26.8is the upstreamclickhouse/clickhouse-server:26.8.1.2041image — no Altinity Stable 26.8 build exists yet (newest Altinity tags are26.3.16.10001.altinitystableand26.6.2.20001.altinityantalya). Tracking it upstream is what makes the current LTS line covered at all.Bug 2 (#116840) is still open upstream and reproduces on 26.8. The view canary now guards five lines, so a fix will still announce itself as an unexpected pass.
Three findings that affect this issue's work-items list
1. ClickHouse 26.8 maps
ACCESS_DENIEDto HTTP 403, where 24.8/25.8/26.3 map it to 500. Scenario H's negative control asserted 500 outright and failed on 26.8 even though propagation was correct — the body was exactly the expected shape (Code: 497 … Received from clickhouse-remote:9000 … (ACCESS_DENIED)). This is now a per-line recorded fact,remote_access_denied_http_status_for, fail-closed for an unrecorded prefix.Relevant here because the work items say to re-measure on a new build: any new 24.8.x image will need an entry in this table too, and if the status mapping was backported it could differ from 24.8.11's 500. Worth knowing that on 26.8
ACCESS_DENIEDandAUTHENTICATION_FAILEDnow share status 403, so the status alone no longer discriminates — the two body markers carry that weight.2. The recorded G' wire tuple said
time_limit=0on every line. It is 20. A pre-existing error since phase 5, insearch_limit_overflow_wire_tupleand operator guide §6. The reasoning was "this path has no<search_timeout>XML key, therefore 0"; with no per-call deadline requested, libldap sends the handle-wideLDAP_OPT_TIMELIMITdefault, which the wire-profile doc §5 documents as 20s and §8.2 has always recorded as the Search'stimeLimitoutright. Corrected from the committed capture corpus (BER02 01 14on all four lines) and live helper telemetry. No behavior changed — the field was recorded and logged but never asserted against telemetry, which is how two committed records contradicted each other unnoticed.3. Adding a line to
BUILDSis now actually possible. This is the one that most affects work item 1.BUILDSis the tracked-line authority for a four-way equality contract (BUILDS↔ wire doc §1/§2.1/§2.2 ↔ fixture directories ↔ everyprofile.json), which demands a captured wire-fixture directory per line — while the phase-3 freeze oncapture-ldap-wire.sh --mode generate, read literally, forbade ever producing one.BUILDSwas effectively ungrowable.The freeze is now narrowed to what it actually protected: no committed fixture is ever regenerated or promoted, with generation permitted for a line that has no committed fixture directory yet. That is enforced, not documented — a
--mode generatepreflight refuses to write into an output directory already holding a line it would capture, andtests/cases/wirecapture-fixture-freeze.shproves the refusal fires before any Docker mutation. Regenerating24.8/25.8during the 26.x work reproduced every committed.berbyte exactly.So the 26.x expansion is a worked example of precisely the procedure work item 1 prescribes. One trap it hit, worth flagging for whoever does the 24.8 work: check
.object.typewhen resolving a release tag.v26.8.1.2041-ltsis an annotated tag, so its ref reports a tag-object SHA, which got recorded where the peeled commit belonged. A tag SHA silently "works" for fetching file contents — the GitHub contents API peels refs — so blob SHAs come out correct either way and--mode verifycannot catch it (it compares the fixture against a value derived from the same table: consistency, not correctness).Work items — unchanged, but cheaper
Every item in the list above still stands as written for the 24.8 restoration. Two notes:
expectations.shitems now cover a third table,remote_access_denied_http_status_for, alongsidesearch_limit_overflow_expectation_for/search_limit_overflow_wire_tuple. All threedieon unknown lines by design.docs_contract_test.gostill enforces therequires ClickHouse ≥ 25.8qualification, which remains true.Full evidence for the 26.x certification — four-image acceptance and HA matrices, session probe, wire generate/verify, fuzz smoke, and the source-audit findings — is in
docs/clickhouse-ldap-wire-profile.md§11.7.