feat: use oauth2 crate for OAuth with configurable client auth (#4181)

Stacked on #4173 (`jack/restore-oidc-flows`, base branch mirrored to
this repo so the diff shows only this change); context from review:
https://github.com/lancedb/lancedb/pull/4173#issuecomment-5674048100.
Rebase to `main` once #4173 and #4179 merge.

## What moved to the `oauth2` crate (5.0, no default features)

- Authorization URL generation and CSRF state (`authorize_url`,
`CsrfToken`)
- PKCE S256 challenge/verifier generation and code exchange
- Client-credentials, authorization-code, refresh-token, and device-code
grant request construction
- Device authorization request and the device token polling loop
(`authorization_pending`, `slow_down` +5s, expiry deadline, denial,
network backoff capped at 10s)
- Standard success/error response parsing (`RequestTokenError`)
- Token-endpoint client authentication and standards-compliant parameter
encoding (RFC 6749 2.3.1 Basic encoding)

LanceDB keeps ownership of OIDC discovery (compared `openidconnect`: no
measurable win for our 3-field metadata + strict validation, at real
dependency cost), HTTPS-or-loopback endpoint enforcement, the loopback
callback server, browser/stderr prompts, token caching and refresh
orchestration, and the dedicated hardened Azure IMDS source, which is
unchanged.

## Client authentication methods

New `ClientAuthMethod` enum (`none` | `client_secret_basic` |
`client_secret_post`), exposed in Rust, Python, and Node. Unset resolves
to `client_secret_basic` when a secret is present (RFC 6749 2.3.1
recommendation and the normal Okta confidential-app default, so a
default Okta app works without weakening its configuration) and to
`none` for public clients (PKCE/device). Explicit `none` with a secret,
or basic/post without one, is rejected. The method applies to client
credentials, code exchange, refresh, and device requests. Deliberate
behavior change: confidential clients previously always sent the secret
in the POST body; they now default to Basic (Keycloak accepts both).

No `audience`/`resource` parameters were added: the supported target is
an Okta custom authorization server with the API audience configured
server-side, so client-provided audience parameters are unnecessary;
`add_extra_param` support exists if a concrete provider contract ever
needs them.

## Device polling behavior changes (deliberate, tested)

- The first token poll now happens immediately rather than after one
interval (RFC 8628 allows both).
- Transient failures (HTTP 429, 5xx, `temporarily_unavailable`, network
errors) now retry with exponential backoff capped at 10s instead of
retrying at the fixed interval; polling never spins faster than once per
second even if a server reports a zero interval.

## Security and compatibility

- Issuer and discovered endpoints (and device verification URIs) still
require HTTPS except explicit loopback HTTP, enforced before any crate
URL type is built
- Token HTTP client keeps the hardened redirect policy that refuses
insecure redirect targets; regression test added
- Errors never embed raw response bodies (avoids leaking tokens through
parse failures); all credential types stay redacted in Debug
- Transient conditions (429/5xx/`temporarily_unavailable`) remain
retryable in device polling and hard errors elsewhere; refresh keeps
rotation and reauthentication semantics
- Existing public APIs stay source-compatible except the added
`OAuthConfig.client_auth_method` field

## Tests

Rust: client-auth methods across code
exchange/refresh/client-credentials/device (none/basic/post),
auth-method resolution and validation, transient device retries,
denial/expiry, redirect rejection, malformed-response leak check, PKCE
URL assertions, redaction. Python and Node: enum values, conversion,
unknown-method errors, config defaults.

Manual Okta validation recipe (no automated Okta credentials): create a
custom authorization server with an API audience, one confidential web
app (Basic) for authorization-code, one native app (PKCE, no secret),
one native device app; point `issuer_url` at the custom server, set
`client_auth_method` only for the POST-required case; verify token
acquisition, refresh after expiry, and `x-lancedb-credential-type: oidc`
against a LanceDB deployment. Never commit tenant URLs or secrets.

Co-authored-by: Xuanwo <github@xuanwo.io>

python/python/lancedb/remote/__init__.py

@@ -9,7 +9,13 @@ from typing import List, Optional
 from lancedb import __version__
 
 from .header import HeaderProvider
-from .oauth import OAuthConfig, OAuthFlowType, OAuthSession, TokenCacheOptions
+from .oauth import (
+    ClientAuthMethod,
+    OAuthConfig,
+    OAuthFlowType,
+    OAuthSession,
+    TokenCacheOptions,
+)
 
 # The API reference renders this module with a single mkdocstrings directive,
 # which only picks up names listed here. New public names must be added to this
@@ -22,6 +28,7 @@ __all__ = [
     "HeaderProvider",
     "OAuthConfig",
     "OAuthFlowType",
+    "ClientAuthMethod",
     "OAuthSession",
     "TokenCacheOptions",
 ]

python/python/lancedb/remote/oauth.py

@@ -22,6 +22,29 @@ class OAuthFlowType(str, Enum):
     """Azure Managed Identity via IMDS."""
 
 
+class ClientAuthMethod(str, Enum):
+    """How the client authenticates to the OAuth token endpoint.
+
+    The method applies to every OAuth request that carries client
+    authentication: client-credentials, authorization-code exchange,
+    refresh-token, and device-authorization requests. The Azure managed
+    identity flow ignores this option.
+    """
+
+    NONE = "none"
+    """No client authentication, for public clients using PKCE or the device
+    flow. Cannot be combined with ``client_secret``."""
+
+    CLIENT_SECRET_BASIC = "client_secret_basic"
+    """HTTP Basic authentication. This is the RFC 6749 recommended method and
+    the normal default for confidential clients, including default Okta
+    applications. Requires ``client_secret``."""
+
+    CLIENT_SECRET_POST = "client_secret_post"
+    """Credentials in the request body, for providers configured to require
+    it. Requires ``client_secret``."""
+
+
 @dataclass
 class TokenCacheOptions:
     """Options for the persistent OAuth token cache.
@@ -77,6 +100,13 @@ class OAuthConfig:
         Authentication flow to use. Default: CLIENT_CREDENTIALS.
     client_secret : Optional[str]
         Client secret (required for CLIENT_CREDENTIALS).
+    client_auth_method : Optional[ClientAuthMethod]
+        How the client authenticates to the token endpoint (default: auto).
+        With a ``client_secret`` the default is
+        ``ClientAuthMethod.CLIENT_SECRET_BASIC``, which matches the RFC 6749
+        recommendation and the default configuration of Okta confidential
+        applications; without a secret the client is public and no client
+        authentication is sent.
     redirect_uri : Optional[str]
         Loopback redirect URI for AUTHORIZATION_CODE. The default is
         ``http://127.0.0.1:{callback_port}/callback``.
@@ -140,8 +170,9 @@ class OAuthConfig:
     ...     flow=OAuthFlowType.AUTHORIZATION_CODE,
     ... )
 
-    Device Authorization with a persistent cache, so later processes reuse
-    the session without a new device prompt:
+    Device Authorization, with a persistent cache so later processes reuse
+    the session without a new device prompt. The verification URL and user
+    code are written to standard error before polling begins:
 
     >>> config = OAuthConfig(
     ...     issuer_url="https://login.microsoftonline.com/{tenant}/v2.0",
@@ -157,6 +188,7 @@ class OAuthConfig:
     scopes: List[str]
     flow: OAuthFlowType = OAuthFlowType.CLIENT_CREDENTIALS
     client_secret: Optional[str] = field(default=None, repr=False)
+    client_auth_method: Optional[ClientAuthMethod] = None
     redirect_uri: Optional[str] = None
     callback_port: Optional[int] = None
     use_pkce: bool = True

python/src/oauth.rs

@@ -9,7 +9,7 @@ use pyo3::{FromPyObject, PyResult, Python, pyclass, pymethods};
 use crate::error::PythonErrorExt;
 use crate::runtime::future_into_py;
 use lancedb::error::Error;
-use lancedb::remote::oauth::{AuthorizationCodeOptions, OAuthConfig, OAuthFlow};
+use lancedb::remote::oauth::{AuthorizationCodeOptions, ClientAuthMethod, OAuthConfig, OAuthFlow};
 use lancedb::remote::{OAuthSession, SessionLogout, SessionStatus, TokenCacheOptions};
 
 /// Python-side persistent token cache options, extracted via FromPyObject.
@@ -42,6 +42,7 @@ pub struct PyOAuthConfig {
     pub audience: Option<String>,
     pub flow: String,
     pub client_secret: Option<String>,
+    pub client_auth_method: Option<String>,
     pub redirect_uri: Option<String>,
     pub callback_port: Option<u16>,
     pub use_pkce: bool,
@@ -77,10 +78,23 @@ impl TryFrom<PyOAuthConfig> for OAuthConfig {
             }
         };
 
+        let client_auth_method = match py.client_auth_method.as_deref() {
+            Some("none") => Some(ClientAuthMethod::None),
+            Some("client_secret_basic") => Some(ClientAuthMethod::ClientSecretBasic),
+            Some("client_secret_post") => Some(ClientAuthMethod::ClientSecretPost),
+            None => None,
+            Some(other) => {
+                return Err(Error::InvalidInput {
+                    message: format!("Unknown OAuth client auth method: {other}"),
+                });
+            }
+        };
+
         Ok(Self {
             issuer_url: py.issuer_url,
             client_id: py.client_id,
             client_secret: py.client_secret,
+            client_auth_method,
             scopes: py.scopes,
             resource: py.resource,
             audience: py.audience,
@@ -255,6 +269,7 @@ mod tests {
             scopes: vec!["scope".to_string()],
             flow: "device_code".to_string(),
             client_secret: None,
+            client_auth_method: None,
             redirect_uri: None,
             callback_port: None,
             use_pkce: true,
@@ -315,6 +330,38 @@ mod tests {
         assert!(matches!(converted.flow, OAuthFlow::DeviceCode));
     }
 
+    #[test]
+    fn test_client_auth_method_conversion() {
+        for (value, expected) in [
+            ("none", ClientAuthMethod::None),
+            ("client_secret_basic", ClientAuthMethod::ClientSecretBasic),
+            ("client_secret_post", ClientAuthMethod::ClientSecretPost),
+        ] {
+            let config = PyOAuthConfig {
+                client_auth_method: Some(value.to_string()),
+                ..base_config()
+            };
+
+            let converted = OAuthConfig::try_from(config).unwrap();
+            assert_eq!(converted.client_auth_method, Some(expected));
+        }
+    }
+
+    #[test]
+    fn test_unknown_client_auth_method_returns_invalid_input() {
+        let config = PyOAuthConfig {
+            client_auth_method: Some("typo".to_string()),
+            ..base_config()
+        };
+
+        let err = OAuthConfig::try_from(config).unwrap_err();
+        assert!(matches!(
+            err,
+            Error::InvalidInput { message }
+                if message == "Unknown OAuth client auth method: typo"
+        ));
+    }
+
     #[test]
     fn test_token_cache_conversion() {
         let config = PyOAuthConfig {

python/tests/test_oauth.py

@@ -63,6 +63,34 @@ def test_device_code_flow_value():
     assert oauth.OAuthFlowType.DEVICE_CODE.value == "device_code"
 
 
+def test_client_auth_method_values():
+    oauth = _load_oauth_module()
+
+    assert oauth.ClientAuthMethod.NONE.value == "none"
+    assert oauth.ClientAuthMethod.CLIENT_SECRET_BASIC.value == "client_secret_basic"
+    assert oauth.ClientAuthMethod.CLIENT_SECRET_POST.value == "client_secret_post"
+
+
+def test_client_auth_method_defaults_to_none():
+    oauth = _load_oauth_module()
+
+    config = oauth.OAuthConfig(
+        issuer_url="https://issuer.example.com",
+        client_id="client-id",
+        scopes=["openid"],
+        client_auth_method=oauth.ClientAuthMethod.CLIENT_SECRET_POST,
+    )
+
+    assert config.client_auth_method is oauth.ClientAuthMethod.CLIENT_SECRET_POST
+
+    default_config = oauth.OAuthConfig(
+        issuer_url="https://issuer.example.com",
+        client_id="client-id",
+        scopes=["openid"],
+    )
+    assert default_config.client_auth_method is None
+
+
 def test_token_cache_options_default_to_memory_only():
     oauth = _load_oauth_module()