FishEye SSL configuration

This page describes how to use SSL with FishEye.

On this page:

1. Obtain an SSL certificate

An SSL certificate is required in order for SSL to work in FishEye. There are two ways to obtain one:

Self-signed certificate

Self-signed certificates are useful in cases where you require encryption, but do not need to verify the website's identity. They are commonly used for testing and on internal corporate networks (intranets). If a certificate is not signed by a Certification Authority (CA), users may get prompted that the site is untrusted. They may then have to perform several steps to "accept" the certificate before they can access the site. This usually only occurs the first time the site is accessed.

Self-signed certificates are not supported when creating Application Links from an Altassian OnDemand instance.

Please note, the following approach to create the certificate uses Java's keytool, and has been designed for use with Java 1.6. There are other tools for generating certificates such as openSSL, but the examples will be for keytools, unless the functionality required does not exist in keytools.

To obtain a self-signed certificate:

  1. Run the following command to create a new keystore file in the FishEye install directory (if one does not already exist):
    • Windows:

      "%JAVA_HOME%\bin\keytool" -genkey -keystore \path\to\keystore.kst -alias fisheye -keyalg RSA
    • Unix/Linux:

      $JAVA_HOME/bin/keytool -genkey -keystore /path/to/keystore.kst -alias fisheye -keyalg RSA
  2. When the keytool utility prompts you with 'What is your first and last name?', enter the fully qualified hostname of the server running FishEye/Crucible. Do not enter your first name and last name.

    What is the fully qualified hostname of my server?

    The fully qualified hostname of your server is the name you would type in your web browser, after the http:// section, to access a conventional website. When the client web browser examines the certificate, it checks this field to make sure it matches the hostname. If it does not, the browser may prevent access to the site and will at least generate messages saying that there is a mismatch. An example of a qualified hostname is: support.atlassian.com

  3. When the keytool utility prompts you to enter the keystore password and key password, enter your desired passwords. You must also specify these passwords in the FishEye/Crucible web admin (recommended) or specify these passwords directly in your config.xml in the corresponding attributes (see Configure FishEye/Crucible SSL below).

    <web-server context="/crucible" 
      site-url="http://localhost:6060/crucible/">
    <http bind=":6060"/>
    <ssl bind=":6443" keystore="/path/to/keystore.kst" keystore-password="password123" 
      truststore="/path/to/keystore.kst" truststore-password="password123"/>
    </web-server>
  4. You now have the minimal requirements to run SSL in FishEye. Next, configure FishEye/Crucible to use SSL as described in the Configure FishEye/Crucible SSL section below.

Certificate authority certificate

Digital Certificates issued by trusted 3rd party Certification Authorities (CAs) provide verification of the identity of your website. Many CAs simply verify the domain name and issue the certificate. Other CAs such as VeriSign also verify the existence of your business, the ownership of your domain name and the authority to whom the certificate application was made, thereby providing a higher standard of identification and authenticity.

A list of CA's can be found here. Some of the most well-known CAs are:

This list is not an endorsement of the given certificate authorities by Atlassian, and is only provided as an example.

To obtain a certificate signed by a CA:

  1. Follow the instructions from the certificate authority you want your certificate signed by. Most CAs have their own instructions for you to follow, e.g. GoDaddy and VeriSign.
  2. If your CA requires a certificate signing request (CSR), use the following command:
    • Windows:

      "%JAVA_HOME%\bin\keytool" -certreq -alias fisheye -keystore \path\to\keystore.kst -file \path\to\fisheye.csr
    • Unix/Linux:

      $JAVA_HOME/bin/keytool -certreq -alias fisheye -keystore /path/to/keystore.kst -file /path/to/fisheye.csr
  3. Ensure that the keystore being used to generate the signing request contains an existing key/cert keypair. If you don't already have a key/cert keypair, follow the steps in Self Signed Certificates to generate a keypair.
  4. If the certificate you receive from the CA is not in a format that keytool understands then the openssl command can be used to convert formats since keytool does not perform any of these conversions. For example, to convert between DER and PEM formats:

    openssl x509 -in certificate.der 
         -inform DER -outform PEM -out certificate.crt

    If you have a key and a certificate in separate files you will need to combine them into a PKCS12 format file for loading into a new keystore.  See these instructions for information on how to do so.

  5. Load the certificate into the keystore, as follows:
    • CA certificate in PEM format:
      • Windows:

        "%JAVA_HOME%\bin\keytool" -import -keystore \path\to\keystore.kst 
             -alias fisheye -file \path\to\certificate.crt 
             -trustcacerts
      • Unix/Linux:

        $JAVA_HOME/bin/keytool -import -keystore /path/to/keystore.kst 
             -alias fisheye -file /path/to/certificate.crt 
             -trustcacerts
    • CA certificate in PKCS12 format:
      • Windows:

        %JAVA_HOME%\bin\keytool -importkeystore 
             -srckeystore \path\to\certificate.pkcs12 
             -srcstoretype PKCS12 -destkeystore \path\to\keystore.kst
      • Unix/Linux:

        $JAVA_HOME/bin/keytool -importkeystore 
             -srckeystore /path/to/certificate.pkcs12 
             -srcstoretype PKCS12 -destkeystore /path/to/keystore.kst
  6. You will now have a keystore file with your certificate in it. Next, configure FishEye/Crucible to use SSL as described in the Configure FishEye/Crucible SSL section below.

If your organization utilizes a wildcard certificate to protect your entire domain you will likely have several files in PKCS#12 format that need to be converted into a Java recognized keystore (JKS). For example, given these four files, use the instructions below to create the keystore:

  • star_yourdomain_com.crt - wildcard domain certificate
  • star_yourdomain_com.key - private key
  • DigiCertCA.crt - intermediate certificate chain
  • TrustedRoot.crt - root certificate
  1. Create a combined PKCS#12 file:

    openssl pkcs12 -export 
    	-in <wildcard domain certificate> -inkey <private key> 
    	-certfile <intermediate certificate chain> 
    	-CAfile <root certificate> -caname root -name jetty -out <p12 output file>

    For example:

    openssl pkcs12 -export -in star_yourdomain_com.crt -inkey star_yourdomain_com.key 
    	-certfile DigiCertCA.crt 
    	-CAfile TrustedRoot.crt -caname root -name jetty -out fecru.p12
  2. Create the JKS file from the PKCS#12 file generated above – use the same password for the both deststorepass and destkeypass:

    keytool -importkeystore 
    	-deststorepass <MY_DESTINATIONSTORE_PASSWORD> -destkeypass <MY_DESTINATIONKEY_PASSWORD> 
    	-destkeystore <keystore file name> -srckeystore <p12 output file> 
    	-srcstoretype PKCS12 -srcstorepass <MY_PKC12_KEYSTORE_PASSWORD> -alias jetty

    For example:

    keytool -importkeystore -deststorepass jks_password -destkeypass jks_password 
    	-destkeystore fecru.jks -srckeystore fecru.p12 
    	-srcstoretype PKCS12 -srcstorepass p12_password -alias jetty

2. Configure FishEye SSL

FishEye requires additional configuration in order to use SSL. This configuration can be done from the web admin as described below (recommended), or added directly into your config.xml. Setting the bind address and the keystore and password field, as described below, will enable SSL in FishEye. You will need to restart your server after updating the settings, for the changes to take effect.

To configure FishEye to use SSL:

  1. Navigate to the FishEye admin area and click Server, under 'Global Settings' (see 'Server Settings' screenshot below).
  2. Click Edit settings in the 'Web Server' section.
  3. Update the following fields (see 'Example SSL Settings' screenshot below):

    Field

    Description

    Example value

    SSL Bind Address

    The SSL port. Most browsers default to 443 as the SSL port for the https protocol.

    On Linux, only root users can bind to ports below 1024. For security reasons, we recommend running FishEye/Crucible as a dedicated, non-root user. To bind to a port lower than 1024, see How Do I Use Port 80 or 443 on My Server as a Non-Root User on Linux for possible workarounds.

    443

    SSL Keystore

    Path to the keystore file (as generated in the steps above). This path can be a relative path - e.g., putting in keystore.kst will mean that the file is in <FishEye install directory>/keystore.kst (or FISHEYE_INST/keystore.kst if it has been set up)

    keystore.kst

    SSL Keystore Password

    The password you used in the above step when creating the keystore file. If you did not set a password, leave this empty. See the passwords section

    SSL Truststore

    Path to the truststore file. May be the same as the keystore. Truststore is a list of trusted CAs. Format is the same as the keystore entry.

    SSL Truststore Password

    The password you used in the above step when creating the truststore file. If you did not set a password, leave this empty. See the passwords section

  4. Restart FishEye.

Screenshots: FishEye server settings (click to view larger images)

3. Remove HTTP Access

If you want your FishEye instance to be accessible via HTTPS only, you must remove the <http bind=":8060"/> tag from config.xml.

Was this helpful?

Thanks for your feedback!

Why was this unhelpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport