Skip to content

Commit 3c90c0d

Browse files
authored
feat(mssql): bundle azure-identity for ActiveDirectoryDefault/AzCli/WorkloadIdentity auth (#1755)
Closes #1754 mssql-jdbc 12.6.1 supports ActiveDirectoryDefault, ActiveDirectoryAzCli, and ActiveDirectoryWorkloadIdentity but delegates them to the azure-identity library (com.azure:azure-identity), which was not previously bundled. Users hitting these modes got: java.lang.NoClassDefFoundError: com/azure/identity/DefaultAzureCredentialBuilder Add azure-identity 1.11.1 (the version mssql-jdbc 12.6.1 was certified against) to deps.edn so all non-browser-dependent Entra ID auth modes work out of the box. The SLF4J version conflict flagged by downstream workarounds (miljodir/DataEngineerPersona#6) does not affect the uberjar: Maven resolves to the newer slf4j-api already present via logback-classic. Also update docs/ref/mssql.rst: - Add ActiveDirectoryDefault (developer az login workflow, WSL2-safe), ActiveDirectoryAzCli, ActiveDirectoryWorkloadIdentity with examples - Deprecation note on ActiveDirectoryPassword (blocked by MFA enforcement in most modern Entra tenants, returns AADSTS50076) - Correct the ActiveDirectoryInteractive note: it works on native Windows / macOS / Linux desktops but fails in WSL2 (linux_xdg_open_failed) and headless environments; ActiveDirectoryDefault is the practical alternative - Quick-reference table of all auth modes and their use cases Add classpath assertion test for DefaultAzureCredentialBuilder, mirroring the existing MSAL4J test added in #1753.
1 parent a054678 commit 3c90c0d

3 files changed

Lines changed: 84 additions & 17 deletions

File tree

‎clojure/deps.edn‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@
1717
com.mysql/mysql-connector-j {:mvn/version "9.0.0"}
1818
com.microsoft.sqlserver/mssql-jdbc {:mvn/version "12.6.1.jre11"}
1919
com.microsoft.azure/msal4j {:mvn/version "1.14.1"}
20+
com.azure/azure-identity {:mvn/version "1.11.1"}
2021
org.xerial/sqlite-jdbc {:mvn/version "3.46.0.0"}
2122

2223
com.opencsv/opencsv {:mvn/version "5.9"}

‎clojure/test/pgloader/load_file/ast_test.clj‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -94,6 +94,14 @@
9494
false))
9595
"com.microsoft.aad.msal4j must be on the classpath for ActiveDirectoryPassword / ActiveDirectoryServicePrincipal auth")))
9696

97+
(deftest test-azure-identity-on-classpath
98+
(testing "azure-identity is bundled — ActiveDirectoryDefault / AzCli / WorkloadIdentity auth modes are available"
99+
(is (try (Class/forName "com.azure.identity.DefaultAzureCredentialBuilder")
100+
true
101+
(catch ClassNotFoundException _
102+
false))
103+
"com.azure.identity must be on the classpath for ActiveDirectoryDefault / ActiveDirectoryAzCli / ActiveDirectoryWorkloadIdentity auth")))
104+
97105
(deftest test-parse-postgresql-synthesises-jdbc-url
98106
(testing "postgresql:// synthesises jdbc-url"
99107
(let [m (parse-uri "postgresql://user:pass@pg:5432/mydb")]

‎docs/ref/mssql.rst‎

Lines changed: 75 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -348,21 +348,33 @@ nor on the lack of support for regular expressions in the engine.
348348
Azure SQL / Azure Active Directory Authentication
349349
-------------------------------------------------
350350

351-
pgloader v4 uses the Microsoft JDBC driver (``mssql-jdbc``) and bundles
352-
MSAL4J, so the following non-interactive Azure AD authentication modes work
353-
out of the box. Always use a ``jdbc:sqlserver://`` URL for Azure SQL so that
354-
``encrypt=true`` and ``authentication=`` reach the driver exactly as written:
355-
356-
``ActiveDirectoryPassword``
357-
Authenticate with an Azure AD username and password::
358-
359-
FROM "jdbc:sqlserver://myserver.database.windows.net:1433;databaseName=mydb;\
360-
authentication=ActiveDirectoryPassword;user=user@tenant.onmicrosoft.com;\
361-
password=secret;encrypt=true;trustServerCertificate=false"
351+
pgloader v4 uses the Microsoft JDBC driver (``mssql-jdbc``) and bundles both
352+
MSAL4J and the Azure Identity library (``azure-identity``), so all
353+
non-browser-dependent Entra ID authentication modes work out of the box.
354+
Always use a ``jdbc:sqlserver://`` URL for Azure SQL so that ``encrypt=true``
355+
and ``authentication=`` reach the driver exactly as written.
356+
357+
Quick reference:
358+
359+
+--------------------------------------+------------------------------------------------+
360+
| Mode | Typical use case |
361+
+======================================+================================================+
362+
| ``ActiveDirectoryServicePrincipal`` | CI/CD — app registration (client ID + secret) |
363+
+--------------------------------------+------------------------------------------------+
364+
| ``ActiveDirectoryManagedIdentity`` | Azure VM / App Service / AKS — no credentials |
365+
+--------------------------------------+------------------------------------------------+
366+
| ``ActiveDirectoryDefault`` | Developer laptop: ``az login`` fallback chain |
367+
+--------------------------------------+------------------------------------------------+
368+
| ``ActiveDirectoryAzCli`` | Developer laptop: explicit ``az login`` token |
369+
+--------------------------------------+------------------------------------------------+
370+
| ``ActiveDirectoryWorkloadIdentity`` | Kubernetes OIDC workload identity |
371+
+--------------------------------------+------------------------------------------------+
372+
| ``ActiveDirectoryPassword`` | **Deprecated** — blocked by MFA enforcement |
373+
+--------------------------------------+------------------------------------------------+
362374

363375
``ActiveDirectoryServicePrincipal``
364-
Authenticate as an Azure AD application (client ID + client secret),
365-
suitable for fully automated / CI pipelines::
376+
Authenticate as an Azure AD application (client ID + client secret) —
377+
the recommended mode for CI/CD pipelines and automated migrations::
366378

367379
FROM "jdbc:sqlserver://myserver.database.windows.net:1433;databaseName=mydb;\
368380
authentication=ActiveDirectoryServicePrincipal;\
@@ -371,16 +383,62 @@ encrypt=true"
371383

372384
``ActiveDirectoryManagedIdentity``
373385
Authenticate using the managed identity of the Azure VM, App Service,
374-
or container that pgloader runs in — no credentials in the URL::
386+
AKS pod, or container that pgloader runs in — no credentials in the URL::
375387

376388
FROM "jdbc:sqlserver://myserver.database.windows.net:1433;databaseName=mydb;\
377389
authentication=ActiveDirectoryManagedIdentity;encrypt=true"
378390

391+
``ActiveDirectoryDefault``
392+
The recommended mode for developer workstations. Uses the Azure
393+
Identity ``DefaultAzureCredential`` chain: environment variables →
394+
workload identity → managed identity → **Azure CLI** → Azure PowerShell.
395+
After a one-time ``az login``, no credentials need to appear in the URL::
396+
397+
FROM "jdbc:sqlserver://myserver.database.windows.net:1433;databaseName=mydb;\
398+
authentication=ActiveDirectoryDefault;encrypt=true;trustServerCertificate=false"
399+
400+
This also works headlessly in WSL2: ``DefaultAzureCredential`` falls back
401+
to ``AzureCliCredential``, which shells out to ``az account
402+
get-access-token`` using your existing ``az login`` session — no browser
403+
popup is needed.
404+
405+
``ActiveDirectoryAzCli``
406+
Like ``ActiveDirectoryDefault`` but always uses the Azure CLI token
407+
exclusively. Useful when you want a predictable, unambiguous credential
408+
source on a developer machine::
409+
410+
FROM "jdbc:sqlserver://myserver.database.windows.net:1433;databaseName=mydb;\
411+
authentication=ActiveDirectoryAzCli;encrypt=true;trustServerCertificate=false"
412+
413+
``ActiveDirectoryWorkloadIdentity``
414+
For Kubernetes pods with OIDC workload identity federation::
415+
416+
FROM "jdbc:sqlserver://myserver.database.windows.net:1433;databaseName=mydb;\
417+
authentication=ActiveDirectoryWorkloadIdentity;encrypt=true"
418+
419+
``ActiveDirectoryPassword``
420+
.. note::
421+
422+
**Deprecated by Microsoft.** This mode is incompatible with mandatory
423+
Entra ID multifactor authentication (MFA), which Microsoft now enforces
424+
by default across most tenants. Attempting it in an MFA-required
425+
tenant returns ``AADSTS50076``. Use ``ActiveDirectoryDefault`` or
426+
``ActiveDirectoryServicePrincipal`` instead.
427+
428+
::
429+
430+
FROM "jdbc:sqlserver://myserver.database.windows.net:1433;databaseName=mydb;\
431+
authentication=ActiveDirectoryPassword;user=user@tenant.onmicrosoft.com;\
432+
password=secret;encrypt=true;trustServerCertificate=false"
433+
379434
.. note::
380435

381-
``ActiveDirectoryInteractive`` opens a browser window for an OAuth2
382-
interactive login and **cannot** be used with pgloader, which runs
383-
non-interactively.
436+
``ActiveDirectoryInteractive`` makes MSAL4J open a system browser via
437+
``xdg-open`` for an OAuth2 interactive login. It works on native Windows,
438+
native macOS, and Linux desktops with a display server. It **fails** in
439+
WSL2 (``linux_xdg_open_failed`` — WSL2 has no JVM-accessible browser
440+
integration), headless Linux, Docker/Podman containers, and CI pipelines.
441+
Use ``ActiveDirectoryDefault`` with an existing ``az login`` session instead.
384442

385443
The native ``mssql://`` scheme defaults to ``encrypt=false`` to match
386444
on-premises SQL Server behaviour. For Azure SQL use the

0 commit comments

Comments
 (0)