1. Guide
  2. Administering Oracle Spatial Studio
  3. Using a CA-Signed SSL Certificate in the Quick Start Installation

2.11 Using a CA-Signed SSL Certificate in the Quick Start Installation

The Spatial Studio Quick Start installation typically comes with a self-signed certificate for handling SSL or HTTPS URL connection encryption.

However, this is not desirable as the browser always warns you about an insecure connection. Starting with Spatial Studio Release 23.2.0, you can use your own (CA-signed) X.509 certificate.

Review the following sections and perform the steps that apply to your scenario.

Parent topic: Administering Oracle Spatial Studio

2.11.1 Preparing a CA-Signed Certificate and Private Key for the Spatial Studio Server

You can prepare a CA-signed certificate and a private key for the Spatial Studio server.

  1. Obtain an SSL certificate from a publicly recognized certificate authority (CA).

    The certificate is generally presented as two files that are linked to the domain of your web site:

    • yourdomain.crt (X.509 certificate)
    • yourdomain.key (private key)

    Sometimes the yourdomain.crt file is in the PEM format, in which case the file name appears as yourdomain.pem or fullchain.pem, and the key file may be named like privatekey.pem.

    However, Java cannot make use of such files directly for SSL support, as these files are generated and supported only by OpenSSL ecosystem tools. Therefore, you must first convert the CA certificate file and the private key file into a Java key store, which can then be used in the Spatial Studio Quick Start.

  2. Convert the X.509 certificate and private key into a PKCS12 file using the following openssl command:
    openssl pkcs12 -export -in yourdomain.crt -inkey yourdomain.key \
               -out yourdomain.p12 -name [some-alias] \
               -CAfile yourdomain.crt -caname root

    Also, note the following while running the preceding command:

    • Ensure that you provide a password when requested.
    • Optionally, add the -chain option to the command to preserve the full certificate chain when working with a real CA-signed certificate.
    • Apply the same openssl command for all CA certificate and private key file extensions.
  3. Convert the PKCS12 file into a Java keystore file using the following Java keytool command.
    keytool -importkeystore \
        -deststorepass ChangeIt -destkeypass ChangeIt -destkeystore yourdomain.keystore \
        -srckeystore yourdomain.p12 -srcstoretype PKCS12 -srcstorepass [password_from_step2] \
        -alias [some-alias]

    The preceding command generates a Java keystore file, yourdomain.keystore, which is protected with the password ChangeIt.

  4. Configure the Spatial Studio server to use the Java keystore file.

Parent topic: Using a CA-Signed SSL Certificate in the Quick Start Installation

2.11.2 Configuring the Spatial Studio Server to Use a Java Keystore

You can configure your server to use a Java keystore file containing an X.509 certificate.

This section assumes that you already have a Java keystore file (yourdomain.keystore) generated from an X.509 certificate and private key as explained in Preparing a CA-Signed Certificate and Private Key for the Spatial Studio Server. It is important to note that the keystore file generated in a different manner may not work with Spatial Studio.
  1. Edit the conf/server.json configuration file in the Oracle_Spatial_Studio directory and modify the following three SSL fields to reflect the location of yourdomain.keystore file and its password.
    "sslKeyStorePath": "<path_to_yourdomain.keystore_file>",
"sslKeyStorePassword": "ChangeIt",
"sslKeyManagerPassword": "ChangeIt",
  2. Optionally, obfuscate your keystore protection password (sslKeyStorePassword and sslKeyManagerPassword) by performing the following steps.
    1. Navigate to the Oracle_Spatial_Studio directory and run the following command.
      java -cp ./servletContainer/jetty-util-9.4.51.v20230217.jar org.eclipse.jetty.util.security.Password <
user> ChangeIt

      The ChangeIt password for the user is obfuscated and the output is as shown. 

      ChangeIt
OBF:1pam1o661saj1v9i1v941sar1o4g1pdc
MD5:72df16e805e7d9c88437b9ea5f8995d6
CRYPT:blSK4yQrQaaxo
    2. Copy the string starting with OBF and update the sslKeyStorePassword and sslKeyManagerPassword fields in the server.json file to use the obfuscated password instead of the plain text password.
  3. Restart the Spatial Studio server to make the changes take effect.

    You should see a similar log towards the beginning of the console output:

    2023-07-27 01:31:50.740:INFO:oejus.SslContextFactory:main: x509=X509@5e5073ab([followed by some organization name or alias info related to your CA cert]

    You can now securely access the Spatial Studio Quick Start using the URL https://yourdomain.com:4040/spatialstudio.

Parent topic: Using a CA-Signed SSL Certificate in the Quick Start Installation

2.11.3 Configuring Reverse Proxy for the Quick Start Installation

If your Spatial Studio Quick Start installation is running on the same host, where you already have an Apache HTTP or NGINX server running, then you can simply use a reverse proxy to ensure a secure connection.

With this approach, you are not required to make any configuration changes to the Spatial Studio server itself.

  1. Configure a CA-signed certificate on your Apache HTTP or NGINX server by following the official documentation for the respective server.
  2. Reverse proxy the URL https://youdomain.com/spatialstudio to http://localhost:8080/spatialstudio in Apache HTTP or NGINX server configuration file.
    For instance, if your Apache HTTP server is listening on port 80 and 443 and your Spatial Studio Quick Start is running on port 8080 on the same host, then you can simply add the proxy directive to your Apache HTTP server configuration file as shown:
    <VirtualHost *:443>
    ServerName yourdomain.com
    DirectoryIndex index.html index.php
 
    SSLCertificateFile /etc/letsencrypt/live/yourdomain.com/fullchain.pem
    SSLCertificateKeyFile /etc/letsencrypt/live/yourdomain.com/privkey.pem
    Include /etc/letsencrypt/options-ssl-apache.conf
 
    ProxyRequests On
    ProxyPass /spatialstudio http://localhost:8080/spatialstudio
    ProxyPassReverse /spatialstudio http://localhost:8080/spatialstudio
 
</VirtualHost>
 
<VirtualHost *:80>
    ServerName yourdomain.com
    DirectoryIndex index.html index.php
    RewriteEngine on
    RewriteCond %{SERVER_NAME} =yourdomain.com
    RewriteRule ^ https://%{SERVER_NAME}%{REQUEST_URI} [END,NE,R=permanent]
 
    ProxyRequests On
    ProxyPass /spatialstudio http://localhost:8080/spatialstudio
    ProxyPassReverse /spatialstudio http://localhost:8080/spatialstudio
</VirtualHost>
  3. Restart the Apache HTTP or NGINX server.
    You can now securely access Spatial Studio using a url like https://yourdomain.com/spatialstudio.

Parent topic: Using a CA-Signed SSL Certificate in the Quick Start Installation