You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
docs: correct Azure Entra OAuth kernel support in connection param reference (#509)
* docs: correct Azure Entra OAuth kernel support in connection param reference
The connection-parameter reference (added in #457) predated #505
(feat(kernel): thread Azure Entra auth (U2M + SP M2M) through the kernel
path) and still claimed the kernel "rejects Azure-direct (Entra) OAuth".
That is now inverted: buildKernelConnectionOptions
(lib/kernel/KernelAuth.ts) has a dedicated AzureSpM2m mode for Entra-
direct service-principal M2M and consumes both azureTenantId and
useDatabricksOAuthInAzure.
- Authentication table: azureTenantId / useDatabricksOAuthInAzure kernel
cell ❌ → ⚠️, with an accurate flow-selection note.
- authType "supported on both" note now mentions Azure Entra SP M2M.
- Summary of gaps: drop Azure from "missing/ignored on Kernel" (renumber)
and record it under "Behavioral divergences to watch" instead.
Other cross-backend rows spot-checked against source and left as-is.
Co-authored-by: Isaac
Signed-off-by: eric-wang-1990 <e.wang@databricks.com>
* docs: mark Azure OAuth options fully supported (✅) on kernel
Per design intent: all U2M routes to the cloud-blind in-house OAuth U2M
flow (no Azure-specific U2M mode), so `.databricks.azure.us` (US-gov) is
always supported via that flow — that is intended completeness, not a
support gap. Both `azureTenantId` and `useDatabricksOAuthInAzure` are read
and forwarded on both backends, so the kernel cell is ✅ (not ⚠️).
Notes reframed: US-gov behavior now reads as the kernel being more
complete than Thrift (whose useDatabricksOAuthInAzure-true arm rejects
US-gov), and useDatabricksOAuthInAzure documented as selecting only the
M2M mechanism.
Co-authored-by: Isaac
Signed-off-by: eric-wang-1990 <e.wang@databricks.com>
* docs: add token, staticToken, and oauthClientSecret rows to auth table
The Authentication table documented `authType` and the OAuth modifier
options but never gave the credential-bearing fields their own rows —
`oauthClientSecret` in particular was only named inline as the flow
selector, despite its non-trivial kernel mapping (remapped to
`azureClientSecret` on the Entra-direct arm) and a blank-handling
divergence (rejected only on the Azure SP arm).
Adds three rows, each with the Thrift↔kernel mapping verified against
source:
- `token` (PAT): Thrift PlainHttpAuthentication vs kernel native `Pat`;
kernel rejects blank/reserved + OAuth-field pairing, Thrift does not.
- `staticToken`: Thrift StaticTokenProvider (federation opt-in) vs kernel
`Pat` bearer with federation always on.
- `oauthClientSecret` (M2M): flow selector on both; kernel native
`oauthClientSecret` or remapped `azureClientSecret`.
Co-authored-by: Isaac
Signed-off-by: eric-wang-1990 <e.wang@databricks.com>
* ai: apply changes for #509 (2 review threads)
Addresses:
- #3847919330 at CONNECTION_PARAMETERS.md:65
- #3848004541 at CONNECTION_PARAMETERS.md:68
Signed-off-by: peco-engineer-bot[bot] <peco-engineer-bot[bot]@users.noreply.github.com>
* ai: apply changes for #509 (1 review thread)
Addresses:
- #3848036730 at CONNECTION_PARAMETERS.md:68
Signed-off-by: peco-engineer-bot[bot] <peco-engineer-bot[bot]@users.noreply.github.com>
* ai: apply changes for #509 (1 review thread)
Addresses:
- #3848073178 at CONNECTION_PARAMETERS.md:60
Signed-off-by: peco-engineer-bot[bot] <peco-engineer-bot[bot]@users.noreply.github.com>
* docs: merge the two oauthClientId rows into one complete row
The table had two oauthClientId entries both describing the U2M/no-secret
case (one about defaulting, one about flow-selection), which read as two
different options, used inconsistent cell notation (✅ vs ✅ (U2M)), and
omitted M2M entirely. The flow-selection parity is also now covered by
the oauthClientSecret row.
Merged into a single oauthClientId row covering both flows: forwarded
verbatim when set; defaults to `databricks-sql-connector` when absent
(Thrift getClientId() for both flows; kernel `?? DEFAULT_OAUTH_CLIENT_ID`
on M2M, napi's own default on U2M); retains the "id + no secret ⇒ U2M,
no secret-required error" parity note.
Co-authored-by: Isaac
Signed-off-by: eric-wang-1990 <e.wang@databricks.com>
* docs: restore Azure kernel support to ✅ with a 1.0.0 version floor
The review-bot hedged the Azure row to ⚠️ because the pinned 0.2.0 native
binary might predate the AzureSpM2m surface. With a 1.0.0 kernel binary
(which carries kernel#282), the Entra-direct M2M arm is implemented at
runtime, so the row is ✅ again.
Replaces the "0.2.0 may predate / not observable / confirm your build"
hedges (Azure row + authType note) with a concrete, checkable version
floor: the Entra-direct M2M arm needs the native binary >= 1.0.0; U2M
works on any build. Per the ✅ legend (option is read and forwarded), the
connector honors these options on both backends; the binary floor is a
deployment note, not a support downgrade.
Co-authored-by: Isaac
Signed-off-by: eric-wang-1990 <e.wang@databricks.com>
* docs: phrase kernel 1.0.0 as forthcoming, not an existing version floor
1.0.0 is not published yet, so "carried by the native binary from 1.0.0
onward" overstated it as a shipping fact. Reword the Azure row and the
authType note: the connector forwards AzureSpM2m today, but its runtime
path needs the kernel Azure SP surface (kernel#282), which the currently
pinned 0.2.0 binary predates — it lands in a forthcoming release (planned
1.0.0, not yet published). U2M still needs no minimum. Row stays ✅ (the
options are read and forwarded per the legend).
Co-authored-by: Isaac
Signed-off-by: eric-wang-1990 <e.wang@databricks.com>
* ai: apply changes for #509 (1 review thread)
Addresses:
- #3848192767 at CONNECTION_PARAMETERS.md:67
Signed-off-by: peco-engineer-bot[bot] <peco-engineer-bot[bot]@users.noreply.github.com>
* docs: drop kernel binary/version hedging from the Azure rows
Per direction, treat the kernel Azure SP surface as included. Remove the
"0.2.0 predates it / planned 1.0.0, not yet published" caveats from both
the Azure row and the authType note; Azure is ✅ on both backends with a
clean flow-selection description.
Co-authored-by: Isaac
Signed-off-by: eric-wang-1990 <e.wang@databricks.com>
* ai: apply changes for #509 (1 review thread)
Addresses:
- #3848237239 at CONNECTION_PARAMETERS.md:66
Signed-off-by: peco-engineer-bot[bot] <peco-engineer-bot[bot]@users.noreply.github.com>
* docs: run prettier on CONNECTION_PARAMETERS.md
Reformat the Authentication table to match prettier's column padding so
the lint check passes. Whitespace-only, no content change.
Signed-off-by: eric-wang-1990 <e.wang@databricks.com>
---------
Signed-off-by: eric-wang-1990 <e.wang@databricks.com>
Signed-off-by: peco-engineer-bot[bot] <peco-engineer-bot[bot]@users.noreply.github.com>
Co-authored-by: peco-engineer-bot[bot] <peco-engineer-bot[bot]@users.noreply.github.com>
|`authType` — supported on both backends |`'access-token'`\|`'databricks-oauth'`\|`'static-token'`| ✅ | ✅ |`'access-token'`|`access-token` uses `token` (PAT) and is the default when `authType` is omitted. `static-token` uses `staticToken`; the kernel maps it to its native bearer-token mode. `databricks-oauth` covers M2M (`oauthClientId` + `oauthClientSecret`) and U2M (browser; no secret). |
61
-
|`authType` — Thrift-only |`'custom'`\|`'token-provider'`\|`'external-token'`| ✅ | ❌ | — |**Thrift-only.**`custom` uses `provider: IAuthentication`, `token-provider` uses `tokenProvider: ITokenProvider`, and `external-token` uses `getToken: TokenCallback`. The kernel throws `unsupported auth mode` for these modes. |
62
-
|`oauthScopes`|`Array<string>`| ❌ | ✅ | U2M `['sql','offline_access']`, M2M `['all-apis']`|**Thrift ignores `oauthScopes`** — `createAuthProvider` never threads it into `DatabricksOAuth`, so `authenticate()` always falls back to `defaultOAuthScopes` (`['sql','offline_access']`). Only the kernel honors a custom `oauthScopes`; its defaults happen to match Thrift's fallback. |
63
-
|`oauthClientId` (U2M) |`string`| ✅ | ✅ | napi default `client_id` when absent | The kernel adapter (`buildKernelConnectionOptions`) forwards a custom `oauthClientId` verbatim on the U2M arm; when it is absent the napi binding applies its own default `client_id`. Whether the native binding then honors or rejects a custom id is not observable from this repo — the TypeScript layer neither hardcodes an id nor rejects one. |
64
-
|`oauthClientId` + no secret |`string`| ✅ (U2M) | ✅ (U2M) | — |**Parity.** The kernel keys flow selection off `oauthClientSecret` presence exactly like Thrift, so `oauthClientId` + no secret routes to **U2M** (with the id forwarded) — it does **not** throw an M2M "secret required" error. |
|`persistence` (custom OAuth token store) |`OAuthPersistence`| ✅ | ❌ | — |**Thrift-only.** Kernel throws; it auto-persists U2M tokens to `~/.config/databricks-sql-kernel/oauth/` and does not cache M2M. |
67
-
|`enableTokenFederation` / `federationClientId`|`boolean` / `string`| ✅ | ⚠️ |`false` / — | On the kernel backend these options apply only to `static-token`. Federation is always enabled, so `enableTokenFederation` is ignored; an omitted or empty client ID selects account-wide WIF and a non-empty ID selects SP-wide WIF. Thrift honors the boolean and also supports these options for `token-provider` and `external-token`. |
58
+
| Option | Type | Thrift | Kernel | Default Value | Note |
|`authType` — supported on both backends |`'access-token'`\|`'databricks-oauth'`\|`'static-token'`| ✅ | ✅ |`'access-token'`|`access-token` uses `token` (PAT) and is the default when `authType` is omitted. `static-token` uses `staticToken`; the kernel maps it to its native bearer-token mode. `databricks-oauth` covers M2M (`oauthClientId` + `oauthClientSecret`), U2M (browser; no secret), and — on an Azure host — Entra-direct service-principal M2M (see the `azureTenantId` / `useDatabricksOAuthInAzure` row). |
61
+
|`authType` — Thrift-only |`'custom'`\|`'token-provider'`\|`'external-token'`| ✅ | ❌ | — |**Thrift-only.**`custom` uses `provider: IAuthentication`, `token-provider` uses `tokenProvider: ITokenProvider`, and `external-token` uses `getToken: TokenCallback`. The kernel throws `unsupported auth mode` for these modes. |
62
+
|`token` (PAT) |`string`| ✅ | ✅ | — (required for `access-token`) | Personal access token for `access-token` (the default mode). Thrift → `PlainHttpAuthentication` HTTP basic auth (username `token`). Kernel → native `Pat` authMode. Kernel rejects a blank/reserved token client-side (`AuthenticationError`) and rejects pairing it with OAuth fields; Thrift forwards it verbatim (a blank surfaces as a server-side 401). |
63
+
|`staticToken`|`string`| ✅ | ✅ | — (required for `static-token`) | Bearer/JWT for `static-token`. Thrift → `StaticTokenProvider.fromJWT` wrapped in `TokenProviderAuthenticator` (federation opt-in via `enableTokenFederation`). Kernel → native `Pat` bearer mode with federation always on (`federationClientId` ⇒ SP-wide WIF, omitted ⇒ account-wide). Kernel rejects a blank/reserved value; see the `enableTokenFederation` row. |
64
+
|`oauthScopes`|`Array<string>`| ❌ | ✅ | U2M `['sql','offline_access']`, M2M `['all-apis']`|**Thrift ignores `oauthScopes`** — `createAuthProvider` never threads it into `DatabricksOAuth`, so `authenticate()` always falls back to `defaultOAuthScopes` (`['sql','offline_access']`). Only the kernel honors a custom `oauthScopes`; its defaults happen to match Thrift's fallback. |
65
+
|`oauthClientId`|`string`| ✅ | ✅ |`databricks-sql-connector` when absent | OAuth client id, used on **both** U2M and M2M. Forwarded verbatim on both backends when set. When absent it defaults to `databricks-sql-connector` — Thrift via `getClientId()` for both flows; kernel via `oauthClientId ?? DEFAULT_OAUTH_CLIENT_ID` on M2M, and by letting the napi binding apply its own (identical) default on U2M. **Parity:**`oauthClientId` + no secret routes to **U2M** with the id forwarded (flow selection keys off `oauthClientSecret` presence — see that row), so it does **not** throw an M2M "secret required" error. |
66
+
|`oauthClientSecret` (M2M) |`string`| ✅ | ✅ | — | M2M client-credentials secret; its **presence** is the U2M-vs-M2M flow selector on both backends (`undefined` ⇒ U2M). Thrift → `DatabricksOAuth.clientSecret`. Kernel → native `oauthClientSecret` (workspace-OIDC M2M) or remapped to `azureClientSecret` (Entra-direct `AzureSpM2m`). A blank/reserved secret is forwarded verbatim and still selects M2M (Thrift parity) — except the Azure SP arm, which rejects it. |
67
+
|`azureTenantId` / `useDatabricksOAuthInAzure`|`string` / `boolean`| ✅ | ⚠️ | — |**Honored on both.** By design the kernel routes **all U2M** (no secret, any cloud) to its cloud-blind in-house OAuth U2M flow — there is no Azure-specific U2M mode, so `useDatabricksOAuthInAzure` is inert on U2M and every Azure workspace (including `.databricks.azure.us` US-gov) is always supported, on any kernel build. `useDatabricksOAuthInAzure` selects only the **M2M** mechanism on an Azure host: absent/`false` → Entra-direct service-principal M2M (native `AzureSpM2m` mode, creds ride `oauthClientId`/`oauthClientSecret`, `azureTenantId` optional — kernel auto-discovers from the workspace `/aad/auth` redirect when omitted); `true` → workspace-OIDC M2M. (`lib/kernel/KernelAuth.ts``buildKernelConnectionOptions`.) |
68
+
|`persistence` (custom OAuth token store) |`OAuthPersistence`| ✅ | ❌ | — |**Thrift-only.** Kernel throws; it auto-persists U2M tokens to `~/.config/databricks-sql-kernel/oauth/` and does not cache M2M. |
69
+
|`enableTokenFederation` / `federationClientId`|`boolean` / `string`| ✅ | ⚠️ |`false` / — | On the kernel backend these options apply only to `static-token`. Federation is always enabled, so `enableTokenFederation` is ignored; an omitted or empty client ID selects account-wide WIF and a non-empty ID selects SP-wide WIF. Thrift honors the boolean and also supports these options for `token-provider` and `external-token`. |
68
70
69
71
## HTTP client, proxy, retries
70
72
@@ -162,10 +164,9 @@ backend, so they are read regardless of `useKernel`. Defaults are sourced from
162
164
`DBSQLClient.openSession`, but the conf key is likely dropped by the
163
165
kernel's session-conf allowlist, so it has no effect on the kernel path.
164
166
2. Auth types `custom`, `token-provider`, and `external-token`.
![peco-engineer-bot[bot]](https://avatars.githubusercontent.com/in/3815206?v=4&size=40){kind=avatar}
0 commit comments