docs(kernel): azure-sp-m2m management token is gated on azure_workspace_resource_id

Correct the wording (bridge docstring/comments, CHANGELOG, CONNECTION_PARAMETERS)
to match the kernel: the Azure SP management token +
X-Databricks-Azure-Workspace-Resource-Id header are sent only when
azure_workspace_resource_id is set (JDBC parity), not always. A workspace-member
SP authenticates with the data token alone; the management token is only needed
for an RBAC-only SP (Azure role, not a workspace member), which is what the
resource id signals.

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

Author: eric-wang-1990

CHANGELOG.md

@@ -2,7 +2,7 @@
 
 # Unreleased
 - Kernel backend (`use_kernel=True`): OAuth U2M with `auth_type="databricks-oauth"` now forwards the connector's `databricks-sql-python` OAuth-app bundle (`client_id` + `sql offline_access` scopes + redirect port) into the kernel, so a bare U2M connection authenticates as `databricks-sql-python` — parity with the Thrift path — instead of inheriting the kernel's own `databricks-sql-connector` default. A caller-supplied `oauth_client_id` (with its coupled `oauth_redirect_port`) is honored, as is a caller-supplied `oauth_scopes`; absent one, the connector default (`sql offline_access`) is forwarded. Note: the kernel binds a single U2M redirect port, so unlike the Thrift path (which tries the full `8020..8024` range) the kernel path uses only one port and does not fall back to the next port if it is already bound — pass `oauth_redirect_port` (with `oauth_client_id`) to pick a free one on a port collision (PECOBLR-4040)
-- Kernel backend (`use_kernel=True`): **Azure Entra (Azure AD) service-principal M2M is now supported.** `auth_type="azure-sp-m2m"` forwards `azure_client_id` / `azure_client_secret`; the kernel is the Azure-aware auth core — it builds the Entra v2.0 token endpoint and the `{app_id}/.default` scope, and **auto-discovers the tenant** from the workspace's `/aad/auth` redirect when `azure_tenant_id` is omitted (matching Thrift). The `Authorization` bearer is the Databricks-audience data token; the kernel **always** also sends the Azure SP management token (`X-Databricks-Azure-SP-Management-Token`), matching Thrift, so a service principal with an Azure RBAC role but no workspace membership can authenticate — set `azure_workspace_resource_id` to add the `X-Databricks-Azure-Workspace-Resource-Id` header too. Azure AD **U2M** (`auth_type="azure-oauth"`) is **not** supported on the kernel path — use `auth_type="databricks-oauth"`, whose in-house OAuth browser flow works against Azure workspaces (the workspace federates login to Entra); `azure-oauth` on `use_kernel=True` is rejected with that pointer (PECOBLR-4141; PECOBLR-4120)
+- Kernel backend (`use_kernel=True`): **Azure Entra (Azure AD) service-principal M2M is now supported.** `auth_type="azure-sp-m2m"` forwards `azure_client_id` / `azure_client_secret`; the kernel is the Azure-aware auth core — it builds the Entra v2.0 token endpoint and the `{app_id}/.default` scope, and **auto-discovers the tenant** from the workspace's `/aad/auth` redirect when `azure_tenant_id` is omitted (matching Thrift). The `Authorization` bearer is the Databricks-audience data token, which alone authenticates a workspace-member SP. Set `azure_workspace_resource_id` and the kernel also sends the Azure SP management token (`X-Databricks-Azure-SP-Management-Token`) + `X-Databricks-Azure-Workspace-Resource-Id` header (matching the JDBC driver), so a service principal with an Azure RBAC role but no workspace membership can authenticate; omit it and no ARM management-scope token is fetched. Azure AD **U2M** (`auth_type="azure-oauth"`) is **not** supported on the kernel path — use `auth_type="databricks-oauth"`, whose in-house OAuth browser flow works against Azure workspaces (the workspace federates login to Entra); `azure-oauth` on `use_kernel=True` is rejected with that pointer (PECOBLR-4141; PECOBLR-4120)
 
 # 4.4.0 (2026-07-22)
 - Raised the minimum supported Python version to 3.10, dropping the end-of-life 3.8/3.9, to update the lockfile and clear CVE-flagged dependencies in the repo (databricks/databricks-sql-python#798)

CONNECTION_PARAMETERS.md

@@ -78,7 +78,7 @@ to change without notice.
 | `identity_federation_client_id`                     | `str`                |   ✅   |   ✅   | `None`                    | Workload identity / token-federation client id (kernel support added in #910).                                                                                 |
 | `experimental_oauth_persistence`                    | `OAuthPersistence`   |   ✅   |   ❌   | `None`                    | **Thrift-only.** The kernel owns its own token lifecycle and does not accept a persistence store.                                                              |
 | `azure_client_id` / `azure_client_secret` / `azure_tenant_id` | `str` | ✅ | ✅ | `None` | Azure service-principal (Entra ID M2M), selected by `auth_type="azure-sp-m2m"`. On the kernel path the connector forwards these to the kernel, which owns Azure resolution (Entra v2.0 token endpoint + the Databricks-resource `.default` scope) (#919). **`azure_tenant_id` is optional on the kernel path too** — like Thrift, the kernel auto-discovers it from the workspace's `/aad/auth` redirect when omitted. |
-| `azure_workspace_resource_id`                       | `str`                |   ✅   |   ✅   | `None`                    | For `azure-sp-m2m`. The SP **management token** (`X-Databricks-Azure-SP-Management-Token`) is always sent; setting this adds the `X-Databricks-Azure-Workspace-Resource-Id` header too, to authorize an SP that has an Azure RBAC role but is not a workspace member. Works on both the kernel and Thrift paths. |
+| `azure_workspace_resource_id`                       | `str`                |   ✅   |   ✅   | `None`                    | For `azure-sp-m2m`. When set, the SP **management token** (`X-Databricks-Azure-SP-Management-Token`) + `X-Databricks-Azure-Workspace-Resource-Id` header are sent, to authorize an SP that has an Azure RBAC role but is not a workspace member. Omit it for a workspace-member SP (the data token authenticates alone; no management token is fetched). Works on both the kernel and Thrift paths. |
 | `_use_cert_as_auth` (+ `_tls_client_cert_file`)     | `bool`               |   ✅   |   ❌   | `False`                   | Authenticate with a TLS client certificate instead of a token. Thrift-only.                                                                                    |
 | `username` / `password`                             | `str`                |   ❌   |   ❌   | `None`                    | **Removed.** Basic auth is no longer supported; passing either raises `ValueError`.                                                                            |
 

src/databricks/sql/backend/kernel/auth_bridge.py

@@ -33,11 +33,13 @@
     Azure service-principal ``azure_client_id`` / ``azure_client_secret`` (plus
     optional ``azure_tenant_id`` / ``azure_workspace_resource_id``). The kernel
     builds the Entra v2.0 token endpoint and the ``{effective_app_id}/.default``
-    scope, auto-discovers the tenant from the workspace's ``/aad/auth`` redirect
-    when ``azure_tenant_id`` is omitted, and always sends the Azure SP
-    management token (adding the ``X-Databricks-Azure-Workspace-Resource-Id``
-    header when ``azure_workspace_resource_id`` is set) — matching the Thrift
-    connector, so an RBAC-only SP can authenticate (PECOBLR-4141).
+    scope, and auto-discovers the tenant from the workspace's ``/aad/auth``
+    redirect when ``azure_tenant_id`` is omitted. When
+    ``azure_workspace_resource_id`` is set, the kernel also sends the Azure SP
+    management token + ``X-Databricks-Azure-Workspace-Resource-Id`` header
+    (matching the JDBC driver), so an RBAC-only SP — one with an Azure role but
+    no workspace membership — can authenticate; omit it for a workspace-member
+    SP (PECOBLR-4141).
 
 ``identity_federation_client_id`` is forwarded with whichever auth shape
 wins resolution. It selects mandatory SP-wide workload-identity token
@@ -234,11 +236,11 @@ def kernel_auth_kwargs(
     # (so connect() is byte-identical between Thrift and use_kernel=True).
     # PECOBLR-4141.
     #
-    # The Authorization bearer is the Databricks-audience data token; the kernel
-    # also always sends the Azure SP management token, and adds the
-    # X-Databricks-Azure-Workspace-Resource-Id header when
-    # azure_workspace_resource_id is set — matching the Thrift connector, so an
-    # RBAC-only SP (Azure role, not a workspace member) can authenticate.
+    # The Authorization bearer is the Databricks-audience data token, which alone
+    # authenticates a workspace-member SP. When azure_workspace_resource_id is
+    # set, the kernel also sends the Azure SP management token +
+    # X-Databricks-Azure-Workspace-Resource-Id header (matching the JDBC driver),
+    # so an RBAC-only SP (Azure role, not a workspace member) can authenticate.
     if auth_type == "azure-sp-m2m":
         azure_client_id = opts.get("azure_client_id")
         azure_client_secret = opts.get("azure_client_secret")
@@ -253,11 +255,10 @@ def kernel_auth_kwargs(
             "azure_client_secret": azure_client_secret,
         }
         # Optional passthroughs: the kernel auto-discovers the tenant when
-        # absent, and always sends the Azure SP management token. When
-        # azure_workspace_resource_id is set, the kernel adds the
-        # X-Databricks-Azure-Workspace-Resource-Id header alongside it (for an
-        # SP with an Azure RBAC role but no workspace membership) — matching the
-        # Thrift connector.
+        # absent. When azure_workspace_resource_id is set, the kernel sends the
+        # Azure SP management token + X-Databricks-Azure-Workspace-Resource-Id
+        # header (for an SP with an Azure RBAC role but no workspace membership)
+        # — matching the JDBC driver; omit it for a workspace-member SP.
         azure_tenant_id = opts.get("azure_tenant_id")
         if azure_tenant_id:
             kwargs["azure_tenant_id"] = azure_tenant_id