Skip to content

Commit 3395a40

Browse files
eric-wang-1990eric-wang-1990
committed
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
1 parent f342b5f commit 3395a40

1 file changed

Lines changed: 12 additions & 6 deletions

File tree

‎CONNECTION_PARAMETERS.md‎

Lines changed: 12 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -57,12 +57,12 @@ column.
5757

5858
| Option | Type | Thrift | Kernel | Default Value | Note |
5959
| ---------------------------------------------- | ------------------------------------------------------------ | :------: | :------: | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
60-
| `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). |
60+
| `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). |
6161
| `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. |
6262
| `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. |
6363
| `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. |
6464
| `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. |
65-
| `azureTenantId` / `useDatabricksOAuthInAzure` | `string` / `boolean` | ✅ | ❌ | — | **Thrift-only.** Kernel rejects Azure-direct (Entra) OAuth; workspace-OIDC discovery covers Azure workspaces without it. |
65+
| `azureTenantId` / `useDatabricksOAuthInAzure` | `string` / `boolean` | ✅ | ⚠️ | — | **Honored on both.** Kernel: on an Azure host, `databricks-oauth` **M2M** (secret present) with `useDatabricksOAuthInAzure` absent/`false` routes to Entra-direct service-principal M2M (native `AzureSpM2m` mode, creds ride `oauthClientId`/`oauthClientSecret`); `true` routes to workspace-OIDC M2M. `azureTenantId` is optional (kernel auto-discovers from the workspace `/aad/auth` redirect when omitted). **U2M** ignores the flag — the kernel's cloud-blind in-house flow works against Azure. One divergence: the kernel treats `.databricks.azure.us` as Azure in every arm, whereas Thrift's `useDatabricksOAuthInAzure`-true arm does not. (`lib/kernel/KernelAuth.ts` `buildKernelConnectionOptions`.) |
6666
| `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. |
6767
| `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`. |
6868

@@ -162,10 +162,9 @@ backend, so they are read regardless of `useKernel`. Defaults are sourced from
162162
`DBSQLClient.openSession`, but the conf key is likely dropped by the
163163
kernel's session-conf allowlist, so it has no effect on the kernel path.
164164
2. Auth types `custom`, `token-provider`, and `external-token`.
165-
3. `azureTenantId` / `useDatabricksOAuthInAzure` (Azure-direct OAuth).
166-
4. `persistence` (custom OAuth token store).
167-
5. SOCKS proxies.
168-
6. Per-statement `useCloudFetch`, `useLZ4Compression`,
165+
3. `persistence` (custom OAuth token store).
166+
4. SOCKS proxies.
167+
5. Per-statement `useCloudFetch`, `useLZ4Compression`,
169168
`stagingAllowedLocalPath`.
170169

171170
### Supported on Kernel, no Thrift public equivalent
@@ -187,5 +186,12 @@ backend, so they are read regardless of `useKernel`. Defaults are sourced from
187186
kernel path (kernel default kept).
188187
- **`configuration`** is allowlist-filtered on the kernel path but forwarded
189188
more freely on Thrift.
189+
- **Azure OAuth flow selection** differs in mechanism. Both backends honor
190+
`azureTenantId` / `useDatabricksOAuthInAzure`, but the kernel routes Entra-
191+
direct M2M through a dedicated native `AzureSpM2m` mode (auto-discovering the
192+
tenant when `azureTenantId` is omitted) and treats U2M as cloud-blind, while
193+
Thrift builds the Azure authorize URL in-process. The kernel also treats
194+
`.databricks.azure.us` as Azure in every arm; Thrift's
195+
`useDatabricksOAuthInAzure`-true arm does not.
190196

191197
> All kernel-path behavior reflects the **M0 stub** and is subject to change.

0 commit comments

Comments
 (0)