keycloak · vmuzikar · Sep 8, 2023 · Sep 5, 2023
diff --git a/docs/guides/server/db.adoc b/docs/guides/server/db.adoc
@@ -30,11 +30,13 @@ only exists for development use-cases. The `dev-file` database is not suitable f
 
 <@profile.ifProduct>
 
-== Installing a database driver (Oracle)
+== Installing a database driver
 
-Database drivers are shipped as part of Keycloak except for the Oracle Database driver which needs to be installed separately.
+Database drivers are shipped as part of Keycloak except for the Oracle Database and Micrsoft SQL Server drivers which need to be installed separately.
 
-Install the Oracle Database driver if you want to connect to an Oracle Database, or skip this section if you want to connect to a different database.
+Install the necessary driver if you want to connect to one of these databases or skip this section if you want to connect to a different database for which the database driver is already included.
+
+=== Installing the Oracle Database driver
 
 To install the Oracle Database driver for Keycloak:
 
@@ -70,6 +72,41 @@ See the <@links.server id="containers" /> {section} for details on how to build
 
 Then continue configuring the database as described in the next section.
 
+=== Installing the Microsoft SQL Server driver
+
+To install the Microsoft SQL Server driver for Keycloak:
+
+. Download the `mssql-jdbc` JAR file from one of the following sources:
+
+.. Download a version from the https://learn.microsoft.com/en-us/sql/connect/jdbc/download-microsoft-jdbc-driver-for-sql-server[Microsoft JDBC Driver for SQL Server page].
+
+.. Maven Central via `link:++https://repo1.maven.org/maven2/com/microsoft/sqlserver/mssql-jdbc/${properties["mssql-jdbc.version"]}/mssql-jdbc-${properties["mssql-jdbc.version"]}.jar++[mssql-jdbc]`.
+
+.. Installation media recommended by the database vendor for the specific database in use.
+
+. When running the unzipped distribution: Place the `mssql-jdbc` in Keycloak's `providers` folder
+
+. When running containers: Build a custom Keycloak image and add the JARs in the `providers` folder. When building a custom image for the Keycloak Operator, those images need to be optimized images with all build-time options of Keycloak set.
++
+A minimal Dockerfile to build an image which can be used with the Keycloak Operator and includes Microsoft SQL Server JDBC drivers downloaded from Maven Central looks like the following:
++
+[source,dockerfile]
+----
+FROM quay.io/keycloak/keycloak:latest
+ADD --chown=keycloak:keycloak https://repo1.maven.org/maven2/com/microsoft/sqlserver/mssql-jdbc/${properties["mssql-jdbc.version"]}/mssql-jdbc-${properties["mssql-jdbc.version"]}.jar /opt/keycloak/providers/mssql-jdbc.jar
+# Setting the build parameter for the database:
+ENV KC_DB=mssql
+# Add all other build parameters needed, for example enable health and metrics:
+ENV KC_HEALTH_ENABLED=true
+ENV KC_METRICS_ENABLED=true
+# To be able to use the image with the Keycloak Operator, it needs to be optimized, which requires Keycloak's build step:
+RUN /opt/keycloak/bin/kc.sh build
+----
++
+See the <@links.server id="containers" /> {section} for details on how to build optimized images.
+
+Then continue configuring the database as described in the next section.
+
 </@profile.ifProduct>
 
 == Configuring a database

diff --git a/pom.xml b/pom.xml
@@ -148,9 +148,10 @@
         <mariadb.version>10.11</mariadb.version>
         <mariadb-jdbc.version>3.1.4</mariadb-jdbc.version>
         <mssql.version>2022-latest</mssql.version>
-        <mssql-jdbc.version>9.2.0.jre8</mssql-jdbc.version>
-        <!-- this is the oracle driver version also used in the Quarkus BOM -->
+        <!-- this is the mssql driver version also used in the Quarkus BOM -->
+        <mssql-jdbc.version>12.2.0.jre11</mssql-jdbc.version>
         <oracledb.version>19.3</oracledb.version>
+        <!-- this is the oracle driver version also used in the Quarkus BOM -->
         <oracle-jdbc.version>23.2.0.0</oracle-jdbc.version>
 
         <!-- Test -->

diff --git a/quarkus/runtime/pom.xml b/quarkus/runtime/pom.xml
@@ -746,6 +746,16 @@
                         </exclusion>
                     </exclusions>
                 </dependency>
+                <dependency>
+                    <groupId>io.quarkus</groupId>
+                    <artifactId>quarkus-jdbc-mssql</artifactId>
+                    <exclusions>
+                        <exclusion>
+                            <groupId>com.microsoft.sqlserver</groupId>
+                            <artifactId>mssql-jdbc</artifactId>
+                        </exclusion>
+                    </exclusions>
+                </dependency>
             </dependencies>
         </profile>
         <profile>

diff --git a/quarkus/tests/integration/pom.xml b/quarkus/tests/integration/pom.xml
@@ -71,6 +71,11 @@
             <artifactId>bctls-fips</artifactId>
             <scope>test</scope>
         </dependency>
+        <dependency>
+            <groupId>com.microsoft.sqlserver</groupId>
+            <artifactId>mssql-jdbc</artifactId>
+            <scope>test</scope>
+        </dependency>
 
         <!-- Minimal test dependencies to *-deployment artifacts for consistent build order -->
         <dependency>

diff --git a/quarkus/tests/junit5/pom.xml b/quarkus/tests/junit5/pom.xml
@@ -92,6 +92,10 @@
             <groupId>org.testcontainers</groupId>
             <artifactId>mssqlserver</artifactId>
         </dependency>
+        <dependency>
+            <groupId>com.microsoft.sqlserver</groupId>
+            <artifactId>mssql-jdbc</artifactId>
+        </dependency>
         <dependency>
             <groupId>org.apache.maven.wagon</groupId>
             <artifactId>wagon-http-shared</artifactId>

diff --git a/quarkus/tests/junit5/src/main/java/org/keycloak/it/utils/RawKeycloakDistribution.java b/quarkus/tests/junit5/src/main/java/org/keycloak/it/utils/RawKeycloakDistribution.java
@@ -389,6 +389,10 @@ private Path prepareDistribution() {
             if (!inited || (reCreate || !dPath.toFile().exists())) {
                 FileUtil.deleteDirectory(dPath);
                 ZipUtils.unzip(distFile.toPath(), distRootPath);
+                if (System.getProperty("product") != null) {
+                    // MS SQL Server driver might be excluded if running as a product build
+                    copyProvider(dPath, "com.microsoft.sqlserver", "mssql-jdbc");
+                }
             }
 
             // make sure script is executable
@@ -525,8 +529,12 @@ public void copyOrReplaceFile(Path file, Path targetFile) {
     }
 
     public void copyProvider(String groupId, String artifactId) {
+        copyProvider(getDistPath(), groupId, artifactId);
+    }
+
+    private static void copyProvider(Path distPath, String groupId, String artifactId) {
         try {
-            Files.copy(Maven.resolveArtifact(groupId, artifactId), getDistPath().resolve("providers").resolve(artifactId + ".jar"));
+            Files.copy(Maven.resolveArtifact(groupId, artifactId), distPath.resolve("providers").resolve(artifactId + ".jar"));
         } catch (IOException cause) {
             throw new RuntimeException("Failed to copy JAR file to 'providers' directory", cause);
         }

diff --git a/testsuite/integration-arquillian/servers/auth-server/quarkus/pom.xml b/testsuite/integration-arquillian/servers/auth-server/quarkus/pom.xml
@@ -371,6 +371,13 @@
                                             <type>jar</type>
                                             <outputDirectory>${auth.server.home}/providers</outputDirectory>
                                         </artifactItem>
+                                        <artifactItem>
+                                            <groupId>com.microsoft.sqlserver</groupId>
+                                            <artifactId>mssql-jdbc</artifactId>
+                                            <version>${mssql-jdbc.version}</version>
+                                            <type>jar</type>
+                                            <outputDirectory>${auth.server.home}/providers</outputDirectory>
+                                        </artifactItem>
                                     </artifactItems>
                                 </configuration>
                             </execution>