feat: OIDC device-flow authentication

CHANGELOG.rst

@@ -5,6 +5,80 @@ Changelog
 
 =========
 
+Unreleased
+----------
+
+Features
+~~~~~~~~
+
+OIDC Authentication (:mod:`questdb.auth`)
+************************************************
+
+New :mod:`questdb.auth` module to sign in interactively to OIDC-secured
+QuestDB Enterprise from Python — including from **remote** kernels
+(JupyterHub, SageMaker, Colab, VS Code-remote) that have no local browser.
+
+It runs the OAuth 2.0 Device Authorization Grant (RFC 8628) client-side: you
+authorize in any browser (laptop or phone), and the token is presented to
+QuestDB over the auth paths it already supports (HTTP ``Bearer`` / PG-wire
+``_sso``). No server change is required.
+
+.. code-block:: python
+
+    from questdb.auth import OidcDeviceAuth, sqlalchemy_engine
+
+    # Sign in once and get a valid, auto-refreshed token:
+    auth = OidcDeviceAuth.from_questdb("https://questdb.example.com:9000")
+    token = auth.token()      # use it with PG-wire, HTTP, or any client
+
+    # Or wire it into PG-wire as the _sso password:
+    engine = sqlalchemy_engine(auth, "https://questdb.example.com:9000")
+
+Highlights:
+
+* Auto-discovery of OIDC config from the QuestDB ``/settings`` endpoint, with a
+  fallback to the IdP ``.well-known`` document. Works with IdPs whose issuer is
+  on a different origin than its token / device-authorization endpoints (e.g.
+  Google: ``accounts.google.com`` issuer, ``oauth2.googleapis.com`` endpoints),
+  while still pinning endpoints advertised over an untrusted ``/settings``
+  channel to the issuer.
+* In-process token cache with silent refresh; in-memory only by default
+  (nothing written to disk unless you opt into a
+  :class:`~questdb.auth.TokenStore` — see the next entry).
+* Opt-in **token persistence** (:class:`~questdb.auth.FileTokenStore`, passed as
+  ``token_store=``) so a restarted process resumes from a saved refresh token
+  instead of prompting again. The default file store keeps one owner-only
+  (``0600``) plaintext file per identity under ``~/.questdb/oidc-tokens/``,
+  written atomically and coordinated across processes with a lock file; supply a
+  custom :class:`~questdb.auth.TokenStore` to back it with an OS keychain. The
+  on-disk format is a language-neutral contract shared with the Java client. The
+  per-request ``timeout`` is capped at 120s (matching the Java client) so a slow
+  refresh held under the file store's cross-process lock can't outlast its
+  staleness window; a larger value raises ``OidcConfigError`` at construction.
+* Convenience adapters (:func:`~questdb.auth.sqlalchemy_engine`,
+  :func:`~questdb.auth.psycopg_connect`) that wire the token into PG-wire as the
+  ``_sso`` password — ``sqlalchemy_engine`` re-supplies a fresh, auto-refreshed
+  token on every new pooled connection, ``psycopg_connect`` captures it at
+  connect time.
+* ``token()`` / ``headers()`` require no dependencies beyond the standard
+  library; ``sqlalchemy`` / ``psycopg`` / ``qrcode`` / ``IPython`` are imported
+  lazily.
+
+See the :ref:`OIDC authentication guide <oidc_auth>` for details.
+
+Breaking Changes
+~~~~~~~~~~~~~~~~~
+
+* The minimum supported Python is **3.10**. Python 3.8 (end-of-life 2024-10) and
+  3.9 (end-of-life 2025-10) are no longer supported, and ``pip`` will refuse to
+  install this release on them. This affects the whole ``questdb`` package, not
+  only the new :mod:`questdb.auth` module. The authoritative ``requires-python``
+  in ``pyproject.toml`` already declared ``>=3.10`` in 4.1.0 (so ``pip`` has
+  rejected 3.8 / 3.9 installs since then); this release also updates the stale
+  ``python_requires`` in ``setup.py``, which still read ``>=3.8``, to match —
+  removing the inconsistency for source builds that read ``setup.py`` directly.
+  Users still on 3.8 / 3.9 should pin to an earlier ``questdb`` release.
+
 4.1.0 (2025-11-28)
 ------------------
 

RELEASING.rst

@@ -59,10 +59,9 @@ From a MacOS ARM computer install UTM.
 * Install MacOS X 12.4 (Monterey). See https://docs.getutm.app/guest-support/macos/
 * Install Rust from https://rustup.rs/
 * Install Firefox
-* Install *all* OFFICIAL Python Releases from Python 3.8 onwards. Use the latest patch version for each minor release. 
+* Install *all* OFFICIAL Python Releases from Python 3.10 onwards. Use the latest patch version for each minor release.
     * https://www.python.org/downloads/macos/
     * Do NOT use Homebrew to install Python.
-    * Python 3.8.10 requires Rosetta, install it when prompted to do so. 
 
 * Optionally install VS Code
 

ci/cibuildwheel.yaml

@@ -107,7 +107,7 @@ stages:
               cmd /c "call `"$vsPath`" && set > env_vars.txt"
 
               Get-Content env_vars.txt | ForEach-Object {
-                if ($_ -match "^([^=]+?)=(.*)$" -and $matches[1] -notmatch '^(SYSTEM|AGENT|BUILD|RELEASE|VSTS|TASK|USE_|FAIL_|MSDEPLOY|AZP_75787|AZP_AGENT|AZP_ENABLE|AZURE_HTTP|COPYFILESOVERSSHV0|ENABLE_ISSUE_SOURCE_VALIDATION|MODIFY_NUMBER_OF_RETRIES_IN_ROBOCOPY|MSBUILDHELPERS_ENABLE_TELEMETRY|RETIRE_AZURERM_POWERSHELL_MODULE|ROSETTA2_WARNING|AZP_PS_ENABLE)') {
+                if ($_ -match "^([^=]+?)=(.*)$" -and $matches[1] -notmatch '^(SYSTEM|AGENT|BUILD|RELEASE|VSTS|TASK|USE_|FAIL_|MSDEPLOY|AZP_75787|AZP_AGENT|AZP_ENABLE|AZP_ENHANCED|AZURE_HTTP|COPYFILESOVERSSHV0|ENABLE_ISSUE_SOURCE_VALIDATION|MODIFY_NUMBER_OF_RETRIES_IN_ROBOCOPY|MSBUILDHELPERS_ENABLE_TELEMETRY|RETIRE_AZURERM_POWERSHELL_MODULE|ROSETTA2_WARNING|AZP_PS_ENABLE)') {
                   [System.Environment]::SetEnvironmentVariable($matches[1], $matches[2], "Process")
                   Write-Host "##vso[task.setvariable variable=$($matches[1])]$($matches[2])"
                 }
@@ -137,7 +137,7 @@ stages:
               cmd /c "call `"$vsPath`" && set > env_vars.txt"
 
               Get-Content env_vars.txt | ForEach-Object {
-                if ($_ -match "^([^=]+?)=(.*)$" -and $matches[1] -notmatch '^(SYSTEM|AGENT|BUILD|RELEASE|VSTS|TASK|USE_|FAIL_|MSDEPLOY|AZP_75787|AZP_AGENT|AZP_ENABLE|AZURE_HTTP|COPYFILESOVERSSHV0|ENABLE_ISSUE_SOURCE_VALIDATION|MODIFY_NUMBER_OF_RETRIES_IN_ROBOCOPY|MSBUILDHELPERS_ENABLE_TELEMETRY|RETIRE_AZURERM_POWERSHELL_MODULE|ROSETTA2_WARNING|AZP_PS_ENABLE)') {
+                if ($_ -match "^([^=]+?)=(.*)$" -and $matches[1] -notmatch '^(SYSTEM|AGENT|BUILD|RELEASE|VSTS|TASK|USE_|FAIL_|MSDEPLOY|AZP_75787|AZP_AGENT|AZP_ENABLE|AZP_ENHANCED|AZURE_HTTP|COPYFILESOVERSSHV0|ENABLE_ISSUE_SOURCE_VALIDATION|MODIFY_NUMBER_OF_RETRIES_IN_ROBOCOPY|MSBUILDHELPERS_ENABLE_TELEMETRY|RETIRE_AZURERM_POWERSHELL_MODULE|ROSETTA2_WARNING|AZP_PS_ENABLE)') {
                   [System.Environment]::SetEnvironmentVariable($matches[1], $matches[2], "Process")
                   Write-Host "##vso[task.setvariable variable=$($matches[1])]$($matches[2])"
                 }

ci/pip_install_deps.py

@@ -77,12 +77,18 @@ def install_pandas3_and_numpy():
 def should_use_pandas3(py_version=None):
     if py_version is None:
         py_version = sys.version_info[:2]
-    return py_version >= (3, 11)
+    # Pandas 3 ships no 32-bit wheels, so only take the pandas 3 / numpy 2
+    # path on 64-bit interpreters. On 32-bit (e.g. win32) the pandas 3 install
+    # would be silently skipped, fastparquet would then drag in a numpy-1-built
+    # pandas 2.0.3 alongside numpy 2, and importing pandas would crash.
+    is_64bits = sys.maxsize > 2 ** 32
+    return is_64bits and py_version >= (3, 11)
 
 
 def install_default_pandas_and_numpy():
-    # Pandas 3 currently requires Python 3.11+, so keep 3.10 wheel tests on
-    # the pandas 2 / numpy 1.x-compatible path unless explicitly overridden.
+    # Pandas 3 requires Python 3.11+ and ships only 64-bit wheels, so keep
+    # 3.10 and all 32-bit wheel tests on the pandas 2 / numpy 1.x-compatible
+    # path unless explicitly overridden.
     if should_use_pandas3():
         install_pandas3_and_numpy()
     else:
@@ -101,6 +107,13 @@ def main(args):
 
     try_pip_install('fastparquet>=2023.10.1')
     try_pip_install('pyarrow')
+    # For the questdb.auth OIDC tests: the behavioural TLS-rejection test
+    # (test_untrusted_server_certificate_is_rejected) generates a self-signed
+    # cert at runtime and skips without `cryptography`. Install it so the real
+    # handshake path is exercised in CI, not just the static-posture assertion.
+    # try_ (not required): on a platform with no wheel the test simply skips, as
+    # it already does locally.
+    try_pip_install('cryptography')
 
     on_linux_is_glibc = (
             (not platform.system() == 'Linux') or

ci/run_tests_pipeline.yaml

@@ -63,12 +63,24 @@ stages:
               git clone --depth 1 https://github.com/questdb/questdb.git
             displayName: git clone questdb master
             condition: eq(variables.vsQuestDbMaster, true)
-          - task: Maven@3
+          # Decide whether to build java-questdb-client from the bundled
+          # submodule (-P local-client, for a -SNAPSHOT client not on Maven
+          # Central) or resolve it from Maven Central. Sets $(CLIENT_PROFILE).
+          - template: templates/detect-local-client.yml
+            parameters:
+              qdbRepoPath: questdb
+              condition: eq(variables.vsQuestDbMaster, true)
+          # The Maven@3 task crashes parsing JDK 25 ("Cannot read properties of
+          # null (reading 'major')") since its JDK support tops out at 21, so
+          # invoke Maven directly on the preinstalled JDK 25 instead. Mirrors the
+          # task's defaults: POM questdb/pom.xml, goal "package".
+          - bash: |
+              set -eu
+              export JAVA_HOME="$(JAVA_HOME_25_X64)"
+              export PATH="$JAVA_HOME/bin:$PATH"
+              java -version
+              mvn -B -f questdb/pom.xml package -DskipTests -Pbuild-web-console $(CLIENT_PROFILE)
             displayName: "Compile QuestDB master"
-            inputs:
-              mavenPOMFile: "questdb/pom.xml"
-              jdkVersionOption: "1.17"
-              options: "-DskipTests -Pbuild-web-console"
             condition: eq(variables.vsQuestDbMaster, true)
           - script: python3 proj.py test 1
             displayName: "Test vs released"
@@ -77,8 +89,20 @@ stages:
           - script: python3 proj.py test 1
             displayName: "Test vs master"
             env:
-              JAVA_HOME: $(JAVA_HOME_17_X64)
+              JAVA_HOME: $(JAVA_HOME_25_X64)
               QDB_REPO_PATH: "./questdb"
+              # QuestDB master runs as the io.questdb JPMS module and needs these
+              # JDK 25 access flags (mirrors questdb.sh). The test fixture launches
+              # questdb.jar directly rather than via questdb.sh, so feed them to the
+              # java launcher through JDK_JAVA_OPTIONS.
+              JDK_JAVA_OPTIONS: >-
+                --sun-misc-unsafe-memory-access=allow
+                --enable-native-access=io.questdb
+                --add-opens=java.base/java.lang=io.questdb
+                --add-opens=java.base/java.lang.reflect=io.questdb
+                --add-opens=java.base/java.nio=io.questdb
+                --add-opens=java.base/java.time.zone=io.questdb
+                --add-exports=java.base/jdk.internal.vm=io.questdb
             condition: eq(variables.vsQuestDbMaster, true)
       - job: TestsAgainstVariousNumpyVersion1x
         pool:

ci/templates/detect-local-client.yml

@@ -0,0 +1,36 @@
+# Adapted from questdb/questdb's ci/templates/detect-local-client.yml.
+#
+# Decide how a cloned QuestDB checkout resolves its java-questdb-client
+# dependency: a -SNAPSHOT client version is not published to Maven Central, so
+# build it from the bundled java-questdb-client submodule via the `local-client`
+# profile; a released version is taken from Maven Central. Sets the
+# CLIENT_PROFILE pipeline variable (``-P local-client`` or empty) for the
+# following Maven build, and inits the submodule only when it is needed.
+#
+# Unlike the upstream template, QuestDB is cloned into a subdirectory here, so
+# the repo path is a parameter; ``condition`` lets the caller gate this to the
+# matrix leg that builds QuestDB master.
+parameters:
+  - name: qdbRepoPath
+    type: string
+    default: questdb
+  - name: condition
+    type: string
+    default: succeeded()
+
+steps:
+  - bash: |
+      set -eu
+      pom="${{ parameters.qdbRepoPath }}/core/pom.xml"
+      CLIENT_VERSION=$(sed -n 's/.*<questdb.client.version>\(.*\)<\/questdb.client.version>.*/\1/p' "$pom" | head -1)
+      echo "questdb.client.version=$CLIENT_VERSION"
+      if echo "$CLIENT_VERSION" | grep -q '\-SNAPSHOT$'; then
+        echo "SNAPSHOT client detected -> build it locally (local-client profile)"
+        git -C "${{ parameters.qdbRepoPath }}" submodule update --init java-questdb-client
+        echo "##vso[task.setvariable variable=CLIENT_PROFILE]-P local-client"
+      else
+        echo "Release client detected -> resolve from Maven Central"
+        echo "##vso[task.setvariable variable=CLIENT_PROFILE]"
+      fi
+    displayName: "Detect QuestDB local client profile"
+    condition: ${{ parameters.condition }}

docs/api.rst

@@ -67,3 +67,69 @@ questdb.ingress
    :members:
    :undoc-members:
    :show-inheritance:
+
+questdb.auth
+============
+
+See the :ref:`oidc_auth` guide for an overview.
+
+.. autoclass:: questdb.auth.OidcDeviceAuth
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autofunction:: questdb.auth.sqlalchemy_engine
+
+.. autofunction:: questdb.auth.psycopg_connect
+
+.. autoclass:: questdb.auth.OidcConfig
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: questdb.auth.TokenSet
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: questdb.auth.FileTokenStore
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: questdb.auth.TokenStore
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: questdb.auth.TokenStoreKey
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: questdb.auth.PersistedToken
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: questdb.auth.Renderer
+   :members:
+   :show-inheritance:
+
+.. autoexception:: questdb.auth.OidcError
+   :show-inheritance:
+
+.. autoexception:: questdb.auth.OidcConfigError
+   :show-inheritance:
+
+.. autoexception:: questdb.auth.OidcNetworkError
+   :show-inheritance:
+
+.. autoexception:: questdb.auth.OidcInteractionRequired
+   :show-inheritance:
+
+.. autoexception:: questdb.auth.OidcDeviceFlowError
+   :show-inheritance:
+
+.. autoexception:: questdb.auth.OidcTimeoutError
+   :show-inheritance: