8000 ClickHouse version compatibility: track upstream external-role fixes (#79099, #116840) and restore full 24.8 Altinity Stable support · Issue #30 · Altinity/altinity-oauth-helper · GitHub
[go: up one dir, main page]

Skip to content

ClickHouse version compatibility: track upstream external-role fixes (#79099, #116840) and restore full 24.8 Altinity Stable support #30

Open

Description

@BorisTyshkevich

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

  1. 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_queries mechanism) so the roles are pushed and the remote logs external_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+.
  2. Pushed external roles are lost when the remote query reads through a normal VIEW (ContextData copy constructor omits external_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.8 from expected_fail to must_pass in integration/clickhouse/lib/expectations.sh only after ./integration/clickhouse/run-all-builds.sh shows 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> to must_pass for that line (the view canary will start reporting an unexpected pass, which is the signal).
  • Re-measure scenario G' (search_limit overflow consequence) on the new build; search_limit_overflow_expectation_for / search_limit_overflow_wire_tuple in expectations.sh must be extended for any new build line (they die on unknown lines by design).
  • Update the compatibility wording in README.md ("Wiring ClickHouse to ch-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.go enforces the ≥25.8 qualification phrase, so update the test's required-phrase list in the same PR.
  • Re-run ./integration/clickhouse/run-ha.sh on the new build (the HA fixture uses the default ClickHouse image).

References

Activity

  1. added 4 commits that reference this issue on Aug 31, 2026
  2. BorisTyshkevich commented on Aug 31, 2026

    @BorisTyshkevich
    CollaboratorAuthor

    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.3 and 26.8 are now full tracked lines in run-all-builds.sh, with audited source provenance and a captured wire corpus each, and the two previously "not measured" search_limit cells are now measured.

    Compatibility matrix (updated 2026-08-31)

    Capability 24.8 25.3 25.8 26.3 26.8
    Ephemeral-user auth, currentUser(), dynamic currentRoles(), role refresh, local-user precedence ✅ ✅ ✅ ✅ ✅
    Distributed over base tables keeps pushed external roles ❌ (bug 1) ❌ (bug 1) ✅ ✅ ✅
    Distributed over a normal VIEW keeps pushed external roles ❌ (bug 2) ❌ (bug 2) ❌ (bug 2) ❌ (bug 2) ❌ (bug 2)
    search_limit overflow (257 roles vs 256) auth fails closed (403), measured not measured auth fails closed (403), measured auth fails closed (403), measured auth fails closed (403), measured

    Tracked builds are now 24.8, 25.8, 26.3, 26.8. 25.3 remains the only characterized-but-untracked line, runnable ad hoc via PHASE3_CH_IMAGE.

    26.8 is the upstream clickhouse/clickhouse-server:26.8.1.2041 image — no Altinity Stable 26.8 build exists yet (newest Altinity tags are 26.3.16.10001.altinitystable and 26.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_DENIED to 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_DENIED and AUTHENTICATION_FAILED now 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=0 on every line. It is 20. A pre-existing error since phase 5, in search_limit_overflow_wire_tuple and 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-wide LDAP_OPT_TIMELIMIT default, which the wire-profile doc §5 documents as 20s and §8.2 has always recorded as the Search's timeLimit outright. Corrected from the committed capture corpus (BER 02 01 14 on 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 BUILDS is now actually possible. This is the one that most affects work item 1. BUILDS is the tracked-line authority for a four-way equality contract (BUILDS ↔ wire doc §1/§2.1/§2.2 ↔ fixture directories ↔ every profile.json), which demands a captured wire-fixture directory per line — while the phase-3 freeze on capture-ldap-wire.sh --mode generate, read literally, forbade ever producing one. BUILDS was 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 generate preflight refuses to write into an output directory already holding a line it would capture, and tests/cases/wirecapture-fixture-freeze.sh proves the refusal fires before any Docker mutation. Regenerating 24.8/25.8 during the 26.x work reproduced every committed .ber byte 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.type when resolving a release tag. v26.8.1.2041-lts is 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 verify cannot 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:

    • The expectations.sh items now cover a third table, remote_access_denied_http_status_for, alongside search_limit_overflow_expectation_for / search_limit_overflow_wire_tuple. All three die on unknown lines by design.
    • The docs item's required-phrase list is unaffected: docs_contract_test.go still enforces the requires ClickHouse ≥ 25.8 qualification, 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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions

      0