YouTrack Standalone 2017.3 Help

SSL Certificates

YouTrack lets you import a trusted SSL certificate from an external service. These certificates identify the external service as a trusted source and let you establish a secure connection between YouTrack and the third-party server.

You can also import a keystore to YouTrack. The keystore identifies YouTrack as a client when it tries to connect to a third party. Keystores are managed on a separate page in YouTrack. For more information, see SSL Keystores.

When you integrate other applications with your YouTrack server over SSL, you need to import the SSL certificates that verify the identity of the connected service. Trusted SSL certificates are commonly used for the following features:

  • When you enable SMTP notifications or set up a mailbox integration using a secure mail server, you may need to import the certificate for your mail server. When a certificate is signed by a well-known authority, the public key and certificate are already stored in the web browser. If the certificate for your mail server is self-signed, you need to import the certificate and public key to establish a secure connection.

  • If you connect to a hosted VCS server, you need to import the certificate for the private VCS server.

  • If you enable a GitHub auth module or an LDAP auth module over SSL, you need to import the certificate for your authentication server.

To access trusted certificates that have been imported to your YouTrack server, select SSL Certificates in the Server Settings area of the Administration menu.

trustedSSLCertificates thumbnail

The following controls are available on this page:

Control

Description

Import Trusted Certificate

Click to import a certificate from your local directory.

View Certificate Properties

Click the name of a certificate to view its properties. Here, you can also edit the name that is assigned to the certificate.

Delete

Click the delete icon to remove a certificate from YouTrack. Use this option to remove certificates that are expired or no longer in use.

Self-signed Certificates

YouTrack lets you import and trust a self-signed certificates. In general, you should use a self-signed certificate only for testing or on an internal corporate network where all of the traffic between services is protected by a firewall and reverse proxy server.

Untrusted Certificates

When YouTrack tries to establish a connection with a third-party server for which it does not have a certificate, the connection is not established. This situation occurs when a new certificate has been issued for the service that has not been imported to YouTrack. YouTrack stores this certificate in an untrusted state. If you recognize the certificate source and want to re-establish the connection, you can change the status of the certificate to trusted.

Import a Trusted SSL Certificate

When you want to establish a secure connection between YouTrack and a third-party service, you need to import the SSL certificate that contains the public key of the third party. You can generate the key and certificate pair using an application like the Java keytool or PuTTY. If the application is accessible from a web browser, you can view and copy the certificate from your browser window.

YouTrack accepts binary DER encoded certificates. These files use the .der, .cer, and .crt extensions.

To import a trusted SSL certificate:

  1. In the Server Settings area of the Administration menu, select SSL Certificates

  2. Click the Import trusted certificate button.

  3. In the Import Trusted Certificate dialog, enter a name for the certificate.

  4. Click the Choose file button and select the certificate file from your local directory.

    sslCertificatesAddDialog thumbnail

  5. Click the Import button.

    • The certificate is added to YouTrack.

Import a Hub Certificate

All of the SSL certificates that you import into YouTrack are actually stored in Hub. When you update the SSL certificate in an external Hub service, YouTrack no longer recognizes Hub as a trusted source.

If a trusted connection to Hub cannot be established, the YouTrack server fails to start. When you try to run YouTrack, you encounter a Server SSL certificate not trusted error. To resolve this issue, import your updated certificate into the keystore.jks file manually.

To import a Hub certificate into the keystore for YouTrack:

  1. Download the SSL certificate for the Hub service in your web browser (instructions for Google Chrome):

    • Enter the URL for the external Hub service in the address bar. For example, https://myhub.com.

    • Click the lock icon in the address bar.

    • Click the Details link.

      • The Security Overview pane opens to the Security tab.

    • Click the View certificate button.

      • The Certificate dialog opens.

    • Select the Details tab.

    • Click the Copy to File button.

      • The Certificate Export Wizard opens.

    • Click the Next button.

    • Select the Base-64 encoded X.509 (.CER) option and click the Next button.

    • Enter a name for the certificate (for example, myhub.com.cer) and click the Next button.

    • Click the Finish button.

  2. Use the keytool certificate management utility to create a keystore.jks file.

    • Create a new password for the keystore (it must be at least 6 characters).

    • Confirm that you trust the certificate.

    Use the following commands to create the keystore:

    keytool -import -trustcacerts -file myhub.com.cer -alias myhub.com -keystore keystore.jks Enter keystore password: <keystore password> Re-enter new password: <keystore password> ... <Certificate info will be shown> ... Trust this certificate? [no]: yes Certificate was added to keystore
  3. Copy the keystore.jks file to <YouTrack home directory>/conf/internal/keystore.jks.
    • For MSI installations, the <YouTrack home directory> is %programdata%\JetBrains\YouTrack\. To locate this directory:

      • Open a Command Prompt window.

      • Enter echo %programdata%.

    • For ZIP installations, the <YouTrack home directory> is the location where the ZIP distribution was unpacked during installation.

  4. Set the following properties in the <YouTrack home directory>/conf/internal/bundle.properties file:
    • additional-keystore-path=<YouTrack home directory>/conf/internal/keystore.jks
    • additional-keystore-password=<keystore password from step 2>
Last modified: 7 March 2019
StatisticsSSL Keystores