Configuring TLS

There are several ways to set up an encrypted HTTPS connection with TLS (SSL) between your Upsource server and its clients.

Use Upsource's built-in TLS. You can configure Upsource to run in the HTTPS mode:
- from Configuration Wizard, during the initial Upsource installation or upgrade
- from the command line, enabling (and disabling as well) HTTPS for your existing Upsource installation
Use a third-party TLS-terminating proxy server. This option is preferable when you have to run Upsource behind a proxy server for other reasons than encryption. See Proxy configuration for details.

You can switch from a third-party TLS-terminating proxy to the Upsource built-in TLS and vice-versa at any time regardless of your current settings.

Configuring built-in TLS in your current Upsource installation

Using the command line, you can switch between the HTTP and HTTPS modes.

HTTP— default HTTP mode. Built-in TLS is disabled.

To enable the secure HTTPS mode, you need to have a private key and certificate which you provide to Upsource either in the form of a keystore or separate files, using a corresponding configuration option:

HTTPS (using keystore)— secure HTTPS mode. Built-in TLS is enabled. Use this configuration if you provide private key/certificate data in a keystore file in the JKS or PKCS#12 format.
HTTPS (using private key and certificate)— secure HTTPS mode. Built-in TLS is enabled. Use this configuration if you provide the private key, certificate, and certificate chain (optional) data in separate files in the PEM format.

To switch to a desired mode, you need to stop Upsource and run the configure command defining all the properties required for the configuration of your choice. See below for detailed instructions and complete lists of properties for each configuration.

Switch to the HTTP mode—disable built-in TLS

Stop Upsource: <upsource_home>/bin/upsource.bat stop
Enter the following command:
<upsource_home>/bin/upsource.bat configure --listen-port=8080 --base-url=<new base URL> --secure-mode=disable
Start Upsource: <upsource_home>/bin/upsource.bat start

Switch to the HTTPS mode with keystore

Prepare the keystore file containing the server's private key and certificate. The certificate data it contains can be in JKS or PKCS#12 format, but the file name should be keystore.jks in order for Upsource to accept it. If it's not—rename the file to keystore.jks.
Create a temporary folder and place the file keystore.jks containing the server's private key and certificate into that folder.
Stop Upsource: <upsource_home>/bin/upsource.bat stop
Run the following command:
<upsource_home>/bin/upsource.bat configure \ --listen-port=443 \ --base-url=<new base URL> \ --secure-mode=tls \ --tls-server-cert-keystore-file=<path-to-keystore> \ --tls-server-cert-keystore-password=<keystore password> \ --tls-server-cert-keystore-key-alias=<private key entry alias> \ --tls-server-cert-keystore-key-password=<private key entry password> \ --tls-redirect-from-http=<[true|false]> [--tls-redirect-from-http-listen-port=8080]
If your keystore file's format is PKCS#12:
- The value of the parameter --tls-server-cert-keystore-key-alias should be friendlyName or a serial number of the bag with the server certificate. (Bag numbering starts with 1, so if there is only one bag in the keystore, then its serial number is 1.)
- Skip the parameter --tls-server-cert-keystore-key-password=<private key entry password> if the private key entry is not protected with a password.
Start Upsource: <upsource_home>/bin/upsource.bat start

Switch to the HTTPS mode with separate private key and certificate

Stop Upsource: <upsource_home>/bin/upsource.bat stop
Run the following command:
<upsource_home>/bin/upsource.bat configure \ --listen-port=443 \ --base-url=<new base URL> \ --secure-mode=tls \ --tls-server-cert-key-file=<path-to-private-key-file> \ --tls-server-cert-file=<path-to-certificate-file> \ [--tls-server-cert-chain-file=<path-to-certificate-chain-file>] \ --tls-redirect-from-http=<[true|false]> \ [--tls-redirect-from-http-listen-port=8080] \
- If the private key is encrypted, add this property to the command: --tls-server-cert-private-key-passphrase=<your passphrase>
- If you want to define relative paths to the certificate files, use tls-server-cert-key-file, tls-server-cert-file, and tls-server-cert-chain-file. Set the value for the additional tls-server-cert-folder property with the absolute path to the directory. Relative paths are resolved against the specified absolute path.
- If the server base URL changes as a result of switching to HTTPS mode, use the --base-url=<new base URL> parameter to set this value.
Start Upsource: <upsource_home>/bin/upsource.bat start

Redirecting HTTP traffic

If you are going to use a secure HTTPS mode, you can optionally set up a Redirect listen port— a non-secure port that will receive all HTTP requests and redirect them to the secure listen port. To do so, set the parameter tls-redirect-from-http=true and add tls-redirect-from-http-listen-port=<your redirect port number> to the configure command.

If you're already running your server in the HTTPS mode, you can enable or disable the Redirect listen port at any time by running the configure command with the aforementioned properties — no need to include other properties in the command.

Make sure to stop Upsource before you run the configure command.

Switching between a third-party TLS-terminating proxy and Upsource's built-in TLS

Switching from a third-party TLS-terminating proxy to Upsource's built-in TLS or vice-versa requires no specific procedures and can be done with the following steps:

To switch from a third-party TLS-terminating proxy to the Upsource's built-in TLS:

Disable your third-party TLS-terminating proxy.
Enable the Upsource's built-in TLS as described above, choosing either of the two available certificate storage options: HTTPS (keystore) or HTTPS (privateKeyAndCert).

To switch from the Upsource's built-in TLS to a third-party TLS-terminating proxy:

Switch Upsource to the HTTP mode as described above.
Configure and enable a third-party proxy.

Configuration parameters

The following table provides a list of parameters that you can use to configure built-in TLS.

Property	Value	Description
secure-mode	`disable` \| `tls`	The connection mode that is applied to the Upsource server. This property supports the following values: `disable`— TLS is disabled. This is the default value for this property. `tls`— TLS is enabled.
listen-port		The port on which Upsource listens to HTTP traffic.
base-url		The URL that end users request to access your Upsource installation. For example, `https://Upsource.mydomain.com`. When the value for the `secure-mode` property is `tls` or your Upsource installation is secured behind an SSL-terminating reverse proxy server, the URL should begin with `https`. Otherwise (when running Upsource using plain HTTP), the URL begins with `http`.
tls-redirect-from-http	`true` \| `false`	Set to true, to enable an additional port (defined by property `tls-redirect-from-http-listen-port`) to accept unencrypted HTTP traffic and redirect it to a secure port defined by the property `listen-port`. The default value is `false`.
tls-redirect-from-http-listen-port		Specify an additional port to accept unencrypted HTTP traffic and redirect it to a secure port defined by the property `listen-port` (to enable this port, set the property `tls-redirect-from-http` to `true` ).
tls-server-cert-folder		An (optional) absolute path to resolve relative paths defined by other command line parameters, when present. Relative paths to server certificate files that are specified in other properties are resolved against this directory. The properties that can reference relative paths are: `tls-server-cert-key-file` `tls-server-cert-file` `tls-server-cert-chain-file` `tls-server-cert-keystore-file`
tls-server-cert-keystore-file		The location of a keystore file in either JKS or PKCS #12 format.
tls-server-cert-keystore-password		Keystore integrity password
tls-server-cert-keystore-key-alias		The alias of the entry in the keystore that contains the server certificate and the private key. If your keystore uses the PKCS #12 format, follow these guidelines: Use the value that is stored as the `friendlyName` in the keystore. If the private key and certificate pair was not marked with a `friendlyName` during generation, use this parameter to provide the sequential number of this pair in the keystore. For a keystore that only contains one certificate and private key pair, set the value to `1`.
tls-server-cert-keystore-key-password		Password that protects your server's private key entry in the keystore.
tls-server-cert-key-file		The location of a private key (PKCS #1 or PKCS #8) file, stored in PEM format.
tls-server-cert-file		The location of a certificate file, stored in PEM format.
tls-server-cert-chain-file		The (optional) location of a file that contains the certificate chain, stored in PEM format.
tls-server-cert-private-key-passphrase	string	If you use an encrypted private key, then use this property to provide the passphrase that was used for encryption. Supported for both PKCS #1 and PKCS #8 formats.

Last modified: 02 April 2021