docs: rework the OIDC documentation and split the OIDC and RBAC guides into sections

[glasstiger]

What

The OIDC documentation, in five parts: the Device Authorization Flow, which
was not documented at all and now has its own page; the settings endpoint a
client discovers the provider from; the configuration reference, which was
missing five options and described four others wrongly; a pass over the pages
elsewhere in the docs that contradicted any of it; and a restructure that
breaks the two 700-1600 line security pages into browsable sections.

Important

This is blocked on the client releases. See
Release coordination at the bottom. The device-flow
APIs documented here are correct, but none of them has shipped, and the Rust
snippet does not build against the published crate.

Device Authorization Flow

A new page, OIDC Device Authorization Flow,
for command-line applications, containers, and remote notebook kernels, where no
browser redirect can come back to the client. It has its own sidebar entry; the
guide keeps a short section at the old #device-authorization-flow anchor so
existing links still resolve.

• QuestDB does not run the flow. The client talks to the Identity Provider
  directly and then presents the resulting bearer token, which the sequence
  diagram walks through end to end. The client is responsible for the polling
  interval, slow_down, and the device code's expiry.
• What has to be configured first: the device grant enabled on a public
  client registered for the application, a device authorization endpoint QuestDB
  can publish (from the configuration document, or from
  acl.oidc.device.authorization.endpoint), and offline_access in
  acl.oidc.scope where the provider requires it before issuing a refresh
  token.
• Worked examples for Java, Python, Rust, C++, and C. Each discovers the
  client ID, scope, endpoints, and token mode from /settings, signs in, then
  writes a row through the rotating token. They live in
  documentation/partials/ and are imported by both this page and the client
  page for that language, so the two copies cannot drift.
• The discovery URL must be https. The clients reject plaintext rather
  than warn. Rust, C, C++ and Python make an exception for loopback; Java does
  not. The per-language opt-out is documented.

Four sections cover what the examples do not show, because the client pages were
already pointing at them:

• The sign-in prompt. The five clients differ in ways that decide whether a
  headless job works at all: Java prints to System.out and performs no
  terminal check, so redirecting output hides the code; Rust, C and C++ refuse
  without a TTY; Python defers to the IPython kernel. Custom-prompt and
  force-interactive setters are named for each.
• Explicit configuration and endpoint pinning. What each setting is for and
  where the setters live, including that Java splits them between
  DiscoveryOptions and builder().
• Token persistence. The per-language constructor and attachment, the
  default directory and its override, and the 0600/0700 permissions, so the
  at-rest tradeoff the page asks the reader to accept can be judged.
• Interaction-required errors. Java has no distinct type, and Rust flattens
  the kind to ErrorCode::AuthError, reachable only through err.oidc_error().

Each client page gained an OIDC device flow (Enterprise) section
(Java,
Python,
Rust,
C & C++). On the Python
and C/C++ pages this replaces the "Unsupported auth paths" table: OIDC token
acquisition and mid-session rotation are no longer unsupported there, so the
table is now a short list of what genuinely remains - mutual TLS, and a fixed
token= that does not rotate.

The guide's Jupyter and CLI sections point at the device flow first. ROPC is
demoted to the fallback for tooling that cannot run the flow, such as psql.

Settings endpoint

The settings endpoint
is what a client reads, without authentication, to discover the authorization,
token, and device authorization endpoints, the client ID and scope, and whether
PKCE and state are required. The new section documents the response key by
key, which keys are omitted when unset, and two traps: acl.oidc.enabled has to
be read before the rest, because the acl.oidc.* keys are published from the
defaults even when OIDC is off, and the path follows the Web Console context
path rather than being fixed at /settings.

Which token to send
is a top-level section rather than a subsection of the settings endpoint, since
nine pages link to it as the canonical answer for the Authorization header. It
documents what acl.oidc.groups.encoded.in.token means for a client, and now
carries the security consequence that previously lived only in the
configuration reference: with the setting enabled QuestDB validates the token
itself and never asks the provider about it, so a revoked token keeps working
until its exp passes.

http.context.settings
was rewritten to match: it serves clients rather than only the Web Console, it
takes a comma-separated list, and setting it adds paths instead of moving the
service. The Go,
.NET,
Node.js, and
QWP ingress
pages link to it, and the first two also link the device flow, since neither
client runs one and the settings endpoint alone does not tell them how to get a
token.

Configuration reference

Compared the acl.oidc.* keys defined in EntPropertyKey.java against
the OIDC configuration page. The
server defines 29 options, the page documented 24 names, one of which the server
does not recognise. All 29 are now documented.

Added

Option	Default	Notes
acl.oidc.state.required	false	Requires the state parameter in the Authorization Code Flow. Published to clients through the settings endpoint, same as the PKCE flag.
acl.oidc.device.authorization.endpoint	none	No default, and QuestDB never calls it. It is resolved and published for clients which run the Device Authorization Flow themselves.
acl.oidc.public.keys.expiry	120000	JWKS cache expiry in milliseconds. Also accepts a duration, unlike the other two millisecond settings.
acl.oidc.response.buffer.size	1M	Buffer for HTTP responses from the OIDC Provider.
acl.oidc.string.pool.capacity	128	String pool used to parse the provider's JSON responses.

Corrected

• acl.oidc.pkce.enabled does not exist. The property is
  acl.oidc.pkce.required. There is no alias, so anyone who copied the
  documented name got silently ignored config, with PKCE staying on.
• acl.oidc.groups.claim has no default. The page claimed groups, but the
  default is null and the option is mandatory when OIDC is enabled - the
  server refuses to start without it.
• acl.oidc.host and acl.oidc.configuration.url are mutually exclusive.
  Setting both fails server startup, which the page did not mention.
• The public keys are downloaded whether or not they are used. The store is
  built whenever OIDC is enabled and loads the keys from its constructor. Only
  the use of the keys is conditional.
• A missing groups claim fails authentication. The guide said the user is
  authenticated but ends up with no permissions. verifyTokenSlow returns false
  when either the groups or the sub claim is missing or empty, in both flows, so
  the login is rejected: 401 over HTTP, an authentication error on PGWire,
  with the reason only in the server log.
• Two components read the token when
  acl.oidc.groups.encoded.in.token=true. The signature validator requires
  sub, aud and exp and checks the signature, audience and expiry against
  them; it never looks at the group memberships. QuestDB then reads the
  principal and the groups out of the same payload through
  acl.oidc.sub.claim and acl.oidc.groups.claim, exactly as in the user info
  flow. So acl.oidc.groups.claim may name any claim the token carries,
  roles for example, and acl.oidc.sub.claim may name any claim too as long
  as the token still carries sub for the validator. The claim's value is
  normally an array; a bare string is accepted where a provider sends a lone
  group.

Scoped to what the server actually does

• acl.oidc.audience is only checked when the groups are encoded in the token.
  It is also the one discovery key the clients look for that the server never
  publishes, so a provider that requires an audience needs it set on the client.
• The mandatory openid in acl.oidc.scope is enforced by the provider, not at
  startup.
• acl.oidc.ropc.flow.enabled makes QuestDB itself exchange HTTP basic and
  PGWire credentials for a token at the provider.
• When QuestDB validates a token itself it checks the signature, the audience,
  the expiry and the presence of the claims - but not nbf or iss. It never
  asks the provider, so revocation does not take effect until exp passes.
• acl.basic.auth.realm.enabled cannot be combined with acl.oidc.enabled;
  setting both fails startup. Noted on the
  IAM page.
• acl.oidc.enabled=false does not take the settings out of play entirely:
  acl.oidc.configuration.url is still parsed and its scheme still validated.

Restructured

• A new Minimum configuration section: the four settings a working setup
  needs, and the full list of consistency rules the server enforces at startup.
  It also records that the OIDC settings are validated even with acl.enabled
  off, so a bad OIDC config still stops the server from starting.
• A new Caching and buffers section. acl.oidc.cache.ttl moved there out of
  "User and group claims", next to the other caching and buffer settings, with
  what setting it to 0 does in each flow.

Cross-page reconciliation

Pages elsewhere in the docs contradicted the above, or predated OIDC entirely:

• connect-string
  is where the client pages send readers for the credential grammar and listed
  only username, password and token. It now records that device-flow
  credentials are not connect-string keys, and that a static token= does not
  rotate.
• RBAC counted three
  authentication methods and the
  REST API
  counted two; both omitted OIDC. The REST API page also now distinguishes an
  OIDC bearer token from the REST API token it documents below, since the two
  share the Authorization: Bearer header.
• Failover told
  operators to send "an OIDC access token", which under the
  groups.encoded.in.token=true that the Entra ID walkthrough sets is rejected
  with a 401.
• The Client Id rule had three answers across the guide. It is stated once, in
  the device flow's setup steps.

Guide corrections

• Noted in the
  authorization code request step
  that some Identity Providers require the state parameter.
• Added the missing QuestDB server.conf block to the
  PingFederate walkthrough,
  which relied on defaults for two settings that have none.
• Renamed both "QuestDB configuration" headings to name their provider, pinning
  the Entra ID anchor so existing links keep working.
• The ROPC example discovered the provider's token endpoint over plaintext
  http and then posted the user's SSO password to whatever URL came back. Both
  non-interactive examples now use https, and were ported off the legacy ILP
  Sender to questdb.connect over wss, matching the Python client page.
• The Implicit flow is marked deprecated: it cannot use PKCE, which the settings
  endpoint advertises as required by default.

Page restructure

The OIDC and RBAC guides had each grown into a single page too long to navigate
or link into precisely - oidc.mdx at 1600 lines, rbac.md at 717. Both are
now directories, one page per topic, with the overview at the section root and
a sidebar category listing the rest.

Was	Now
security/oidc.mdx	security/oidc/ - overview, how sign-in works, client discovery and tokens, client integration patterns, mapping groups and permissions, PingFederate, Entra ID
security/rbac.md	security/rbac/ - overview, users and groups, authentication and endpoints, granting permissions, permissions reference, common scenarios

Old anchors keep working. Both section roots end with a "where each section
moved" table that holds the old anchor ids and points at the page each section
went to, so external links to #which-token-to-send,
#questdb-configuration-for-pingfederate, #endpoint-permissions and the rest
still land somewhere useful. Every inbound link inside the docs was repointed at
the new canonical anchor rather than left on the redirect.

Two permission statements were corrected while passing through the RBAC pages:
REBASE WAL
and SWITCH COLD STORAGE ROLE
need the SYSTEM ADMIN permission, which is grantable. Both pages described it
as unspecified "database administrator (system admin) privileges", and the cold
storage page went further and called the statements "not grantable through RBAC
permissions". Separately, all_permissions() lists every permission the
database supports, not the ones currently applied.

Verification

Every default was read off EntPropServerConfiguration.java:284-320, not
inferred, and the value formats off the getters each one uses. The
startup-failure claims were each checked against the validation in
EntPropServerConfiguration and OidcEndpoint. The token-validation table
describes the next Enterprise release, which validates exp; the earlier
"an expired token is still accepted" wording matched the shipped validator and
no longer holds. nbf and iss remain unchecked. The settings endpoint example
matches SettingsEndpointTest, key for key and in order, including
acl.basic.auth.realm.enabled.

The client API surfaces were checked against the client sources, and the
examples compile: Java with javac against the built client, Rust with
cargo check, and both C variants and the C++ example with -fsyntax-only -Wall -Wextra. Every type, method, kwarg and C symbol named in these pages
exists and is spelled correctly.

yarn build passes with no broken links or anchors.

Release coordination

The APIs are right; none of them has shipped. This is the one thing that
should gate the merge:

	Merged to main	Released
Java	yes	no - pom.xml is 1.3.10-SNAPSHOT, newest tag 1.3.7
Rust	no	no - crates.io questdb-rs 7.0.0 has no oidc feature
C / C++	no	no - include/questdb/oidc.h absent from main
Python	no	no - PyPI is 5.0.0; CHANGELOG.rst says 5.0.1 (unreleased)
Enterprise server	yes	no - absent from tags 4.0.0 and 3.3.4

No client page states a minimum version, and the Rust snippet's
questdb-rs = { version = "7", features = ["oidc"] } is a copy-paste build
failure against the published crate today. It is not only the OIDC surface:
connect_with_token_provider, questdb_db_connect_ex and token_provider.rs
are all unmerged, so the rotating-provider pattern these sections recommend is
feature-branch work for Rust, C and C++.

Either hold this until the clients release, or add an explicit minimum-version
note to each of the five sections. The Cargo.toml needs fixing either way.

🤖 Generated with Claude Code

https://claude.ai/code/session_0111nSmXn2CmqkYMGobjvxgY

[github-actions]

🚀 Build success!

Latest successful preview: https://preview-522--questdb-documentation.netlify.app/docs/

Commit SHA: ef66a91

📦 Build generates a preview & updates the link on each commit.

[glasstiger]

Token validation: superseded by questdb-enterprise#1188

Review flagged that acl.oidc.groups.encoded.in.token's validation table claims
exp is checked, while jwt.rs set validate_exp = false. That is fixed on the
server side by questdb-enterprise#1188, which sets
set_required_spec_claims(&["sub", "aud", "exp"]) and validate_exp = true.

So the table on this branch is right for the release that carries #1188, and
wrong for every release before it. The same holds for acl.oidc.cache.ttl's
"that local check tests the token's expiry".

Two things still need a pass here, because #1188 changes more than exp.

1. The literal groups claim requirement is going away. #1188 drops
groups: Vec<String> from the native Claims struct, so
acl.oidc.groups.claim now selects the claim. Its upgrade note:

acl.oidc.groups.claim now selects the claim that carries group membership in
an ID token. Earlier releases required a claim literally named groups and
rejected the token before the setting was consulted, so a provider emitting
roles, or any other name, could not be used together with
acl.oidc.groups.encoded.in.token=true.

That contradicts two passages this PR adds to configuration/oidc.md:

• "the JWT must carry claims named sub and groups literally, and groups
  must be an array of strings" - the array requirement also goes, since #1188
  tolerates a lone bare string, "some providers send a lone group that way"
• "So set acl.oidc.groups.claim=groups, since that is the only name the
  validator accepts for the group memberships" - no longer true

2. The revocation caution is still not right after #1188. It says the token
"keeps working until its exp passes, and acl.oidc.cache.ttl does not shorten
that". Per #1188's upgrade note the cache extends acceptance past exp:

A token is also still accepted for a short window past exp: 60 seconds of
clock-skew leeway, plus up to acl.oidc.cache.ttl (30 seconds by default)
while an earlier validation of the same token remains cached.

It also notes the WebSocket connection is not torn down when its token expires,
which is worth a line on the QWP or device-flow page.

Since the docs now describe post-#1188 behaviour, both PRs should land together,
or these pages should say which version the behaviour applies from.