documentation/Reference/Configuration/Security Configuration.md
Java assumes some configuration is in place to allow it to use SSL/TLS. This is setup with environment variables that form part of the JAVA_ARGS parameter.
The tools used to manage cryptographic stores are the same (keytool and openssl) but Java differentiates the stores based on their purpose.
Used to store the (public) certificates of trusted entities. Determines whether the remote authentication credentials, and thus the connection, should be trusted.
| JAVA_ARGS value | Purpose |
|---|---|
javax.net.ssl.trustStore | the path to a Truststore containing the certificates of the signing authority |
javax.net.ssl.trustStorePassword | the password to access the Truststore defined in javax.net.ssl.trustStore |
If no trust store is explicitly defined then the following locations will be checked:
$JAVA_HOME/lib/security/jssecacerts$JAVA_HOME/lib/security/cacertsHOME/.keystore (Linux)%USER_HOME%\.keystore (Windows)Used to store your keys and certificates to allow the remote party to authenticate you.
| JAVA_ARGS value | Purpose |
|---|---|
javax.net.ssl.keyStore | the path to a key store containing the client's TLS/SSL certificates |
javax.net.ssl.keyStorePassword | the password to access the Truststore defined in javax.net.ssl.keyStore |
Where you are using a native connector driver you will need to provide the relevant connection details as part of the connection string and you may need to provide similar information in two ways - once for Flyway's API driver and once for the vendor native tooling.
The exact mechanism will vary for each database but we'll look at enabling TLS with MongoDB as an example.
my_certificates.pem.This will involve configuring the Java Truststore and setting the JAVA_ARGS parameters javax.net.ssl.trustStore and javax.net.ssl.trustStorePassword.
How the Truststore file is created will depend on who is providing the certificates and in what format they are originally.
You can find some reference material here:
Keytool referencekeytool will only process a single certificate at a time.The steps would look like this:
keytool to convert my_certificates.pem into /tmp/certs/my_certificates.jksJAVA_ARGS to include -Djavax.net.ssl.trustStore=/tmp/certs/my_certificates.jks and -Djavax.net.ssl.trustStorePassword=<certstore-password>Note: JKS is an older format, PKCS12 supersedes it but should work just the same.
Assuming you are using Javascript migrations then Flyway will use the Mongosh native tooling to deploy these. In order to configure Mongosh, all the information it needs will also need to be in the connection string. This is because:
Where you would typically invoke Mongosh on the command line with parameters like this:
mongosh "mongodb://localhost:27017" --tls --tlsCAFile="/tmp/certs/my_certificates.pem"
This is the functionally equivalent command using a connection string:
mongosh "mongodb://localhost:27017/?tls=true&tlsCAFile=/tmp/certs/my_certificates.pem"
You can find reference information about the Mongo connection string parameters here
The connection string is passed to Flyway as the URL parameter:
[environments.tls-mongodb]
url = "mongodb://localhost:27017/?tls=true&retryWrites=false&tlsCAFile=/tmp/certs/my_certificates.pem"
user = "your username"
password = "your password"
{% include enterprise.html %}
This feature is available only in Native Connectors mode with MongoDB.
As highlighted in the previous section, the MongoDB Java Driver in Native Connectors requires Java Keystore/Truststore, while Mongosh relies on tlsCertKeyFile/tlsCAFile, which must be provided as parameters in the connection string. To simplify configuration, Flyway automatically provisions the Truststore/Keystore based on the tlsCAFile/tlsCertificateKeyFile connection string parameters.
Note
FLYWAY_SSL_AUTOCONFIGURATION to false.JAVA_ARGS settings are detected.