Optionally, you can enable Transport Layer Security (TLS), commonly known as SSL, access between the , its services, and the .

Tip: SSL can be applied to any supported database distribution.

NOTE: This configuration applies only to the databases that are used to store metadata for the . For more information on enabling SSL for external JDBC connections, see Configure Security for Relational Connections.

Install SSL Certificate

Before you enable SSL for the , you must deploy a security certificate on the .  The certificate must be installed on the , whether the databases are installed locally or remotely.

NOTE: Please retain the location of the certificate on the server, as well as other information listed in the sections below.


NOTE: If you receive a org.postgresql.util.PSQLException: Could not read SSL key file error message when connecting via SSL to your PostgreSQL databases, you may need to convert your certificate to DER format and re-install. For more information, see https://www.enterprisedb.com/postgres-tutorials/how-enable-ssl-authentication-edb-postgres-advanced-server.

Enable

To enable use of SSL to connect to the platform databases, please complete the following.

Steps:

  1. Locate the following setting, and set it to true:
  2. "webapp.database.ssl.enabled": true,
  3. Do not save your changes yet.

Configure for Certificate

After the SSL certificate has been deployed to the server, please complete the following steps to configure use of the certificate by the .

Steps:

  1. Locate the following settings and set them accordingly:

    "webapp": {
        "database": {
            "ssl": {
                "rejectUnauthorized": true, 
                "serverCertificateAuthorityFile": "/path/to/caFile",
                "clientKeyFile": "/path/to/keyFile",
                "clientCertificateFile": "/path/to/certFile"
            }
        }
    }
    SettingDescription
    rejectUnauthorized(optional) Set this value to true to reject access by any client that is presenting an invalid server certificate.
    serverCertificateAuthorityFile

    (optional) Path on the to the certificate authority verification file, which is used to verify the presented server certificate.

    clientKeyFile

    (optional) Path on the to the client key file, which is used for client authentication.

    clientCertificateFile

    (optional) Path on the to the SSL certificate to use for client authentication.

  2. Save your changes and restart the platform.

Configure Databases for SSL

After you have enabled the use of SSL in the platform, you must configure each  to use secure access. 

Steps:

To enable SSL on individual databases, you must apply the appropriate configuration settings as additionalConnectionProperties for the database. 

  1. Tip: Although you can apply these changes through , it may be easier to apply through the Admin Settings page in the if it is available.

  2. Search for the following string: 

    database.additionalConnectionProperties
  3. For each of the above settings, you must add the following text string(s) containing key-value pairs to the additionalConnectionProperties, based on your database distribution, for each listed service database:

    NOTE: Key-value pairs must be separated by an ampersand (&). See Configuration Examples below.

    setting and value

    PostgreSQLMySQL
    "webapp.database.ssl.enabled": true,ssl=truerequireSSL=true
    "webapp.database.ssl.rejectUnauthorized": true,sslmode=requireverifyServerCertificate=true
    "webapp.database.ssl.serverCertificateAuthorityFile": "/path/to/caFile",sslrootcert=/path/to/caFiletrustCertificateKeyStoreUrl=file:/path/to/truststore&trustCertificateKeyStorePassword=<password>
    "webapp.database.ssl.clientKeyFile": "/path/to/keyFile",sslkey=/path/to/keyFileclientCertificateKeyStoreUrl=file:/path/to/truststore&clientCertificateKeyStorePassword=<password>
    "webapp.database.ssl.clientCertificateFile": "/path/to/certFile",sslcert=/path/to/certFile
  4. Apply the values based on your configuration example below.

Configuration Example - Minimal SSL configuration

For minimal SSL configuration, the configuration that you performed above look like the following:

"webapp": {
    "database": {
        "ssl": {
            "enabled": true, 
            "rejectUnauthorized": true, 
            "serverCertificateAuthorityFile": "",
            "clientKeyFile": "",
            "clientCertificateFile": ""
        }
    }
}

PostgreSQL:

"<service>.database.additionalConnectionProperties": "ssl=true&sslmode=require",

MySQL:

"<service>.database.additionalConnectionProperties": "requireSSL=true&verifyServerCertificate=true",

Configuration Example - SSL with Client Authentication

If you have deployed a client key and certificate for authentication, your configuration may look like the following:

"webapp": {
    "database": {
        "ssl": {
            "enabled": true, 
            "rejectUnauthorized": true, 
            "serverCertificateAuthorityFile": "",
            "clientKeyFile": "/path/to/keyFile",
            "clientCertificateFile": "/path/to/certFile"
        }
    }
}

PostgreSQL:

"<service>.database.additionalConnectionProperties": "ssl=true&sslmode=require&sslkey=/path/to/keyFile&sslcert=/path/to/certFile",

MySQL:

"<service>.database.additionalConnectionProperties": "requireSSL=true&verifyServerCertificate=true&clientCertificateKeyStoreUrl=file:/path/to/truststore&clientCertificateKeyStorePassword=<password>",

Configuration Example - SSL with a custom certificate

If you have deployed a custom SSL certificate on the , your configuration may look like the following. For more information, see Install SSL Certificate.

"webapp": {
    "database": {
        "ssl": {
            "enabled": true, 
            "rejectUnauthorized": true, 
            "serverCertificateAuthorityFile": "/path/to/caFile",
            "clientKeyFile": "",
            "clientCertificateFile": ""
        }
    }
}

PostgreSQL:

"<service>.database.additionalConnectionProperties": "ssl=true&sslmode=require&sslrootcert=/path/to/caFile",

MySQL:

"<service>.database.additionalConnectionProperties": "requireSSL=true&verifyServerCertificate=true&trustCertificateKeyStoreUrl=file:/path/to/truststore&trustCertificateKeyStorePassword=<password>",

Use

When SSL is enabled and configured, users of the  automatically connect to the database using SSL. 

NOTE: There may be a small performance cost to using SSL.