If you use self-signed certificates

On this page

Still need help?

The Atlassian Community is here for you.

Ask the community

Atlassian applications allow the use of SSL within our products, however Atlassian Support does not provide assistance for configuring it. Consequently, Atlassian cannot guarantee providing any support for it.

  • If assistance with conversions of certificates is required, please consult with the vendor who provided the certificate.
  • If assistance with configuration is required, please raise a question on Atlassian Answers.

If you're on a Bitbucket version 8.8 or above, you can configure your webhook to skip certificate verification.

If you're on a Bitbucket version lower than 8.8, in order to trust a self-signed certificate, the public certificate need to be imported in the Java keystore that Bitbucket Data Center and Server uses. In this example, it is *.atlassian.com, and we cover how to install it below.

If you're unable to install Portecle on the server or prefer the command line please see our Command Line Installation section below.

Obtain and import the endpoint's public certificate

  1. Download and install the Portecle app onto the server that runs Bitbucket.
    (warning) This is a third-party application and not supported by Atlassian.
  2. Ensure the <JAVA_HOME> variable is pointing to the same version of Java that Bitbucket uses. 
    (info) If running on a Linux/UNIX server, X11 will need to be forwarded when connecting to the server (so you can use the GUI), as below:

    ssh -X user@server
  3. Select the Examine menu and then click Examine SSL/TLS Connection:
  4. Enter the SSL Host and Port of the target system:
  5. Wait for it to load, then select the public certificate and click on PEM:
  6. Export the certificate and save it.
  7. Go back to the main screen and select the Open an existing keystore from disk option, select cacerts (for example $JAVA_HOME/lib/security/cacerts ) then enter the password (the default is changeit).
  8. Select the Import a trusted certificate into the loaded keystore button:
  9. Select the certificate that was saved in step 6 and confirm that you trust it, giving it an appropriate alias (e.g.: confluence).
    1. You may hit this error: 
    2. If so, hit OK, and then accept the certificate as trusted.
  10. Save the Key Store to disk:
  11. Restart Bitbucket.
  12. Test that you can connect to the host. 

Command Line Installation

  1. Fetch the certificate, replacing google.com with the FQDN of the server Bitbucket is attempting to connect to:
    Unix:

    openssl s_client -connect google.com:443 < /dev/null | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > public.crt

    Windows:

    openssl s_client -connect google.com:443 < NUL | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > public.crt

    (info) The command above will only be executed if you have Sed for Windows as well as  OpenSSL installed on your environment. If you don't have Sed or OpenSSL or you don't want to install it, use the instructions below as an alternative. Issue the following command:

    openssl s_client -connect google.com:443

    Save the output to a file called  public.cert.  Edit the the public.cert file so it contains only what is between the BEGIN CERTIFCATE and END CERTIFICATElines. This is how your file should look like after you edited it:

    -----BEGIN CERTIFICATE-----
    < Certificate content as fetched by the command line. 
    Don't change this content, only remove what is before 
    and after the BEGIN CERTIFICATE and END CERTIFICATE. 
    That's what your Sed command is doing for you :-) >
    -----END CERTIFICATE-----
  • Import the certificate:

    <JAVA_HOME>/bin/keytool -import -alias <server_name> -keystore <JAVA_HOME>/jre/lib/security/cacerts -file public.crt

Alternative KeyStore Locations

Java will normally use a system-wide keystore in $JAVA_HOME/jre/lib/security/cacerts, but it is possible to use a different keystore by specifying a parameter, -Djavax.net.ssl.trustStore=/path/to/keystore, where '/path/to/keystore' is the absolute file path of the alternative keystore.

However, setting this is not recommended because if Java is told to use a custom keystore (eg. containing a self-signed certificate), then Java will not have access to the root certificates of signing authorities found in $JAVA_HOME/jre/lib/security/cacerts, and accessing most CA-signed SSL sites will fail. It is better to add new certificates (eg. self-signed) to the system-wide keystore (as above).

Debugging

Problems are typically one of two forms:

  • The certificate was installed into the incorrect keystore.
  • The keystore does not contain the certificate of the SSL service you're connecting to.
Last modified on Apr 26, 2023

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.