Securing Stash with Tomcat using SSL
Redirection noticeThis page will redirect to /display/BitbucketServer/Securing+Bitbucket+Server+with+Tomcat+using+SSL .
This page is intended for administrators setting up Stash for a small team. It describes how to enable HTTPS (HTTP over SSL) access for Tomcat, the webserver distributed with Stash, using a self-signed certificate. You should consider doing this, and making secure access mandatory, if Stash will be internet-facing and usernames, passwords and other proprietary data may be at risk.
If you are setting up a production instance of Stash you should consider using a CA certificate, briefly described below.
There are other network topology options for running Stash, including running Stash behind a reverse proxy. For an overview of some common options, see Proxying and securing Stash.
When Stash is set up following the instructions on this page, access to Stash is direct, and all communication between the user's browser and Stash will be secured using SSL.
- Stash will listen for requests on port 8443. This port can be changed if required.
- The address with which to access Stash, by default, will be https://<computer name>:8443. Change the base URL for Stash if required.
- Any existing links with other applications will need to be reconfigured using this new URL for Stash.
- You can set the context path for Stash if you are running another Atlassian application, or Java web application, at the same hostname and context path as Stash.
- Securing Git operations between the user's computer and Stash is a separate consideration - see Enabling SSH access to Git.
Please note that Atlassian Support will refer SSL-related support to the issuing authority for the certificate. The documentation on this page is for reference only.
1. Generate a self-signed certificate
Self-signed certificates are useful where you require encryption but do not need to verify the website identity. They are commonly used for testing and on internal corporate networks (intranets). If you are setting up a production instance of Stash you should consider using a CA certificate, briefly described below.
Users may receive a warning that the site is untrusted and have to "accept" the certificate before they can access the site. This usually will only occur the first time they access the site.
The following approach to creating a certificate uses Java's keytool. Other tools for generating certificates are available.
To generate a self-signed certificate:
Log in with the user account that Stash will run under, and run the following command:
"%JAVA_HOME%\bin\keytool" -genkey -alias tomcat -keyalg RSA -sigalg SHA256withRSA
|Linux, Mac OS X||
$JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA -sigalg SHA256withRSA
This will create (if it doesn't already exist) a new
.keystore file located in the home directory of the user you used to run the keytool command.
If you used the Stash installer to install Stash as a service on your system, the installer will have created a user account called
atlstash. This account is locked (it cannot be used to log in to the system) and doesn't have a home directory. In this case you need to specify a location for the
.keystore file using the
keystore parameter like this:
"%JAVA_HOME%\bin\keytool" -genkey -alias tomcat -keyalg RSA -sigalg SHA256withRSA -keystore /path/to/keystore/stash.jks
|Linux, Mac OS X||
$JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA -sigalg SHA256withRSA -keystore /path/to/keystore/stash.jks
Note the following:
- When running the keytool command you will be prompted with:
What is your first and last name?
You must enter the fully qualified hostname of the server running Stash. This is the name you would type in your web browser after 'http://' (no port number) to access your Stash installation. The qualified host name should match the base URL you have set in Stash (without the port number).
- The keytool utility will also prompt you for two passwords: the keystore password and the key password for Tomcat.
You must use the same value for both passwords, and the value must be either:
- "changeit", which is the default value Tomcat expects, or
- any other value, but you must also specify it in
<Stash home directory>/shared/server.xmlby adding the following attribute to the
2. Configure HTTPS in Tomcat
To configure HTTPS in Tomcat:
<Stash home directory>/shared/server.xmland, at the bottom, before the
</Service>tag, add this section (or uncomment this if it already exists):
This enables SSL access on port 8443 (the default for HTTPS is 443, but 8443 is used here instead of 443 to avoid conflicts).
If you created the keystore somewhere else on the filesystem, add the
keystoreFileattribute to the connector tag as well:
Comment out the existing Connector directive for port 7990 in
<Stash home directory>/shared/server.xml, so as to disable HTTP access, if you want all access to Stash to make use of HTTPS. That is, comment out this directive:
Alternatively, redirect all requests from the insecure port to the secure one: Redirect HTTP Requests to HTTPS
- Start, or re-start, Stash. You will be able to access Stash at in your browser.
Exporting the self-signed certificate
If Stash will run as the user who ran the
keytool --genkey command, you do not need to export the certificate.
You may need to export the self-signed certificate, so that you can import it into a different keystore, if Stash will not be run as the user executing
keytool --genkey. You can do so with the following command:
"%JAVA_HOME%\bin\keytool" -export -alias tomcat -file file.cer
|Linux, Mac OS X||
$JAVA_HOME/bin/keytool -export -alias tomcat -file file.cer
If you generate the certificate as one user and run Stash as another, you'll need to do the certificate export as the generating user and the import as the target user.
Requesting a CA certificate
Digital certificates that are issued by trusted 3rd party CAs (Certification Authorities) provide verification that your website does indeed represent your company.
First, you will generate a local certificate and create a 'certificate signing request' (CSR) based on that certificate. You then submit the CSR to your chosen certificate authority. The CA will use that CSR to generate a certificate for you.
- Use Java's
keytoolutility to generate a local certificate, as described in the section above.
keytoolutility to generate a CSR, replacing the text
<MY_KEYSTORE_FILENAME>with the path to and file name of the
.keystorefile generated for your local certificate:
"%JAVA_HOME%\bin\keytool" -certreq -keyalg RSA -alias tomcat -file certreq.csr -keystore <MY_KEYSTORE_FILENAME>
Linux, Mac OS X
$JAVA_HOME/bin/keytool -certreq -keyalg RSA -alias tomcat -file certreq.csr -keystore <MY_KEYSTORE_FILENAME>
- Submit the generated file called
certreq.csrto your chosen certificate authority. Refer to the documentation on the CA's website to find out how to do this.
- The CA will send you a certificate.
Import the new certificate into your local keystore. Assuming your certificate is called "file.cer" whether obtained from a CA or self-generated, the following command will add the certificate to the keystore:
"%JAVA_HOME%\bin\keytool" -import -alias tomcat -file file.cer
Linux, Mac OS X
$JAVA_HOME/bin/keytool -import -alias tomcat -file file.cer
Here are some troubleshooting tips if you are using a self-signed key created by keytool, or a CA certificate, as described above.
When you enter "
logs/catalina.out log file. Here are some possible errors with explanations:
SSL + Apache + IE problems
Some people have reported errors when uploading attachments over SSL using Internet Explorer. This is due to an IE bug, and can be fixed in Apache by setting:
Google has plenty more on this.
Can't find the keystore
This indicates that Tomcat cannot find the keystore. The keytool utility creates the keystore as a file called
.keystore in the current user's home directory. For Unix and Linux the home directory is likely to be
/home/<username>. For Windows it is likely to be
Make sure you are running Stash as the same user who created the keystore. If this is not the case, or if you are running Stash on Windows as a service, you will need to specify where the keystore file is in
<Stash home directory>/shared/server.xml. Add the following attribute to the connector tag you uncommented:
You used a different password than "changeit". You must either use "changeit" for both the keystore password and for the key password for Tomcat, or if you want to use a different password, you must specify it using the
keystorePass attribute of the Connector tag, as described above.
Passwords don't match
You specified a different value for the keystore password and the key password for Tomcat. Both passwords must be the same.
If the Keystore has more than one certificate, Tomcat will use the first returned unless otherwise specified in the SSL Connector in
<Stash home directory>/shared/server.xml.
keyAlias attribute to the Connector tag you uncommented, with the relevant alias, for example:
Using Apache Portable Runtime
APR uses a different SSL engine, and you will see an exception like this in your logs:
The reason for this is that the APR Connector uses OpenSSL and cannot use the keystore in the same way. You can rectify this in one of two ways:
Use the Http11Protocol to handle SSL connections
Edit the server.xml so that the SSL Connector tag you just uncommented specifies the Http11Protocol instead of the APR protocol:
Configure the Connector to use the APR protocol
This is only possible if you have PEM encoded certificates and private keys. If you have used OpenSSL to generate your key, then you will have these PEM encoded files - in all other cases contact your certificate provider for assistance.
Enabling client authentication
To enable client authentication in Tomcat, ensure that the value of the
clientAuth attribute in your
Connector element of your Tomcat's
server.xml file is
For more information about
Connector element parameters, please refer to the 'SSL Support' section of the Tomcat 6.0 documentation.
Wrong certificate type
If the certificate from the CA is in PKSC12 format, add the
keystoreType attribute to the SSL Connector in
<Stash home directory>/shared/server.xml.
Certificate chain is incomplete
If the root certificate and intermediary certificate(s) aren't imported into the keystore before the entity/domain certificate, you will see the following error:
Most likely, the CA sent a compressed file containing several certificates. The import order matters so you must import the root certificate first, followed by one or many intermediate certificates, followed lastly by the entity/domain certificate. There are many resources online that provide guidance for certificate installation for Tomcat (Java-based) web servers using keytool.
Was this helpful?
Thanks for your feedback!