Upsource 2018.1 Help

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:

  • 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 TLS in your current Upsource installation

Using the command line, you can switch between the following secure mode configurations:

  • HTTP — default HTTP mode. TLS is disabled
  • HTTPS(keystore) — secure HTTPS mode. TLS is enabled. The private key/certificate data is stored in a keystore file.
  • HTTPS(privateKeyAndCert) — secure HTTPS mode. TLS is enabled. The private key, certificate, and certificate chain(optional) are stored 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 a complete list of the properties for each configuration.

To switch to the HTTP mode:

  1. Stop Upsource: <upsource_home>/bin/upsource.bat stop

  2. Enter the following command:

    <upsource_home>/bin/upsource.bat configure --listen-port=8080 --secure-mode=disable

  3. Start Upsource: <upsource_home>/bin/upsource.bat start

To switch to the HTTPS (keystore) mode:

  1. Create a temporary folder and place the file keystore.jks containing the server's private key and certificate in that folder.

  2. Stop Upsource: <upsource_home>/bin/upsource.bat stop

  3. Run the following command:

    <upsource_home>/bin/upsource.bat configure --listen-port=443 --secure-mode=tls --tls-server-cert-storage-type=keystore --tls-server-cert-folder=<folder with file keystore.jks> --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]

  4. Start Upsource: <upsource_home>/bin/upsource.bat start

To switch to the HTTPS (privateKeyAndCert) mode:

  1. Create a temporary folder (let's call it <certificates_folder>) to store the files with private key, certificate and certificate chain (if any).

  2. Place the RSA private key (in the PEM format) into file <certificates_folder>/privateKey.pem.

  3. Place the server certificate (in the PEM format) associated with the private key into the file <certificates_folder>/certificate.crt.

  4. If you have a certificate chain for signing the server's certificate (in the PEM format), place it into the file <certificates_folder>/certificateChain.crt.

  5. Stop Upsource: <upsource_home>/bin/upsource.bat stop

  6. Run the following command:

    <upsource_home>/bin/upsource.bat configure --listen-port=443 --secure-mode=tls --tls-server-cert-storage-type=privateKeyAndCert --tls-server-cert-folder=<certificates_folder> --tls-redirect-from-http=<[true|false]> [--tls-redirect-from-http-listen-port=8080]

  7. 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, add the parameters tls-redirect-from-http=true and tls-redirect-from-http-listen-port=<your redirect port number> to 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:

  1. Disable your third-party TLS-terminating proxy.
  2. 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:

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

Configuraton parameters

HTTP

Property Value Description
secure-mode disable The default value of the property. TLS is disabled by default.
listen-port The port on which Upsource listens to the HTTP traffic.

HTTPS (common properties)

Property Value Description
secure-mode tls TLS is enabled
tls-server-cert-storage-type TLS is enabled Defines the format (storage type) of a server certificate. See descriptions of each storage type below.
tls-redirect-from-http true or false. The default value is 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.
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

Specify the directory that contains server certificate files to be applied to Upsource. The directory should contain the file keystore.jks If you are using the keystore format (the property tls-server-cert-storage-type is set to keystore in that case). The directory should contain the files privateKey.pem, certificate.crt and certificateChain.crt (if any) if you are using the PEM format (the property tls-server-cert-storage-type is set to privateKeyAndCert in that case).

tls-server-cert-checksum This is a checksum of provided server certificate files. Those files are re-imported on Upsource startup only if the actual checksum differs from the stored one. Normally, this property is calculated automatically and should not be changed manually. However when changed to any value different from the current one it forces re-import of the server certificate on Upsource startup.

HTTPS (keystore - additional settings)

Property Value Description
tls-server-cert-storage-type keystore

Use this property if your private key/certificate data is stored in a generated keystore file. In this mode, the server's private key/certificate pair will be derived from the file internal/cert/keystore/keystore.jks located in the conf directory. The keystore file is saved in the JKS format.

tls-server-cert-keystore-password Keystore integrity password
tls-server-cert-keystore-key-alias Alias that is associated with the private key/certificate entry in the keystore.
tls-server-cert-keystore-key-password Password that protects your server's private key entry in the keystore.

HTTPS (privateKeyAndCert - additional settings)

Property Value Description
tls-server-cert-storage-type privateKeyAndCert

In this mode the server's private key/certificate pair is taken from the files internal/cert/privateKeyAndCert/privateKey.pem, internal/cert/privateKeyAndCert/certificate.crt located in the conf directory. Also, a certificate chain can be defined in the file internal/cert/privateKeyAndCert/certificateChain.crt. All files are assumed to be stored in the PEM format. Private key is an RSA key encoded into base64.

Last modified: 16 May 2018