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
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
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.
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.
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 -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.
# 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 .
# TODO: private key file for the input certificate.
# Password of the entry in the new keystore (has to be set in Teamscale config file)
# Alias of the entry in the new keystore
if [ -f keystore.jks ]; then
echo "Found a keystore.jks file. Please remove it before starting this script (we will generate this keystore)."
# 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)"
# Assume that this is a real Unix system
echo "Set the following properties in the file config/teamscale.properties in your Teamscale installation:"
echo "Optionally, you can set server.port=0 to disable HTTP access."