# How to Configure HTTPS (TLS/SSL)

Teamscale can optionally provide HTTPS communication, 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.

# 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. 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

# 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 (i. e. 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.

Slashes under Windows

Under Windows, please use forward slashes (/) instead of backslashes for paths configured in teamscale.properties. A backslash is interpreted as an escape character.