remove JDBC properties from docs & add TLS docs to tests-db.md

pruivo · pruivo · commit 3bfbe71048dc · 2026-03-12T15:02:41.000Z
Signed-off-by: Pedro Ruivo &lt;1492066+pruivo@users.noreply.github.com&gt;
diff --git a/docs/guides/server/db.adoc b/docs/guides/server/db.adoc
@@ -510,8 +510,6 @@ This section provides guidance on how to enable these settings in {project_name}
 Configuring the database server with the private keys and certificates is outside the scope of this section.
 Consult your vendor documentation on how to do it.
 
-=== Using {project_name} CLI options
-
 {project_name} provides unified CLI options to configure database TLS settings across different database vendors.
 These options simplify the configuration by abstracting vendor-specific JDBC properties and providing a consistent interface.
 
@@ -545,214 +543,6 @@ Alternatively, you can use `--truststore-paths` instead of the `db-tls-trust-sto
 
 <@kc.start parameters="--db=postgres --db-tls-mode=verify-server --truststore-paths=/path/to/certificate.pem"/>
 
-=== Using the Java truststore
-
-{project_name} allows adding certificates to the Java truststore using the CLI option `--truststore-paths`, which is supported by most drivers.
-The recommended settings for each database are provided below.
-
-==== PostgreSQL
-// https://jdbc.postgresql.org/documentation/ssl/
-PostgreSQL requires the following JDBC properties to be configured.
-
-[%autowidth]
-|===
-|JDBC Property |Value | Description
-
-m|sslmode
-m|verify-full
-|Encrypts the network traffic and validates the server identity.
-
-m|sslfactory
-m|org.postgresql.ssl.DefaultJavaSSLFactory
-|By default, the driver uses `LibPQFactory` which does not support the Java truststore.
-
-|===
-
-<@kc.start parameters="--truststore-paths=/path/to/database_cert.pem --db-url-properties=?sslmode=verify-full&sslfactory=org.postgresql.ssl.DefaultJavaSSLFactory"/>
-
-==== MySQL
-// https://dev.mysql.com/doc/connector-j/en/connector-j-reference-using-ssl.html
-MySQL requires the following JDBC property to be configured.
-
-[%autowidth]
-|===
-|JDBC Property |Value | Description
-
-m|sslMode
-m|VERIFY_IDENTITY
-|Encrypts the network traffic and validates the server identity.
-
-|===
-
-<@kc.start parameters="--truststore-paths=/path/to/database_cert.pem --db-url-properties=?sslMode=VERIFY_IDENTITY"/>
-
-[%autowidth]
-==== MariaDB
-// https://mariadb.com/docs/connectors/mariadb-connector-j/using-tls-ssl-with-mariadb-java-connector
-MariaDB requires the following JDBC property to be configured.
-
-|===
-|JDBC Property |Value | Description
-
-m|sslMode
-m|verify-full
-|Encrypts the network traffic and validates the server identity.
-
-|===
-
-<@kc.start parameters="--truststore-paths=/path/to/database_cert.pem --db-url-properties=?sslMode=verify-full"/>
-
-[%autowidth]
-==== Microsoft SQL Server
-// https://learn.microsoft.com/en-us/sql/connect/jdbc/connecting-with-ssl-encryption?view=sql-server-ver17#configuring-the-connection
-Microsoft SQL Server requires the following JDBC properties to be configured.
-
-|===
-|JDBC Property |Value | Description
-
-m|encrypt
-m|true
-|Encrypts the network traffic.
-
-m|trustServerCertificate
-m|false
-|Validates the server identity.
-
-|===
-
-<@kc.start parameters="--truststore-paths=/path/to/database_cert.pem --db-url-properties=;encrypt=true;trustServerCertificate=false"/>
-
-[%autowidth]
-==== Oracle
-// https://docs.oracle.com/en/database/oracle/oracle-database/21/jajdb/oracle/jdbc/OracleDriver.html
-Oracle by default verifies the server identity when the protocol `tcps` is used.
-
-<@kc.start parameters="--truststore-paths=/path/to/database_cert.pem --db-url=jdbc:oracle:thin:@tcps://host:port/database"/>
-
-=== Using database-specific certificate paths
-
-Alternatively, instead of using the Java truststore with `--truststore-paths`, you can configure each database driver to use its own certificate file or truststore directly through JDBC properties.
-This approach is useful when you want to keep database certificates separate from the Java truststore.
-
-==== PostgreSQL
-
-PostgreSQL supports specifying the certificate file directly using the `sslrootcert` property.
-
-[%autowidth]
-|===
-|JDBC Property |Value | Description
-
-m|sslmode
-m|verify-full
-|Encrypts the network traffic and validates the server identity.
-
-m|sslrootcert
-m|/path/to/cert.pem
-|The path to the server's certificate file on the client machine.
-
-|===
-
-<@kc.start parameters="--db-url-properties=?sslmode=verify-full&sslrootcert=/path/to/cert.pem"/>
-
-==== MySQL
-
-MySQL supports specifying the certificate file or truststore through dedicated SSL properties.
-
-[%autowidth]
-|===
-|JDBC Property |Value | Description
-
-m|sslMode
-m|VERIFY_IDENTITY
-|Encrypts the network traffic and validates the server identity.
-
-m|trustCertificateKeyStoreUrl
-m|file:/path/to/truststore.jks
-|The URL to a custom truststore file containing the server certificate.
-
-m|trustCertificateKeyStorePassword
-m|password
-|The password for the custom truststore (if required).
-
-|===
-
-<@kc.start parameters="--db-url-properties=?sslMode=VERIFY_IDENTITY&trustCertificateKeyStoreUrl=file:/path/to/truststore.jks&trustCertificateKeyStorePassword=password"/>
-
-==== MariaDB
-
-MariaDB supports specifying the certificate file directly using the `serverSslCert` property.
-
-[%autowidth]
-|===
-|JDBC Property |Value | Description
-
-m|sslMode
-m|verify-full
-|Encrypts the network traffic and validates the server identity.
-
-m|serverSslCert
-m|/path/to/cert.pem
-|The path to the server's certificate file on the client machine.
-
-|===
-
-<@kc.start parameters="--db-url-properties=?sslMode=verify-full&serverSslCert=/path/to/cert.pem"/>
-
-==== Microsoft SQL Server
-
-Microsoft SQL Server supports specifying a custom truststore using the `trustStore` and `trustStorePassword` properties.
-
-[%autowidth]
-|===
-|JDBC Property |Value | Description
-
-m|encrypt
-m|true
-|Encrypts the network traffic.
-
-m|trustServerCertificate
-m|false
-|Validates the server identity.
-
-m|trustStore
-m|/path/to/truststore.jks
-|The path to a custom truststore file containing the server certificate.
-
-m|trustStorePassword
-m|password
-|The password for the custom truststore.
-
-|===
-
-<@kc.start parameters="--db-url-properties=;encrypt=true;trustServerCertificate=false;trustStore=/path/to/truststore.jks;trustStorePassword=password"/>
-
-==== Oracle
-
-Oracle supports using Oracle Wallet or Java keystores for certificate management.
-When using `tcps` protocol, you can specify a custom keystore location.
-
-[%autowidth]
-|===
-|JDBC Property |Value | Description
-
-m|javax.net.ssl.trustStore
-m|/path/to/truststore.jks
-|The path to a custom truststore file containing the server certificate.
-
-m|javax.net.ssl.trustStorePassword
-m|password
-|The password for the custom truststore.
-
-m|javax.net.ssl.trustStoreType
-m|JKS
-|The type of truststore (JKS, PKCS12, etc.).
-
-|===
-
-<@kc.start parameters="--db-url=jdbc:oracle:thin:@tcps://host:port/database --db-url-properties=?javax.net.ssl.trustStore=/path/to/truststore.jks&javax.net.ssl.trustStorePassword=password&javax.net.ssl.trustStoreType=JKS"/>
-
-Alternatively, you can use Oracle Wallet by configuring the wallet location in the JDBC URL or through Oracle-specific properties.
-
 == Setting JPA provider configuration option for migrationStrategy
 
 To setup the JPA migrationStrategy (manual/update/validate) you should setup JPA provider as follows:
diff --git a/docs/tests-db.md b/docs/tests-db.md
@@ -70,9 +70,67 @@ Stop TiDB:
 
     docker rm -f tidb
 
-Using built-in profiles to run database tests using docker containers
+
+Enabling SSL
+============
+
+Generate certificate
+-------
+
+To enable TLS connection, a private key and certificate to be provided to the database.
+Let's create a directory named `certs` to store the files we need.
+
+```bash
+mkdir certs ; cd certs
+```
+
+```bash
+openssl req -x509 -newkey rsa:4096 -keyout database-key.pem -out database-cert.pem -sha256 -days 3650 -nodes -subj "/CN=localhost
+```
+
+Private key permissions
+-------
+
+The primary key must belong to the user running in the container and only that user should be able to access.
+PostgreSQL, MariaDB, and MySQL both use user with id 999 (at the time of writing).
+
+```bash
+chmod 0600 database-key.pem
+chown 999:999 database-key.pem
+```
+
+Starting the database container
 -------
 
+Mount the `certs` directory in the container and configure the database as shown below.
+The file `database-cert.pem` can be added to Keycloak truststore to perform the hostname verification.
+By default, the JDBC drivers do not perform the hostname verification.
+
+**PostgreSQL**
+
+```bash
+docker run -d --name postgres --network host --volume '${PWD}:/mnt/certs:ro' -e POSTGRES_USER=keycloak -e POSTGRES_PASSWORD=keycloak -e POSTGRES_DB=keycloak postgres:17 postgres -c ssl=on -c ssl_cert_file=/mnt/certs/database-cert.pem -c ssl_key_file=/mnt/certs/database-key.pem
+```
+
+**MariaDB**
+
+```bash
+docker run -d --name maridb --network host --volume '${PWD}:/mnt/certs:ro' -e MARIADB_ROOT_PASSWORD=keycloak -e MARIADB_USER=keycloak -e MARIADB_PASSWORD=keycloak -e MARIADB_DATABASE=keycloak mariadb:11 --ssl-cert=/mnt/certs/database-cert.pem --ssl-key=/mnt/certs/database-key.pem --require-secure-transport
+```
+
+The option `--require-secure-transport` ensures only TLS connections are accepted by the server.
+
+**MySQL**
+
+```bash
+docker run -d --name mysql --network host --volume '${PWD}:/mnt/certs:ro' -e MYSQL_ROOT_PASSWORD=keycloak -e MYSQL_USER=keycloak -e MYSQL_PASSWORD=keycloak -e MYSQL_DATABASE=keycloak mysql:9 --ssl-cert=/mnt/certs/database-cert.pem --ssl-key=/mnt/certs/database-key.pem --require-secure-transport
+```
+
+The option `--require-secure-transport` ensures only TLS connections are accepted by the server.
+
+Using built-in profiles to run database tests using docker containers
+============
+
 The project provides specific profiles to run database tests using containers. Below is a just a sample of implemented profiles. In order to get a full list, please invoke (`mvn help:all-profiles -pl testsuite/integration-arquillian | grep -- db-`):
 
 * `db-mysql`
