FEAT: Add ActiveDirectoryServicePrincipal support for bulk copy

[bewithgaurav]

Work Item / Issue Reference

AB#45137

GitHub Issue: #534

---

Summary

Adds Authentication=ActiveDirectoryServicePrincipal support for bulk copy. Partial fix for #534. Addresses the exact error in the issue report ("Authentication method 'ActiveDirectoryServicePrincipal' is not supported. No token provider was registered for this method.").

Why a callback rather than pre-acquire

The other Entra ID modes already supported in bulk copy (Default, DeviceCode, Interactive) pre-acquire a JWT in Python and pass it as access_token. ServicePrincipal can't work that way:

• ClientSecretCredential(tenant_id, client_id, client_secret) requires tenant_id as a constructor argument.
• The connection string doesn't carry tenant_id; azure-identity doesn't discover it from anywhere.
• The only place tenant is available client-side is the STS URL the server hands back during the FedAuth pre-login (this is what ODBC does internally; that's why ODBC has never needed tenant_id on the connection string).

So bulk copy must register a callback that's invoked mid-handshake. mssql-py-core hands the callback (spn, sts_url, auth_method) and we parse the tenant from the STS URL on every call.

Flow

mssql-python                              mssql-py-core (Rust)              mssql-tds (Rust)

cursor.bulkcopy()
  parses conn string (UID/PWD)
  ServicePrincipalAuth
    .make_token_factory(uid, pwd)
  returns _factory closure

  pycore_context = {
      "authentication": "AD-SP",
      "user_name":  client_id,
      "password":   client_secret,
      "entra_id_token_factory": _factory,
      ...
  }
                                          PyCoreConnection(ctx)
                                            validate_auth / transform_auth
                                            register factory in
                                              auth_method_map[SP]
                                                                                TDS pre-login, open TCP/TLS
                                                                                server: FedAuthInfo
                                                                                  (spn, sts_url)
                                            context.entra_id_
                                              token_factory()
                                            factory.create_token invoked
  _factory(spn, sts_url, method)        <-- (spn, sts_url, m)
    _parse_tenant_id(sts_url)
    ClientSecretCredential(
        tenant_id, client_id,
        client_secret)
    .get_token(scope=spn + "/.default")
    return jwt.encode("utf-16-le")
                                                                                FedAuth token packet
                                                                                SQL Server validates

Test

$ python -m pytest tests/test_008_auth.py -q
65 passed in 0.77s

27 new tests cover:

• TestAuthType::test_auth_type_constants extended for SERVICE_PRINCIPAL
• TestProcessAuthParameters::test_service_principal_auth_leaves_odbc_path_alone, test_service_principal_auth_case_insensitive
• TestExtractAuthType::test_serviceprincipal
• TestParseTenantId: GUID, GUID without trailing slash, domain, query string, extra path segments, empty string, no path
• TestServicePrincipalAuth: factory returns callable, requires non-empty client_id and client_secret, returns UTF-16LE bytes, forwards credentials to ClientSecretCredential, builds scope from SPN (and keeps /.default suffix when already present), errors on unparseable STS URL, propagates ClientAuthenticationError as RuntimeError

Connection string example

import mssql_python

conn = mssql_python.connect(
    "Server=tcp:myserver.database.windows.net;"
    "Database=mydb;"
    "Authentication=ActiveDirectoryServicePrincipal;"
    "UID=<client-id-guid>;"
    "PWD=<client-secret>;"
    "Encrypt=yes;"
)
cur = conn.cursor()
cur.bulkcopy("mytable", [(1, "a"), (2, "b")])  # uses the callback under the hood

Same connection string keeps working for regular queries (ODBC handles ServicePrincipal natively in the non-bulk-copy path).

Out of scope

• ActiveDirectoryPassword needs the same callback shape but a different azure-identity credential class. Separate PR; py-core still rejects it today with a clear error.
• ActiveDirectoryIntegrated needs SSPI/Kerberos wiring at the Rust layer, not a Python callback. Separate work.

Dependencies

• Requires mssql-py-core 0.1.5+. This Python PR will fail at import or runtime against earlier py-core versions because the entra_id_token_factory dict key is silently ignored there. Will update the dependency pin once a new mssql-py-core wheel is published.

[Copilot]

Pull request overview

This PR adds bulk copy support for Authentication=ActiveDirectoryServicePrincipal by registering an Entra ID token-factory callback (invoked mid-handshake) so the tenant can be derived from the STS URL returned by the server, aligning bulk copy behavior with ODBC’s native Service Principal handling for the normal query path.

Changes:

• Added AuthType.SERVICE_PRINCIPAL and updated auth-type extraction/processing to recognize Service Principal mode.
• Implemented ServicePrincipalAuth.make_token_factory() and _parse_tenant_id() to generate UTF-16LE JWTs during FedAuth handshake.
• Updated cursor.bulkcopy() to register entra_id_token_factory for Service Principal auth; added tests and a changelog entry.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
mssql_python/constants.py	Adds SERVICE_PRINCIPAL enum value for connection-string auth detection.
mssql_python/auth.py	Adds tenant parsing + token-factory callback for Service Principal; updates auth detection/mapping.
mssql_python/cursor.py	Registers the callback for bulkcopy when _auth_type == "serviceprincipal"; preserves credentials for py-core auth resolution.
tests/test_008_auth.py	Adds unit tests for tenant parsing, factory behavior, and new auth-type detection.
CHANGELOG.md	Documents new bulk copy Service Principal support and notes py-core requirement.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[github-actions]

📊 Code Coverage Report

🔥 Diff Coverage 92%

🎯 Overall Coverage 80%

📈 Total Lines Covered: 6737 out of 8350 📁 Project: mssql-python

---

Diff Coverage

Diff: main...HEAD, staged and unstaged changes

• mssql_python/auth.py (91.2%): Missing lines 202-203,214,253-254
• mssql_python/connection.py (100%)
• mssql_python/constants.py (100%)

Summary

• Total: 66 lines
• Missing: 5 lines
• Coverage: 92%

mssql_python/auth.py

Lines 198-207

  198     from urllib.parse import urlparse
  199 
  200     try:
  201         parsed = urlparse(sts_url)
! 202     except (ValueError, AttributeError):
! 203         return None
  204     # Reject anything that isn't an https URL with a netloc. ``urlparse`` will
  205     # happily put a bare string like ``"tenant-guid"`` into ``path``, which
  206     # would then look like a valid tenant. Azure AD STS URLs are always https.
  207     if parsed.scheme != "https" or not parsed.netloc:

---

Lines 210-218

  210     if not path:
  211         return None
  212     first_segment = path.split("/", 1)[0]
  213     if not first_segment:
! 214         return None
  215     if first_segment.lower() in _RESERVED_TENANTS:
  216         return None
  217     return first_segment

---

Lines 249-258

  249             try:
  250                 from azure.identity import ClientSecretCredential
  251                 from azure.core.exceptions import ClientAuthenticationError
  252                 from azure.core.pipeline.transport import RequestsTransport
! 253             except ImportError as e:
! 254                 raise RuntimeError(
  255                     "Azure authentication libraries are not installed. "
  256                     "Please install with: pip install azure-identity azure-core"
  257                 ) from e

---

---

📋 Files Needing Attention

📉 Files with overall lowest coverage (click to expand)

mssql_python.pybind.logger_bridge.cpp: 59.2%
mssql_python.pybind.ddbc_bindings.h: 59.9%
mssql_python.pybind.logger_bridge.hpp: 70.8%
mssql_python.pybind.connection.connection.cpp: 76.2%
mssql_python.pybind.ddbc_bindings.cpp: 76.2%
mssql_python.row.py: 76.9%
mssql_python.__init__.py: 77.3%
mssql_python.ddbc_bindings.py: 79.6%
mssql_python.logging.py: 85.5%
mssql_python.connection.py: 85.6%

---

🔗 Quick Links

⚙️ Build Summary	📋 Coverage Details
View Azure DevOps Build	Browse Full Coverage Report

[jahnvi480]

PR lgtm!
I have just posted few questions and wanted clarification and understanding on others.
Comments are non-blocking, hence approving the PR.

[jahnvi480]

auth_method is silenced via unused-argument. Are we expecting it to be used in furture?

[jahnvi480]

_credential_cache is never evicted. After a client_secret rotation, a fresh entry is added under the new secret_hash, but the old ClientSecretCredential stays in the dict for the life of the process - holding the old secret in memory plus its internal token cache. For long-lived processes that rotate secrets periodically this is a slow leak.

Consider evicting any prior entries matching (serviceprincipal, tenant_id, client_id, *) when inserting a new secret_hash, or documenting the long-running-process caveat. Not blocking.

[jahnvi480]

message says "see debug logs for provider details" but the provider error is logged at logger.error(...) a few lines up, not debug. Either drop the log to debug or update the message to "see error logs" so the user knows where to actually look.

[jahnvi480]

secret_hash is recomputed on every factory invocation, but client_secret is fixed for the lifetime of the closure returned by make_token_factory. Compute the hash once in the outer scope and capture it:

secret_hash = hashlib.sha256(client_secret.encode("utf-8")).hexdigest()
def _factory(spn, sts_url, auth_method):
    ...
    cache_key = _credential_cache_key(_AuthInternal.SERVICE_PRINCIPAL,
        {"tenant_id": tenant_id, "client_id": client_id, "secret_hash": secret_hash})

Save the SHA-256 per call (tens of μs each) and remove a redundant import of hashlib from the hot path.

[jahnvi480]

AADAuth.get_token_struct (used for the access_token path) returns a <I length-prefixed UTF-16LE struct. This factory returns bare token.encode("utf-16-le") with no length prefix.

one line in the docstring like "py-core handles the FedAuth length-prefix wrapping; do not pre-wrap" so a future reader doesn't try to "fix" this to match get_token_struct.