glasstiger · Oct 23, 2026 · Oct 23, 2026 · Oct 23, 2026 · Oct 23, 2026 · Oct 23, 2026
diff --git a/documentation/changelog.mdx b/documentation/changelog.mdx
@@ -16,6 +16,15 @@ This page tracks significant updates to the QuestDB documentation.
 
 ### New
 
+- [Token providers](/docs/connect/clients/java/#token-providers) - The Java client 1.3.11 requests and renews bearer tokens itself, with `token_provider=azure` for Microsoft Entra ID or a `RefreshingTokenProvider` for other identity providers. Covers the `questdb-client-azure` artifact, credential selection, failure classification, and how senders, queries, and orphan drainers handle token failures
+- [Connection health](/docs/connect/clients/java/#connection-health) - The Java client reports whether each sender and query client reaches the server, since when it has not, and its last failure
+- [Managed identities and service principals](/docs/security/oidc/#managed-identities-and-service-principals) - Authenticate Azure services to QuestDB Enterprise with Entra ID app-only tokens: app roles, v2.0 tokens, claim lists, group mappings, and the Java client
+- [User and group claims](/docs/security/oidc/#user-and-group-claims) - Fallback claim lists for `acl.oidc.sub.claim` and `acl.oidc.groups.claim` in QuestDB Enterprise 4.1.0, how QuestDB picks a claim, and the startup checks
+- [Token validation](/docs/security/oidc/#token-validation) - What QuestDB checks in a token, and how it finds the expected issuer
+- [Sessions and token expiry](/docs/security/oidc/#sessions-and-token-expiry) - HTTP sessions end when QuestDB rejects their token, and how the Web Console renews its tokens and handles failed renewals
+- [Troubleshooting OIDC](/docs/security/oidc/#troubleshooting) - Log lines of rejected logins and tokens, and the errors of the Web Console login page
+- [HTTP sessions in the REST API](/docs/connect/compatibility/rest-api/#http-sessions) - Open and close a session with the `qdb_session` cookie, and how QuestDB 10.1.0 and QuestDB Enterprise 4.1.0 end a session whose credential they reject
+- [HTTP sessions in RBAC](/docs/security/rbac/#http-sessions) - Sessions of QuestDB Enterprise 4.1.0 end with their credential, how to end the Web Console logins of a user, and what replicas keep
 - [Merge-append partitions](/docs/concepts/merge-append-partitions/) - Reduce copying for backdated ingestion, monitor partition pieces and dead rows, and safely disable the layout before downgrading or converting to non-WAL
 - [Persisted metrics](/docs/operations/logging-metrics/#persisted-metrics) - New section on the `sys.metrics` table, where QuestDB keeps a history of its own metrics, with example queries
 - [Databento connector](/docs/connect/connectors/databento/) - New page for the QuestDB Enterprise Databento connector, which streams Live feeds and runs Historical backfills into QuestDB. Covers installation, TOML configuration, table mappings, storage policies, candles from a materialized view, a session VWAP live view, live dashboards in a Web Console notebook or Grafana, checkpointed recovery, and Prometheus metrics
@@ -25,6 +34,11 @@ This page tracks significant updates to the QuestDB documentation.
 
 ### Reference
 
+- [`acl.oidc.issuer`](/docs/configuration/oidc/#acloidcissuer) and [`acl.oidc.issuer.validation.enabled`](/docs/configuration/oidc/#acloidcissuervalidationenabled) - New settings for the expected issuer of a token
+- [`acl.oidc.sub.claim`](/docs/configuration/oidc/#acloidcsubclaim) and [`acl.oidc.groups.claim`](/docs/configuration/oidc/#acloidcgroupsclaim) - Documented claim lists and their startup validation, and corrected that `acl.oidc.groups.claim` has no default and is required
+- [`acl.oidc.cache.ttl`](/docs/configuration/oidc/#acloidccachettl) - Documented that `0` disables the cache, and how long an HTTP session reuses a password check
+- [`http.session.timeout`](/docs/configuration/http-server/#httpsessiontimeout) - Documented how long an idle HTTP session stays valid, and that a value without a unit suffix is read as microseconds
+- [Token providers](/docs/connect/clients/connect-string/#token-providers) - The `token_provider` and `azure_*` connect-string keys of the Java client
 - Added [merge-append and partition compaction settings](/docs/configuration/cairo-engine/#partition-compaction) and the `deadRows`, `lastWriteTimestamp` and `pieceCount` columns in [`SHOW PARTITIONS`](/docs/query/sql/show/#show-partitions) and [`table_partitions()`](/docs/query/functions/meta/#table_partitions)
 - Added [`metrics.enabled`](/docs/configuration/logging-metrics/#metricsenabled) and the [`metrics.persist.*`](/docs/configuration/logging-metrics/#persisted-metrics) settings for `sys.metrics`
 - Added the dedicated live view refresh worker pool settings [`live.view.refresh.worker.count`](/docs/configuration/live-views/#liveviewrefreshworkercount), `.affinity`, `.haltOnError`, `.nap.threshold`, `.sleep.threshold`, `.sleep.timeout`, and `.yield.threshold`, plus [`cairo.live.view.checkpoint.purge.interval`](/docs/configuration/live-views/#cairoliveviewcheckpointpurgeinterval). Live views run on their own refresh pool, not the materialized view pool as previously documented
@@ -37,6 +51,10 @@ This page tracks significant updates to the QuestDB documentation.
 
 ### Updated
 
+- [Upgrade QuestDB](/docs/operations/upgrade/#authentication-changes-in-410) - Authentication changes to check before upgrading to QuestDB Enterprise 4.1.0
+- [QWP client behaviour](/docs/connect/wire-protocols/qwp-client-behavior/#authentication-failures-and-token-providers) - Authentication failures by phase, and the retry with a new token after a `401`. The QWP ingress and egress, client failover, and connect string pages now describe how the Java client retries authentication failures
+- [Java client](/docs/connect/clients/java/#ingestion-errors) - Corrected the error categories and policies, that the `QuestDB` builder accepts an error handler, and the `AUTH_FAILED` connection event
+- [Microsoft Entra ID](/docs/security/oidc/#microsoft-entraid) - The configuration takes the principal from `preferred_username` instead of the display name
 - [Partition splitting](/docs/concepts/partitions/#partition-splitting-and-squashing) - Documented WAL split retention and background merging of idle splits and reclamation of Parquet dead space, including when merge-append is disabled
 - [HORIZON JOIN](/docs/query/sql/horizon-join/#queries-without-aggregate-functions) - Breaking change in QuestDB 10.1.0: a HORIZON JOIN without aggregate functions now returns one row per left-hand row and offset instead of grouping by the selected columns. Documented the row order, the designated timestamp of the result, how `SELECT DISTINCT` or an explicit `GROUP BY` restores the previous result, the [upgrade steps](/docs/query/sql/horizon-join/#upgrading-to-questdb-1010) for queries, outer aggregation, views, `INSERT INTO ... SELECT`, and `CREATE TABLE AS SELECT`, and the new execution plan names
 - [HORIZON JOIN](/docs/query/sql/horizon-join/#filtering-right-hand-tables) - Breaking change in QuestDB 10.1.0: documented right-hand filters, written in the `ON` clause, as a `(table WHERE ...)` subquery, or as a `SELECT` of the table's columns, which apply before the ASOF match. Earlier versions ignored `ON` predicates other than the join keys. Added a grammar for the right-hand side, including CTEs, and documented the `ORDER BY` limitation

diff --git a/documentation/configuration/http-server.md b/documentation/configuration/http-server.md
@@ -97,6 +97,22 @@ occurs. Changing the default value is strongly discouraged.
 Password for HTTP Basic Authentication in QuestDB Open Source. QuestDB
 Enterprise supports more advanced authentication via RBAC.
 
+### http.session.timeout
+
+- **Default**: `30m`
+- **Reloadable**: no
+
+How long an HTTP session stays valid without a request. A client opens a
+session, identified by the `qdb_session` cookie, by sending `session=true`, as
+the Web Console does at login. Every request that QuestDB authorizes restarts
+the timer, so a session in use does not expire. QuestDB Open Source opens
+sessions only when `http.user` and `http.password` are set. See
+[HTTP sessions](/docs/connect/compatibility/rest-api/#http-sessions).
+
+The value is a duration with a unit suffix, such as `90s`, `30m`, or `1h`. A
+number without a suffix is read as microseconds, so `1800000` is 1.8 seconds,
+not 30 minutes.
+
 ### http.user
 
 - **Default**: N/A

diff --git a/documentation/configuration/oidc.md b/documentation/configuration/oidc.md
@@ -26,6 +26,11 @@ For detailed information about OIDC, see the
 OAuth2 audience as set on the tokens issued by the OIDC Provider. Defaults
 to the client ID if not set.
 
+With `acl.oidc.groups.encoded.in.token=true`, QuestDB accepts a token only
+when its `aud` claim contains this value. The ID tokens that the Web Console
+sends carry the client ID, so keep the default when users sign in to the Web
+Console. See [Token validation](/docs/security/oidc/#token-validation).
+
 ### acl.oidc.client.id
 
 - **Default**: none
@@ -65,6 +70,53 @@ configuration URL is set.
 
 OIDC provider HTTP request timeout in milliseconds.
 
+### acl.oidc.issuer
+
+- **Default**: none
+- **Reloadable**: no
+
+The issuer that the `iss` claim of a token must match when
+`acl.oidc.groups.encoded.in.token` is `true`, in QuestDB Enterprise 4.1.0 and
+later. When not set, QuestDB uses the `issuer` field of the discovery document
+that it downloads from
+[`acl.oidc.configuration.url`](#acloidcconfigurationurl). When set, it takes
+precedence over the discovery document. The comparison is exact and
+case-sensitive, and includes the path and any trailing slash.
+
+Set it when QuestDB has no discovery document, because it uses
+[`acl.oidc.host`](#acloidchost) and the endpoint settings, or when the
+discovery document names a template instead of an issuer, such as
+`https://login.microsoftonline.com/{tenantid}/v2.0` for the multi-tenant
+endpoints of Microsoft Entra ID. Set the issuer of your tenant, never a
+template or a wildcard. With issuer validation enabled, QuestDB refuses to
+start in token mode without an expected issuer:
+
+```text
+required to set acl.oidc.issuer or provide an issuer in the OIDC discovery document when acl.oidc.groups.encoded.in.token and acl.oidc.issuer.validation.enabled are true
+```
+
+See [Token validation](/docs/security/oidc/#token-validation).
+
+### acl.oidc.issuer.validation.enabled
+
+- **Default**: `true`
+- **Reloadable**: no
+
+Whether QuestDB checks the `iss` claim of a token when
+`acl.oidc.groups.encoded.in.token` is `true`, in QuestDB Enterprise 4.1.0 and
+later. With `false`, QuestDB neither requires nor compares the `iss` claim,
+even when [`acl.oidc.issuer`](#acloidcissuer) is set, and logs an advisory at
+startup. It still checks the signature, the audience, the expiry, and the
+`sub` claim of a token.
+
+Disable it only for a provider whose tokens carry no `iss` claim. Without the
+check, QuestDB accepts the token of any issuer or tenant that the provider
+signs with a key that QuestDB trusts, for the expected audience.
+
+Accepts `true` or `false`, in any letter case. Any other value, an empty one
+included, stops QuestDB from starting, even when OIDC is disabled:
+`invalid configuration value [key=acl.oidc.issuer.validation.enabled, value=...]`.
+
 ### acl.oidc.port
 
 - **Default**: `443`
@@ -196,37 +248,77 @@ which it connects.
 
 ## User and group claims
 
+QuestDB reads the principal and the group memberships of an external user
+from the user information: the response of the User Info endpoint, or, when
+`acl.oidc.groups.encoded.in.token` is `true`, the payload of the token. For
+how QuestDB picks the claims, see
+[User and group claims](/docs/security/oidc/#user-and-group-claims) in the
+OIDC guide.
+
 ### acl.oidc.cache.ttl
 
 - **Default**: `30000`
 - **Reloadable**: no
 
-User info cache entry TTL in milliseconds. QuestDB caches user info responses
-for each valid access token. This setting controls how often the access token
-is validated and user info refreshed.
+How long QuestDB caches the result of checking a token, in milliseconds: the
+User Info response, or, when `acl.oidc.groups.encoded.in.token` is `true`, the
+result of validating the token. QuestDB checks the token again once its cache
+entry expires, so in User Info mode, this setting also controls how soon a
+change in the Identity Provider, such as a disabled user, takes effect. `0`
+disables the cache.
+
+In QuestDB Enterprise 4.1.0 and later, the same interval applies to HTTP
+sessions, even with OIDC disabled. A session reuses the check of a password
+that QuestDB verifies itself, the password of a database user or of the
+built-in admin, until this interval has passed since the session last checked
+it. A session never reuses the check of a REST token or an OIDC credential.
+See [HTTP sessions](/docs/security/rbac/#http-sessions).
 
 ### acl.oidc.groups.claim
 
-- **Default**: `groups`
+- **Default**: none
 - **Reloadable**: no
 
-The name of the custom claim in the user information that contains the
-group memberships of the user.
+The claim in the user information that contains the group memberships of the
+user, as an array of group names or as a single name. Required when OIDC is
+enabled.
+
+In QuestDB Enterprise 4.1.0 and later, accepts a comma-separated list of claim
+names in priority order, such as `roles,groups`. QuestDB takes the groups from
+the first claim on the list that holds at least one group name, and does not
+combine the groups of several claims. QuestDB refuses to start when the list
+is empty, names a claim twice, or names a claim that
+[`acl.oidc.sub.claim`](#acloidcsubclaim) also lists. See
+[User and group claims](/docs/security/oidc/#user-and-group-claims).
 
 ### acl.oidc.groups.encoded.in.token
 
 - **Default**: `false`
 - **Reloadable**: no
 
-When `true`, QuestDB looks for group memberships in the ID token instead of
-calling the User Info endpoint. Set to `true` if the OIDC Provider encodes
-group memberships directly into the token.
+When `true`, QuestDB reads the principal and the group memberships from a
+JWT, such as the ID token, instead of calling the User Info endpoint, and
+validates the token itself. Set to `true` if the OIDC Provider encodes group
+memberships directly into the token, as Microsoft Entra ID does. In QuestDB
+Enterprise 4.1.0 and later, the validation includes the issuer of the token.
+See [Token validation](/docs/security/oidc/#token-validation).
 
 ### acl.oidc.sub.claim
 
 - **Default**: `sub`
 - **Reloadable**: no
 
-The name of the claim in the user information that contains the user's name.
-Could be a username, full name, or email. Displayed in the Web Console and
-logged for audit purposes.
+The claim in the user information that contains the principal of the user,
+such as a username, an email address, or an object ID. `current_user()`
+returns the principal, the Web Console displays it, and QuestDB logs it for
+audit purposes. Pick a claim whose value the Identity Provider never gives to
+anyone else: users who share a principal share their permissions. Avoid
+display names, such as the `name` claim.
+
+In QuestDB Enterprise 4.1.0 and later, accepts a comma-separated list of claim
+names in priority order, such as `preferred_username,oid`. QuestDB takes the
+principal from the first claim on the list that holds a non-empty value.
+QuestDB refuses to start when the list is empty, names a claim twice, or names
+a claim that [`acl.oidc.groups.claim`](#acloidcgroupsclaim) also lists. An
+empty value does not fall back to the default `sub`. See
+[User and group claims](/docs/security/oidc/#user-and-group-claims).