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
Enter the following command:<upsource_home>/bin/upsource.bat configure --listen-port=8080 --base-url=<new base URL> --secure-mode=disable
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.
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-aliasshould 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.
Switch to the HTTPS mode with separate private key and certificate
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:
If you want to define relative paths to the certificate files, use
tls-server-cert-chain-file. Set the value for the additional
tls-server-cert-folderproperty 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.
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
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
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.
The following table provides a list of parameters that you can use to configure built-in TLS.
The connection mode that is applied to the Upsource server. This property supports the following values:
|listen-port||The port on which Upsource listens to HTTP traffic.|
The URL that end users request to access your Upsource installation. For example,
Set to true, to enable an additional port (defined by property
The default value is
|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 |
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-keystore-file||The location of a keystore file in either JKS or PKCS #12 format.|
|tls-server-cert-keystore-password||Keystore integrity password|
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:
|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.|