Feature dependencies of the Microsoft JDBC Driver for SQL Server

Download JDBC driver

A basic application that declares only the com.microsoft.sqlserver:mssql-jdbc dependency resolves only the driver JAR at runtime. Some driver features use optional Java libraries or native components. Add those dependencies only when your application uses the corresponding feature.

Use the dependency versions that match your driver version. The versions in this article come from the published POMs for driver 13.6.2. For any other release, read the POM that shipped with that release. This article lists the current release first and keeps historical dependency information for older applications.

Compile-time dependencies

The published POMs for the jre8 and jre11 artifacts declare these feature dependencies:

The POM marks the feature libraries in the previous table as optional. Maven and Gradle don't add optional dependencies transitively for a normal application dependency, so add the dependencies your feature needs to your application directly. The two OSGi API dependencies use provided scope instead. An OSGi framework supplies them at runtime, so don't add them to a standard Java application.

Runtime dependencies

For a base application, add only the driver dependency:

<dependency>
    <groupId>com.microsoft.sqlserver</groupId>
    <artifactId>mssql-jdbc</artifactId>
    <version>13.6.2.jre11</version>
</dependency>

If your application uses Microsoft Entra authentication modes that rely on Azure Identity, add azure-identity and the pinned Azure SDK HTTP transport. azure-identity brings azure-core-http-netty transitively, but at a lower version than the driver POM declares, so declare the transport yourself to get the version the driver was built against:

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
    <version>1.18.4</version>
</dependency>
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-core-http-netty</artifactId>
    <version>1.16.6</version>
</dependency>

If your application uses the Azure Key Vault provider for Always Encrypted, add azure-security-keyvault-keys, azure-identity, and the pinned Azure SDK HTTP transport:

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-security-keyvault-keys</artifactId>
    <version>4.11.1</version>
</dependency>
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
    <version>1.18.4</version>
</dependency>
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-core-http-netty</artifactId>
    <version>1.16.6</version>
</dependency>

If your application uses Always Encrypted with secure enclaves, add the enclave dependencies that your attestation path uses:

<dependency>
    <groupId>com.google.code.gson</groupId>
    <artifactId>gson</artifactId>
    <version>2.11.0</version>
</dependency>
<dependency>
    <groupId>org.bouncycastle</groupId>
    <artifactId>bcprov-jdk18on</artifactId>
    <version>1.84</version>
</dependency>

If your application loads a Public-Key Cryptography Standards (PKCS) #1 private key for client certificate authentication, add bcpkix-jdk18on:

<dependency>
    <groupId>org.bouncycastle</groupId>
    <artifactId>bcpkix-jdk18on</artifactId>
    <version>1.84</version>
</dependency>

If your application uses useFmtOnly, add the ANTLR runtime:

<dependency>
    <groupId>org.antlr</groupId>
    <artifactId>antlr4-runtime</artifactId>
    <version>4.9.3</version>
</dependency>

If you're not using Maven or Gradle, download the same libraries and their transitive dependencies, then place them on the same application classpath as the driver.

Dependency requirements for the JDBC driver

Work with the Azure Key Vault provider

Use these direct dependencies:

The current Azure Key Vault sample targets the modern Azure SDK path. For more information, see Azure Key Vault sample version 9.2 and later.

Choose authentication dependencies

The following table lists authentication dependencies beyond the driver JAR. Microsoft Authentication Library for Java (MSAL4J), published as com.microsoft.azure:msal4j, provides several Microsoft Entra authentication paths. Include each Java library's transitive dependencies. Native dynamic-link libraries (DLLs) must match your Java virtual machine (JVM) architecture.

The azure-identity dependency shown in this article includes MSAL4J transitively. You can use that dependency for the MSAL4J paths, or add MSAL4J and its transitive dependencies directly. The two ActiveDirectoryIntegrated rows describe alternative paths, not dependencies that every application must install together.

Work with Microsoft Entra authentication

Add com.azure:azure-identity when your authentication mode uses Azure Identity credentials. Microsoft Entra authentication modes include ActiveDirectoryPassword, ActiveDirectoryIntegrated, ActiveDirectoryManagedIdentity, ActiveDirectoryServicePrincipal, ActiveDirectoryServicePrincipalCertificate, ActiveDirectoryInteractive, and ActiveDirectoryDefault.

For authentication=ActiveDirectoryIntegrated, the driver selects one of two authentication paths:

• On Windows, if the native wrapper loads, the driver uses the native authentication path. The Java virtual machine (JVM) loads the versioned, architecture-specific wrapper mssql-jdbc_auth-<version>-<arch>.dll, which ships with the JDBC driver download and is also published to Maven Central as com.microsoft.sqlserver:mssql-jdbc_auth. For example, driver 13.6.2 for an x64 JVM loads mssql-jdbc_auth-13.6.2.x64.dll. Place that wrapper on the java.library.path. The wrapper then loads mssql-auth.dll when the driver requests a token. The JDBC package doesn't include mssql-auth.dll. Install Microsoft ODBC Driver 18 for SQL Server or Microsoft OLE DB Driver 19 for SQL Server to get it, and let that installer place the file.
• If the native wrapper isn't loaded, the driver uses Microsoft Authentication Library for Java (MSAL4J) on both Windows and non-Windows systems. Configure Kerberos for this path and include MSAL4J with its transitive dependencies on the application classpath. The azure-identity dependency shown in this article includes MSAL4J transitively. The Windows native DLLs aren't required for this Java authentication path.

If neither the native wrapper nor MSAL4J is available, the driver reports that it failed to load both the authentication DLL and the MSAL4J Java library. Add the Java dependencies and configure Kerberos, or configure the native path on Windows.

If the wrapper loads but can't load mssql-auth.dll, the driver raises a separate error that names mssql-auth.dll and includes a hexadecimal Windows error code. It doesn't switch to MSAL4J after this failure. Install Microsoft ODBC Driver 18 for SQL Server or Microsoft OLE DB Driver 19 for SQL Server, and confirm that the installed architecture matches the JVM.

For the authentication walkthrough and mode-specific setup, see Connect using Microsoft Entra authentication.

Historical dependency notes

Applications on older driver versions might still use previous-generation Azure SDK libraries such as com.microsoft.azure:adal4j, com.microsoft.azure:azure-keyvault, and com.microsoft.rest:client-runtime. Keep those versions aligned with the POM for the driver version you run. Don't mix dependency sets from different major driver versions unless you tested the exact application.

Related content

• Install the JDBC driver
• Microsoft Entra authentication
• Using Always Encrypted with the JDBC driver
• Using Always Encrypted with secure enclaves
• JDBC driver GitHub repository
• JDBC driver API reference