feat(kernel): thread Azure Entra auth (U2M + SP M2M) through the kernel path

On useKernel=true + authType='databricks-oauth', route Azure Entra auth to the
kernel instead of rejecting it. Mirrors the Thrift OAuthManager.getManager:
useDatabricksOAuthInAzure selects the flavour on an Azure host.

- useDatabricksOAuthInAzure: true -> in-house workspace-federated flow, which
  the kernel runs natively: no secret -> OAuthU2m (browser), secret -> OAuthM2m
  (workspace-OIDC client-credentials). Works against Azure workspaces.
- absent/false on an Azure host -> Entra-direct: with a secret -> the kernel's
  Azure SP M2M (AzureSpM2m; Entra SP creds ride oauthClientId/oauthClientSecret,
  azureTenantId optional/auto-discovered); without a secret -> Entra-direct
  browser U2M, which the kernel does not implement -> rejected with a pointer to
  useDatabricksOAuthInAzure: true or the Thrift backend.
- Non-Azure host: the flags are inert (in-house is the only flow).

Adds an AzureSpM2m variant to the native-options union + an isAzureHost helper.
Replaces the previous blanket Azure-OAuth rejection. Verified end-to-end
against a live Azure workspace (U2M browser flow + SP M2M data token) with a
native module built from databricks-sql-kernel#280.

Co-authored-by: Isaac
Signed-off-by: eric-wang-1990 <e.wang@databricks.com>

Author: eric-wang-1990

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Release History
 
+## Unreleased
+
+- Kernel backend (`useKernel: true`): **Azure Entra (Azure AD) auth is now threaded through the kernel path.** On `authType: 'databricks-oauth'`, `useDatabricksOAuthInAzure` selects the flavour on an Azure host (mirroring the Thrift `OAuthManager.getManager`): `true` → the in-house workspace-federated flow, which the kernel runs natively (browser U2M → `OAuthU2m`, client-credentials M2M → `OAuthM2m`, both via workspace-OIDC discovery, which works against Azure workspaces); absent/`false` on an Azure host → the Entra-direct flow — with a secret it maps to the kernel's Azure service-principal M2M (`AzureSpM2m`, the Entra SP creds ride `oauthClientId`/`oauthClientSecret`, `azureTenantId` optional and auto-discovered when omitted), and without a secret (Entra-direct browser U2M, which the kernel does not implement) it is rejected with a pointer to `useDatabricksOAuthInAzure: true` or the Thrift backend. On a non-Azure host these flags are inert. Requires a `databricks-sql-kernel` native module that exposes the Azure SP surface ([databricks-sql-kernel#280](https://github.com/databricks/databricks-sql-kernel/pull/280)). (PECOBLR-4141 / PECOBLR-4120)
+
 ## 2.0.0
 
 **Breaking changes — completes the security cleanup that 1.17.0 could not do without breaking changes.**

lib/kernel/KernelAuth.ts

@@ -239,6 +239,14 @@ export type KernelNativeConnectionOptions = KernelSessionDefaults &
         oauthScopes?: Array<string>;
         oauthClientId?: string;
       }
+    | {
+        hostName: string;
+        httpPath: string;
+        authMode: 'AzureSpM2m';
+        azureClientId: string;
+        azureClientSecret: string;
+        azureTenantId?: string;
+      }
   );
 
 function prependSlash(str: string): string {
@@ -248,6 +256,28 @@ function prependSlash(str: string): string {
   return str;
 }
 
+/**
+ * Azure Databricks host suffixes — the superset the Thrift driver's
+ * `OAuthManager.getManager` recognises (`.azuredatabricks.net`,
+ * `.databricks.azure.us`, `.databricks.azure.cn`). Used to decide whether an
+ * OAuth connection is on Azure and therefore subject to the in-house-vs-
+ * Entra-direct split.
+ */
+const AZURE_HOST_SUFFIXES = ['.azuredatabricks.net', '.databricks.azure.us', '.databricks.azure.cn'];
+
+/**
+ * True when `host` is an Azure Databricks workspace host. Normalises the input
+ * the same way `getManager` does (lowercase, strip scheme + any path) so a
+ * caller passing a bare host or a full URL is treated identically.
+ */
+function isAzureHost(host: string): boolean {
+  const normalized = host
+    .toLowerCase()
+    .replace(/^https?:\/\//, '')
+    .split('/')[0];
+  return AZURE_HOST_SUFFIXES.some((suffix) => normalized.endsWith(suffix));
+}
+
 /**
  * Reject inputs that pass `typeof === 'string' && length > 0` but are
  * structurally useless as credentials: whitespace-only strings, and the
@@ -467,11 +497,24 @@ export function buildKernelHttpOptions(options: ConnectionOptions): KernelHttpOp
  *          on the U2M arm. Thrift U2M honours a custom `clientId`.
  *     Both are documented limitations of the M0 kernel OAuth surface, not bugs.
  *
+ * Azure (Entra) on the OAuth path — mirrors Thrift `OAuthManager.getManager`,
+ * with `useDatabricksOAuthInAzure` selecting the flavour on an Azure host:
+ *   - `useDatabricksOAuthInAzure: true` → **in-house** (workspace-federated).
+ *     The kernel runs it natively via workspace-OIDC discovery — U2M browser
+ *     flow (`OAuthU2m`) and M2M client-credentials (`OAuthM2m`) — so it is NOT
+ *     rejected. `azureTenantId` is ignored here (the in-house flow does not use
+ *     it), matching Thrift.
+ *   - absent/`false` on an Azure host → **Entra-direct**:
+ *       - with a secret → Azure service-principal M2M (`AzureSpM2m`); the Entra
+ *         SP creds ride `oauthClientId`/`oauthClientSecret`, `azureTenantId`
+ *         optional (kernel auto-discovers).
+ *       - without a secret → Entra-direct browser U2M, which the kernel does
+ *         not implement → **rejected** with a pointer to
+ *         `useDatabricksOAuthInAzure: true` or the Thrift backend.
+ *   - On a non-Azure host these flags are inert (the in-house flow is the only
+ *     one), matching Thrift.
+ *
  * Out of scope on the OAuth paths (rejected with a clear error):
- *   - `azureTenantId` / `useDatabricksOAuthInAzure` → Microsoft Entra
- *     direct flow. The kernel uses workspace-OIDC discovery (which works
- *     against Azure workspaces too — they serve `/oidc/.well-known/...`)
- *     and does not implement the Entra-direct scope-rewrite path.
  *   - `persistence` on M2M → M2M tokens are not cached (re-issuing is
  *     cheap; no refresh token).
  *   - `persistence` on U2M → custom token store is a parity gap;
@@ -485,7 +528,7 @@ export function buildKernelHttpOptions(options: ConnectionOptions): KernelHttpOp
  *
  * Throws:
  *   - `AuthenticationError` for missing/blank required credentials.
- *   - `HiveDriverError` for unsupported auth modes / Azure-direct /
+ *   - `HiveDriverError` for unsupported auth modes / Entra-direct U2M /
  *     custom persistence / ambiguous combinations.
  */
 /**
@@ -632,12 +675,45 @@ export function buildKernelConnectionOptions(options: ConnectionOptions): Kernel
       );
     }
 
-    if (oauth.azureTenantId !== undefined || oauth.useDatabricksOAuthInAzure === true) {
-      throw new HiveDriverError(
-        'kernel backend: Azure-direct OAuth (azureTenantId / useDatabricksOAuthInAzure) ' +
-          'is not supported. The workspace-OIDC discovery path handles Azure workspaces ' +
-          'today without these options.',
-      );
+    // Azure routing. `useDatabricksOAuthInAzure` selects the in-house
+    // (workspace-federated) flow vs the Entra-direct flow, mirroring the Thrift
+    // driver's `OAuthManager.getManager`: on an Azure host, `true` → in-house,
+    // absent/false → Entra-direct. The kernel runs the in-house flow natively
+    // via workspace-OIDC discovery (U2M browser flow AND M2M client-credentials
+    // — Azure workspaces serve `/oidc/.well-known/...`), but has NO Entra-direct
+    // browser U2M; Entra-direct SP M2M maps to the kernel's dedicated
+    // azure-sp-m2m. On a non-Azure host these flags are inert (the in-house flow
+    // is the only one), matching Thrift.
+    const entraDirect = isAzureHost(options.host) && oauth.useDatabricksOAuthInAzure !== true;
+    if (entraDirect) {
+      if (oauth.oauthClientSecret === undefined) {
+        // Entra-direct browser U2M — the kernel has no direct-Entra U2M flow.
+        throw new HiveDriverError(
+          'kernel backend: Azure AD (Entra-direct) OAuth U2M is not supported. Set ' +
+            '`useDatabricksOAuthInAzure: true` to use the in-house workspace-federated browser ' +
+            'flow (which the kernel runs against Azure Databricks workspaces), or use the Thrift ' +
+            'backend (default) for the Entra-direct flow.',
+        );
+      }
+      // Entra-direct service-principal M2M → the kernel's azure-sp-m2m. The Entra
+      // SP credentials ride the generic `oauthClientId` / `oauthClientSecret`
+      // (Thrift convention); forward them as `azureClientId` / `azureClientSecret`.
+      // `azureTenantId` is optional — the kernel auto-discovers it from the
+      // workspace `/aad/auth` redirect when omitted.
+      const azureClientId = oauth.oauthClientId;
+      if (azureClientId === undefined) {
+        throw new HiveDriverError(
+          'kernel backend: Azure service-principal M2M requires `oauthClientId` (the Entra ' +
+            'app-registration client id) alongside `oauthClientSecret`.',
+        );
+      }
+      const azure = {
+        ...base,
+        authMode: 'AzureSpM2m' as const,
+        azureClientId,
+        azureClientSecret: oauth.oauthClientSecret,
+      };
+      return oauth.azureTenantId !== undefined ? { ...azure, azureTenantId: oauth.azureTenantId } : azure;
     }
 
     // Flow selector + client-id resolution mirror the Thrift driver EXACTLY

tests/unit/kernel/auth-m2m.test.ts

@@ -127,23 +127,56 @@ describe('KernelAuth + KernelBackend — OAuth M2M auth flow', () => {
       expect((native as { oauthClientId?: string }).oauthClientId).to.equal('client-uuid');
     });
 
-    it('rejects azureTenantId with a clear Entra-direct-out-of-scope error', () => {
+    it('routes Azure host + secret (Entra-direct default) to azure-sp-m2m, forwarding the tenant', () => {
+      // On an Azure host with no `useDatabricksOAuthInAzure`, the default is the
+      // Entra-direct flow — for M2M that is the kernel's azure-sp-m2m. The Entra
+      // SP creds ride oauthClientId/oauthClientSecret; azureTenantId is forwarded
+      // (optional — the kernel auto-discovers it when omitted).
       const opts: ConnectionOptions = {
         host: 'adb-12345.0.azuredatabricks.net',
         path: '/sql/1.0/warehouses/abc',
         authType: 'databricks-oauth',
-        oauthClientId: 'client-uuid',
-        oauthClientSecret: 'dose-fake-secret',
+        oauthClientId: 'entra-app-id',
+        oauthClientSecret: 'entra-secret',
         azureTenantId: 'tenant-uuid',
       };
 
-      expect(() => buildKernelConnectionOptions(opts)).to.throw(
-        HiveDriverError,
-        /Azure-direct OAuth.*is not supported/,
-      );
+      const native = buildKernelConnectionOptions(opts);
+      expectNativeConnectionOptions(native, {
+        hostName: 'adb-12345.0.azuredatabricks.net',
+        httpPath: '/sql/1.0/warehouses/abc',
+        intervalsAsString: true,
+        authMode: 'AzureSpM2m',
+        azureClientId: 'entra-app-id',
+        azureClientSecret: 'entra-secret',
+        azureTenantId: 'tenant-uuid',
+      });
+    });
+
+    it('routes Azure host + secret without a tenant to azure-sp-m2m (kernel auto-discovers)', () => {
+      const opts: ConnectionOptions = {
+        host: 'adb-12345.0.azuredatabricks.net',
+        path: '/sql/1.0/warehouses/abc',
+        authType: 'databricks-oauth',
+        oauthClientId: 'entra-app-id',
+        oauthClientSecret: 'entra-secret',
+      };
+
+      const native = buildKernelConnectionOptions(opts);
+      expectNativeConnectionOptions(native, {
+        hostName: 'adb-12345.0.azuredatabricks.net',
+        httpPath: '/sql/1.0/warehouses/abc',
+        intervalsAsString: true,
+        authMode: 'AzureSpM2m',
+        azureClientId: 'entra-app-id',
+        azureClientSecret: 'entra-secret',
+      });
     });
 
-    it('rejects useDatabricksOAuthInAzure with the same Entra-direct error', () => {
+    it('routes Azure host + useDatabricksOAuthInAzure:true + secret to in-house OAuthM2m', () => {
+      // `useDatabricksOAuthInAzure: true` opts into the in-house
+      // (workspace-federated) flow — for M2M that is the kernel's generic
+      // workspace-OIDC client-credentials (OAuthM2m), which works on Azure hosts.
       const opts: ConnectionOptions = {
         host: 'adb-12345.0.azuredatabricks.net',
         path: '/sql/1.0/warehouses/abc',
@@ -153,10 +186,16 @@ describe('KernelAuth + KernelBackend — OAuth M2M auth flow', () => {
         useDatabricksOAuthInAzure: true,
       };
 
-      expect(() => buildKernelConnectionOptions(opts)).to.throw(
-        HiveDriverError,
-        /Azure-direct OAuth.*is not supported/,
-      );
+      const native = buildKernelConnectionOptions(opts);
+      expectNativeConnectionOptions(native, {
+        hostName: 'adb-12345.0.azuredatabricks.net',
+        httpPath: '/sql/1.0/warehouses/abc',
+        intervalsAsString: true,
+        authMode: 'OAuthM2m',
+        oauthClientId: 'client-uuid',
+        oauthClientSecret: 'dose-fake-secret',
+        oauthScopes: ['all-apis'],
+      });
     });
 
     it('rejects a `persistence` hook on M2M (no cache needed)', () => {

tests/unit/kernel/auth-u2m.test.ts

@@ -100,7 +100,10 @@ describe('KernelAuth + KernelBackend — OAuth U2M auth flow', () => {
       expect(native.httpPath).to.equal('/sql/1.0/warehouses/abc');
     });
 
-    it('rejects azureTenantId on the U2M path with the Entra-direct error', () => {
+    it('rejects Entra-direct U2M (Azure host, no secret, no useDatabricksOAuthInAzure)', () => {
+      // On an Azure host the default is the Entra-direct flow; the kernel has no
+      // direct-Entra browser U2M, so this is rejected with a pointer to the
+      // in-house flag (or Thrift). azureTenantId does not change that.
       const opts: ConnectionOptions = {
         host: 'adb-12345.0.azuredatabricks.net',
         path: '/sql/1.0/warehouses/abc',
@@ -110,22 +113,30 @@ describe('KernelAuth + KernelBackend — OAuth U2M auth flow', () => {
 
       expect(() => buildKernelConnectionOptions(opts)).to.throw(
         HiveDriverError,
-        /Azure-direct OAuth.*is not supported/,
+        /Entra-direct\) OAuth U2M is not supported/,
       );
     });
 
-    it('rejects useDatabricksOAuthInAzure on the U2M path', () => {
+    it('routes Azure host + useDatabricksOAuthInAzure:true (no secret) to in-house OAuthU2m', () => {
+      // `useDatabricksOAuthInAzure: true` opts into the in-house
+      // (workspace-federated) browser flow, which the kernel runs against Azure
+      // Databricks workspaces — so this is the U2M happy path, not a rejection.
       const opts: ConnectionOptions = {
         host: 'adb-12345.0.azuredatabricks.net',
         path: '/sql/1.0/warehouses/abc',
         authType: 'databricks-oauth',
         useDatabricksOAuthInAzure: true,
       };
 
-      expect(() => buildKernelConnectionOptions(opts)).to.throw(
-        HiveDriverError,
-        /Azure-direct OAuth.*is not supported/,
-      );
+      const native = buildKernelConnectionOptions(opts);
+      expectNativeConnectionOptions(native, {
+        hostName: 'adb-12345.0.azuredatabricks.net',
+        httpPath: '/sql/1.0/warehouses/abc',
+        intervalsAsString: true,
+        authMode: 'OAuthU2m',
+        oauthRedirectPort: 8030,
+        oauthScopes: ['sql', 'offline_access'],
+      });
     });
 
     it('rejects a `persistence` hook on U2M citing the AuthConfig::External kernel-plumbing gap', () => {