Configuring Crowd to Work with SSL
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.
Why should you enable HTTPS access to Crowd?
When web applications are accessed across the internet, there is always the possibility of usernames and passwords being intercepted by intermediaries. HTTPS is a good way to safeguard your Crowd data and user logins from being intercepted and read by outsiders.
On this page:
Using Crowd over HTTPS
The process of enabling HTTPS access is specific to each application server, but specifying which pages require protection is generic. Below we describe the process for Tomcat, the application server bundled with Crowd.
Step 1: Enable Tomcat HTTPS Access
<crowd installation>/apache-tomcat/conf/server.xml, and at the bottom before the
</Service> tag (not to be confused with the
</Server> tag!), add this section (or uncomment it if it's already there):
<Connector port="8443" protocol="org.apache.coyote.http11.Http11Protocol"
maxThreads="150" SSLEnabled="true" scheme="https" secure="true"
This enables SSL access on port 8443. (The default for HTTPS is 443, but just as Tomcat uses 8080 instead of 80 to avoid conflicts, 8443 is used instead of 443 here). You may need to change the values of
keyPass as appropriate for your certificates and set-up.
Step 2: Create or Import your SSL Key (Self-Signed or CA-Issued)
You can either create a self-signed SSL key or import a certificate issued by a Certificate Authority (CA). We describe both methods below.
Creating a Self-Signed SSL Key
You can create a self-signed key for testing purposes with one of the following commands:
%JAVA_HOME%\bin\keytool -genkey -alias tomcat -keyalg RSA (Windows)
$JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA (Unix / Mac OS)
When you are asked for your "first and last name", instead supply the hostname for the Crowd server, e.g.:
What is your first and last name?
The keytool utility will prompt you for two passwords: the keystore password and the key password for Tomcat. You can use either of:
- 'changeit' (this is the default value Tomcat expects), or
Any value other than 'changeit', and you must also specify it as the value of
You will then need to import your certificate into the truststore:
First, export the key you generated to a file:
$JAVA_HOME/bin/keytool -export -alias tomcat -file tomcat.cert
Import the key into the JRE keystore (you will need permission to write to the keystore specified, and may need elevated privileges):
$JAVA_HOME/bin/keytool -import -alias tomcat -file tomcat.cert -keystore $JAVA_HOME/jre/lib/security/cacerts
For information on adding a key pair issued by a Certificate Authority (CA), refer to the Apache Tomcat documentation.
Importing a CA-Issued Certificate
When using certificates issued by a Certificate Authority, you also need to import the certificate using the
keytool command, rather than generating a self-signed key.
Here is an example of the command:
keytool -import -alias tomcat -file certificate.cer -keystore some/path/to/file -storepass something.secure
-file is your certificate and the
-keystore is an optional destination, but it will guarantee that you know where your keystore is. By default, the keystore is placed in your user home directory. You can refer to the following Oracle documentation for more information on the keytool:
Now edit the
server.xml file as described in section 'Edit the Tomcat Configuration File' in the Apache Tomcat documentation. Basically, you'll need to add the
keystorePass to the SSL Connector definition to match your keystore settings.
Now start (or restart) your Crowd instance. You should be able to access Crowd at this URL:
Here are some troubleshooting tips if you are using a self-signed key created by keytool, as described above.
When you enter 'https://localhost:8443' in your browser, if you get a message such as 'Cannot establish a connection to the server at localhost:8443', look for error messages in your
logs/catalina.out log file. Here are some possible errors with explanations:
Can't Find the Keystore
java.io.FileNotFoundException: /home/<username>/.keystore (No such file or directory)
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/Linux the home directory is likely to be
/home/<username>. For Windows it is likely to be
C:\Documents And Settings\<UserName>.
Make sure you are running Crowd as the same user who created the keystore. If this is not the case, or if you are running Crowd on Windows as a service, you will need to specify where the keystore file is in
conf/server.xml. Add the following attribute to the connector tag you uncommented:
keystoreFile="<location of keystore file>"
java.io.IOException: Keystore was tampered with, or password was incorrect
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
java.io.IOException: Cannot recover key
You specified a different value for the keystore password and the key password for Tomcat. Both passwords must be the same.
To find out more about the options that Tomcat offers, please take a look at the Apache Tomcat documentation.
Using SSL between an LDAP Server and Crowd
Microsoft Active Directory Connector using SSL Certificate
Please refer to Configuring an SSL Certificate for Microsoft Active Directory.
Other LDAP Servers
For other LDAP servers, please consult your LDAP server documentation.
On the Crowd side, when configuring the connector properties, you will have to simply check the 'Secure SSL' box and make sure you use the correct port in the 'URL' field (usually 636).