Using HTTPS to access TeamCity server

This document describes how to configure various TeamCity server clients to use HTTPS for communicating with the server. We assume that you have already configured HTTPS in your web server. See how to do this for Tomcat here: http://tomcat.apache.org/tomcat-7.0-doc/ssl-howto.html. It's also a common approach to setup a middle server like Apache that will handle HTTPS but will use Tomcat to handle the requests. See also a feature request: TW-12976. When using a proxying server please make sure it is configured How To....

Authenticating with server certificate (HTTPS with no client certificate)

If your certificate is valid (i.e. it was signed by a well known Certificate Authority like Verisign), then TeamCity clients should work with HTTPS without any additional configuration. All you have to do is to use https:// links to the TeamCity server instead of http://.

If your certificate is not valid:

• To enable HTTPS connections from TeamCity Visual Studio plugin and Tray notifier, point your Internet Explorer to the TeamCity server using https:// URL and import the server certificate into the browser. After that Visual Studio Addin and Windows Tray Notifier should be able to connect by HTTPS.

• To enable HTTPS connections from Java clients (TeamCity Agents, IntelliJ IDEA, Eclipse), save server certificate to a file, and then import it into the corresponding Java keystore using keytool program. By default, Java keystore is protected by password: changeit

• For Build Agent, to import certificate, use the following command: keytool -importcert -file <cert file> -keystore <agent installation path>/jre/lib/security/cacerts in case you do not use bundled JRE with agent, use the following command: keytool -importcert -file <cert file> -keystore <agent custom JDK/JRE>/lib/security/cacerts

• For IntelliJ Platform Plugin or Eclipse Plugin: keytool -importcert -file <cert file> -keystore <path to JDK used by IDE>/jre/lib/security/cacerts

Authenticating with the help of client certificate

Importing client certificate If you need to use client certificate to access the TeamCity server via https from IntelliJ IDEA, Eclipse or the agents, you will need to add the certificate to Java keystore and supply the keystore to the JVM used by the IDE.

1. If you have your certificate in p12 file, you can use the following command to convert it to a Java keystore. Make sure you use keytool from JDK 1.6 because earlier versions may not understand p12 format.

keytool -importkeystore -srckeystore <path to your .p12 certificate> -srcstoretype PKCS12 -srcstorepass <password of your p12 certificate> -destkeystore <path to keystore file> -deststorepass <keystore password> -destkeypass <keystore password> -srcalias 1

This commands extracts the certificate with alias "1" from your .p12 file and adds it to Java keystore You should know <path to your .p12 certificate> and <password of your p12 certificate> and you can provide new values for <path to keystore file> and <keystore password>.

Here, keypass should be equal to storepass because only storepass is supplied to JVM and if keypass is different, one may get error: "java.security.NoSuchAlgorithmException: Error constructing implementation (algorithm: Default, provider: SunJSSE, class: com.sun.net.ssl.internal.ssl.DefaultSSLContextImpl)".

Importing root certificate to organize a chain of trust If your certificate is not signed by a trusted authority you will also need to add the root certificate from your certificate chain to a trusted keystore and supply this trusted keystore to JVM.

2. You should first extract the root certificate from your certificate. You can do this from a web browser if you have the certificate installed, or you can do this with OpenSSL tool using the command:

openssl.exe pkcs12 -in <path to your .p12 certificate> -out <path to your certificate in .pem format>

You should know <path to your .p12 certificate> and it's password (to enter it when prompted). You should specify new values for <path to your certificate in .pem format> and for the pem pass phrase when prompted.

3. Then you should extract the root certificate (the root certificate should have the same issuer and subject fields) from the pem file (it has text format) to a separate file. The file should look like:

-----BEGIN CERTIFICATE----- MIIGUjCCBDqgAwIBAgIEAKmKxzANBgkqhkiG9w0BAQQFADBwMRUwEwYDVQQDEwxK ... -----END CERTIFICATE-----

Let's assume it's name is <path to root certificate>.

4. Now import the root certificate to the trusted keystore with the command:

keytool -importcert -trustcacerts -file <path to root certificate> -keystore <path to trust keystore file> -storepass <trust keystore password>

Here you can use new values for <trust keystore path> and <trust keystore password> (or use existing trust keystore).

Starting IDE

Now you need to pass the following parameters to the JVM when running the application:

For IntelliJ IDEA you can add the lines into bin\idea.exe.vmoptions file (one option per line). For the agent, see TeamCity Startup Properties.