How to Configure HTTPS (TLS/SSL) Access to the Teamscale Server

Teamscale can optionally provide HTTPS access to the Teamscale Server, either in addition to HTTP or exclusively. The enablement of both can be controlled via the settings server.port and https.port in the server configuration.

HTTPS-Termination using a Reverse Proxy

Instead of configuring Teamscale itself to terminate the HTTPS connection, a reverse proxy like NGINX or Apache can be used instead.

Depending on the environment the configuration of a reverse proxy may be easier and less error-prone. Please refer to this documentation page: How to Integrate with Apache Webserver or NGINX

Connecting to External Servers via HTTPS

How to access external servers (e.g., GitLab or Jira) that allow only HTTPS communication from Teamscale is described in a different documentation page: Connecting to External Servers via HTTPS

• SSL Keys and Certificate
• Converting Certificate to PKCS 12 Format
• Creating a Keystore
• Adapting teamscale.properties
• Shell Script for Generation of a Keystore

SSL Keys and Certificate

To set up HTTPS communication for Teamscale, a pair of private key and certificate is required. Your company may already have a certificate and key available or a new pair has to be generated. Please consult your IT operations team for potential regulations in your company. Technically, you also have the option of generating a self-signed certificate (not recommended for security reasons).

Teamscale requires the private key and certificate to be stored in the Java Keystore format (.jks). Prior to importing a certificate in a Java keystore, the certificate has to be converted to the PKCS 12 format.

Converting Certificate to PKCS 12 Format

Conversion under Windows

In case you are using Windows and have the certificate stored in the Certificate Management of the operating system, you can directly export the certificate and private key in the PKCS 12 format using the Certificate Export Wizard. You can then skip the conversion in the next paragraph and continue with the creation of the Java keystore.

In case the certificate and key was created with OpenSSL, the conversion can be done using the OpenSSL command line tool. When working on Windows, note that OpenSSL comes per default with the Git Bash for Windows.

TIP

If your certificate comes as .pfx file, simply renaming to .p12 can work. You can then continue and create a keystore.

Assuming your certificate is available in a file myhost.crt and your private key in a file myhost.key , the following command will combine them and save them a file myhost.p12 converting them to the PKCS12 format which is compatible with the Java keystore (you will be asked for an export password):

openssl pkcs12 -export -in myhost.crt -inkey myhost.key -out myhost.p12

Creating a Keystore

After this, you can create a new Java keystore and import the certificate/key pair into the newly created store. This can be done with the keytool command line tool that is part of Java (located in the bin folder of the Java installation). The following command will create a new file myhost.jks containing a Java keystore with both the certificate and private key. You will be asked for import and export passwords.

Use same Password

Please ensure to use the same password used previously for protecting the private key also for the keystore.

keytool -importkeystore -srckeystore myhost.p12 -srcstoretype pkcs12 -destkeystore myhost.jks

Use same Java version

Please ensure to use the same Java version for creating the keystore and running Teamscale. Otherwise, Teamscale may be not able to read the provided keystore, which will result in a failure during startup.

Adapting teamscale.properties

To enable HTTPS for Teamscale, all configuration settings in teamscale.properties starting with https. have to be properly configured. Make sure to properly configure the path to the newly generated Java keystore, its password as well as the certificate alias.

If you do not know the alias of your certificate, you can look it up with a keytool command:

keytool -list -keystore myhost.jks

If everything was properly configured, Teamscale will accept HTTPS connections on the HTTPS port specified in the Teamscale settings (https.port). All connections to the configured HTTP port (the value for server.port or the default of 8080) will be forwarded to the HTTPS port. If the HTTP port is set to 0, HTTP is disabled and only HTTPS connections are accepted.

Shell Script for Generation of a Keystore

This is a shell script (Bash script) that executes the steps described on this page. On Windows systems, it can be executed in the Git Bash for Windows. It furthermore requires that the Java keytool executable is available (the keytool is part of the Java Runtime Environment JRE).

Please note that the script needs to be adapted before using it: the names of the input files have to be changed.

#! /bin/bash

# TODO: input certificate file. This will be the certificate that the Teamscale server uses to identify itself.
# For example, if Teamscale is accessed via the URL teamscale.company.org, then this must be the certificate for teamscale.company.org .
CERT_FILE=MyTeamscaleServer.crt
# TODO: private key file for the input certificate.
CERT_KEY_FILE=MyTeamscaleServer.key

# Password of the entry in the new keystore (has to be set in Teamscale config file)
STORE_PASSWORD=12345678
# Alias of the entry in the new keystore
CERT_ALIAS=teamscalehostcert

if [ -f keystore.jks ]; then
    echo "Found a keystore.jks file. Please remove it before starting this script (we will generate this keystore)."
    echo "Aborting."
    exit 1
fi

# Generate a new intermediate.p12 certificate in pkcs12 format. This contains the certificate AND the private key
# N.B.: You may run into issues with this, if you do not have enough permissions such that openssl can access some system files.
openssl pkcs12 -export -in $CERT_FILE -inkey $CERT_KEY_FILE -out intermediate.p12 -passout pass:$STORE_PASSWORD -name $CERT_ALIAS
# Import the certificate (with private key) into a new Java keystore
keytool -importkeystore -srckeystore intermediate.p12 -srcstorepass $storePassword -srcstoretype pkcs12 -destkeystore keystore.jks -deststorepass $STORE_PASSWORD -deststoretype pkcs12
# List the contents of the new keystore
keytool -list -keystore keystore.jks -storepass $STORE_PASSWORD

# Determine the path of the new keystore file
if hash cygpath 2>/dev/null; then
    # Assume that this is a Windows system (running in Cygwin/Git bash here)
    ABSOLUTE_PATH_TO_KEYSTORE="$(cygpath -w --absolute keystore.jks)"
else
    # Assume that this is a real Unix system
    ABSOLUTE_PATH_TO_KEYSTORE="$(pwd)/keystore.jks"
fi

echo "Set the following properties in the file config/teamscale.properties in your Teamscale installation:"
echo
echo "https.port=443"
echo "https.keystore-path=$ABSOLUTE_PATH_TO_KEYSTORE"
echo "https.keystore-password=$STORE_PASSWORD"
echo "https.certificate-alias=$CERT_ALIAS"
echo
echo "Optionally, you can set server.port=0 to disable HTTP access."