Documentation for Crowd 2.9. Documentation for earlier versions of Crowd is available too.

Skip to end of metadata
Go to start of metadata

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

Edit <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"
           clientAuth="false" sslProtocol="TLS"
           keystoreFile="${user.home}/.keystore" keystorePass="changeit"
           keyAlias="tomcat" keyPass="changeit"/> 

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 keystoreFilekeystorePass and 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?
  [Unknown]:  localhost

The keytool utility will prompt you for two passwords: the keystore password and the key password for Tomcat. You can use either of:

  1. 'changeit' (this is the default value Tomcat expects), or
  2. Any value other than 'changeit', and you must also specify it as the value of keystorePass in conf/server.xml.

You will then need to import your certificate into the truststore:

  1. First, export the key you generated to a file:

    $JAVA_HOME/bin/keytool -export -alias tomcat -file tomcat.cert

     

     

  2. 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

The -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 keystoreFile and keystorePass to the SSL Connector definition to match your keystore settings.

Step 3: Modify crowd.properties

Modify your <Crowd-Home-Directory>/crowd.properties file to reflect your new SSL settings. For example:

#Wed Apr 09 12:36:21 EST 2008
session.lastvalidation=session.lastvalidation
session.isauthenticated=session.isauthenticated
application.password=password
application.name=crowd
session.validationinterval=0
crowd.server.url=https\://localhost\:8443/crowd/services/
session.tokenkey=session.tokenkey
application.login.url=https\://localhost\:8443/crowd/console/

When changing crowd to use ssl after going through web based set up, <Crowd-Home-Directory>/crowd.properties, <Crowd-install>/build.properties, and <Crowd-install>/client/conf/crowd.properties need to be updated with https\://host:port/... Just updating crowd.properties is not enough. The symptom is unable to log in from the web interface, and the logs show xfire unable to connect to the web service.

 

Now start (or restart) your Crowd instance. You should be able to access Crowd at this URL:

https://localhost:8443/crowd/console

Troubleshooting

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>"

Incorrect Password

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).

RELATED TOPICS

Configuring an SSL Certificate for Microsoft Active Directory
Configuring Crowd

21 Comments

  1. Anonymous

    If using tomcat6 as a service.... setenv.bat won't be used so be sure to set the keyStore so the service will pick it up, otherwise you'll get the mentioned xfire problem.

  2. Anonymous

    If you first set up crowd without ssl and then using ssl on a reverse proxy you will not able to login in from crowd web interface.

    You have to add https in this file <Crowd-Home-Directory>/crowd.properties .

  3. To save the next person several hours:

    1. Setup crowd as you would normally, without SSL configuration. Verify it works and you can log in before moving on.
    2. When you get to 'Step 3: Modify crowd.properties', don't change the domains, only change http to https, and change the port from xx to 8443. If it has my.domain.com, leave it as my.domain.com. If it says localhost, leave it as localhost

    >-(

    1. I found your comment only after several hours (wink) Thanks though! 

    2. Thanks for the great information!
      I'd just like to add that, regarding Step 3, the following files also contain the old information:

      <Crowd-Home-Directory>/crowd-openidserver-webapp/WEB-INF/classes/crowd.properties
      <Crowd-Home-Directory>/demo-src/crowd.properties
      <Crowd-Home-Directory>/demo-webapp/crowd.properties
      <Crowd-Home-Directory>/demo-webapp/WEB-INF/classes/crowd.properties
       
  4. Anonymous

    This is required, even if you are going to proxy the SSL using a fronted web service. If you proxy back to http://localhost:8095/crowd, then crowd will see the incoming request as being over http. This works for simple URLs, but it doesn't work when crowd wants to issue a 302 redirect and it thinks that the referring page was http://, as is what happens on login. 

  5. This documentation is missing the fact that, if you are using a self-signed certificate, you will need to add the certificate to your Java installations trusted certificates, otherwise, if you change Crowd over to running on SSL (after installing without SSL) then you will be able to get to the login screen, but not log in; or, if you try to install Crowd using SSL from the outset, you will be able to access the install wizard over SSL, but it will fail once it asks for the Crowd install URL.

     

    See Re: SSLHandshakeException - unable to find valid certification path to requested target for a roughly accurate description of how to add a self-signed certificate to Java's cacerts file.

    1. I agree! This info should be added to this documentation.

      Luckily I read your comment and it solved my problem.

      Thanks!

      1. Good catch guys! I've updated the docs now. Thanks for letting us know (smile)

  6. Why Atlassian doesn't bother providing exact step by step instructions that actually work is beyond me. To ease the frustration of others that try replicating a working SSL setup I could not make this work without exporting the certificate created in step 2 like this:

    $JAVA_HOME/bin/keytool -exportcert -alias tomcat > file.cer

    This guide and the number of steps required to make this work is a bit puzzling to me. Why Crowd, Confluence and JIRA aren't setup by default with a working SSL configuration and some self signed certificates is just weird. It ought to be better to provide instructions on how to take a working SSL setup to one using "real" certs.

    1. I am right there with you man, I absolutely LOVE Atlassian's product suite and have purchased the starter editions of most all of there applications. But the issues with setting things up securely when forward facing and the lack of consistency inside of all of the different applications is very disappointing, and the SSL issues when using crowd with SSO and HTTPS is just atrocious.

      I really hope they can assign a couple guys to work on making the experience across multiple apps more fluid and consistent and hopefully a couple more to work on the lack of SSL / HTTPS out of the box support are two major issues I vote up!

  7. Regarding step 4.  What you are doing here is allowing callsback into crowd to know the CA chain, because the CA chain is in your keystore file.  This is very important, because without the edits to the setenv scripts you will get errors like javax.net.ssl.SSLHandshakeException.  The same step, or roughly there about, is also needed on EVERY other Atlassian products to allow the application to AUTH against crowd over https.  By default the connection string from say JIRA looks like this:  http://crowd.example.com:8095/crowd/ which sends your user/password data over clear text; what you really want in JIRA is https://crowd.example.com:8443/crowd/.  Without the edits to the setenv for each application the https call will fail.

    1. I think "step 4" refers to older documentation because there is no longer a step 4.

      Step 4 used to be "Step 4: Create or Modify setenv.sh or setenv.bat"

      So either this is no longer required or Atlassian doesn't have the best documentation. You decide.

      Also, hi John! (If you are the same John Peacock I know, which is likely)

      -JDS

  8. I also take exception to this statement: 

    "Please be aware that this material is provided for your information only, and that you use it at your own risk."

    In my head it translates to:

    "We really don't support getting a secure solution to our customers on a product that is suppose to provide better security"

  9. I got this error in my logs when crowd started with SSL: javax.net.ssl.SSLException: Unrecognized SSL message, plaintext connection?

    Atlassian actually has a ticket for this. Java 7 does some dumb stuff. See here: Unrecognized SSL message, plaintext connection?

  10. I might add that these instructions do not enforce SSL. They only enable it. To ensure you get SSL on every connection regardless of how you specify the URL (http or https), you need to add a security constraint to <crowd installation>/crowd-webapp/WEB-INF/web.xml just before the final </web-app> tag as follows:

    <security-constraint>
      <web-resource-collection>
        <web-resource-name>Restricted URLs</web-resource-name>
        <url-pattern>/</url-pattern>
      </web-resource-collection>
      <user-data-constraint>
        <transport-guarantee>CONFIDENTIAL</transport-guarantee>
      </user-data-constraint>
    </security-constraint>

    Otherwise, you'll still be able to connect via http. With the constraint it all automatically goes SSL

    1. Thanks Mike. I do this exact same thing for Confluence, I didn't realize it would work for Crowd!

      -Kelly Schoenhofen

  11. This solution works to setup Crowd behind a secured Nginx proxy. Crowd must not run on HTTPS, so it's easier to setup.

    http://serverfault.com/questions/618501/atlassian-crowd-nginx-ssl-setup-not-working-redirect-loop

    Connector definition in <crowd installation>/apache-tomcat/conf/server.xml
    <Connector URIEncoding="UTF-8" acceptCount="100" connectionTimeout="20000"
               disableUploadTimeout="true" enableLookups="false" maxHttpHeaderSize="8192"
               maxThreads="150" minSpareThreads="25" port="8095" redirectPort="8495"
               useBodyEncodingForURI="true"
               proxyName="crowd.example.com"
               proxyPort="443"
               scheme="https"/>
    <crowd installation>/client/conf/crowd.properties
    application.name                        crowd
    application.password                    password
    application.login.url                   http://localhost:8095/crowd/console/
    crowd.server.url                        http://localhost:8095/crowd/services/
    crowd.base.url                          http://localhost:8095/crowd/
    session.isauthenticated                 session.isauthenticated
    session.tokenkey                        session.tokenkey
    session.validationinterval              2
    session.lastvalidation                  session.lastvalidation
    <crowd home>/crowd.properties
    session.lastvalidation=session.lastvalidation
    session.tokenkey=session.tokenkey
    crowd.server.url=http\://localhost\:8095/crowd/services/
    application.name=crowd
    http.timeout=30000
    session.isauthenticated=session.isauthenticated
    application.login.url=http\://localhost\:8095/crowd
    session.validationinterval=0
    application.password=***
    nginx.conf
    server {
        listen          443 ssl;
        server_name     crowd.example.com;
    
        ssl_certificate         /etc/nginx/ssl/crowd.example.com.crt;
        ssl_certificate_key     /etc/nginx/ssl/crowd.example.com.key;
    
        location / {
            proxy_set_header X-Forwarded-Host $host;
            proxy_set_header X-Forwarded-Server $host;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_pass http://localhost:8095/;
            proxy_redirect off;
            proxy_connect_timeout 300;
        }
    }
  12. Hi Everybody,

    I am new to Atlassian I have set up jira, confluence and stash behind the HAProxy and now trying to automate the Crowd installation and basic configuration behind the HAProxy over https. I drop https at HAProxy level and then send requests over http to Crowd. My settings are as following.

     

    haproxy.cfg
    global
        maxconn 4096
        user haproxy
        group haproxy
        tune.ssl.default-dh-param 2048
    
    
    defaults
        mode http
        timeout connect 100000
        timeout client 100000
        timeout server 100000
        balance roundrobin
    
    frontend abc_http
        bind *:443 ssl crt /tmp/mycerts.pem
        option forwardfor except 127.0.0.1
        balance roundrobin
    
        acl crowd_url hdr_dom(host) -i crowd
        use_backend crowd if crowd_url
    
    
    backend crowd
        option httpchk
        option forwardfor
        cookie JSESSIONID prefix indirect nocache
        server my_crowd IP:8095 inter 2000 rise 2 fall 5
    
    
    
    ../apache-tomcat/conf/server.xml
    <Connector URIEncoding="UTF-8" acceptCount="100" connectionTimeout="20000"
               disableUploadTimeout="true" enableLookups="false" maxHttpHeaderSize="8192"
               maxThreads="150" minSpareThreads="25" port="8095" redirectPort="8495"
               useBodyEncodingForURI="true"
               proxyName="crowd.example.com"
               proxyPort="443"
               scheme="https"/>

    along with other usual stuff.

    When I create certificates I use "crowd.example.com" for first and last name and then put values as following properties files.

    <crowd installation>/client/conf/crowd.properties
    application.name                        crowd
    application.password                    password
    application.login.url                   http://localhost:8095/crowd/console/
    crowd.server.url                        http://localhost:8095/crowd/services/
    crowd.base.url                          http://localhost:8095/crowd/
    session.isauthenticated                 session.isauthenticated
    session.tokenkey                        session.tokenkey
    session.validationinterval              2
    session.lastvalidation                  session.lastvalidation
     
     
    ---------------------- As well as -------------------
     
    application.name                        crowd
    application.password                    password
    application.login.url                   http://crowd.example.com/crowd/console/
    crowd.server.url                        http://crowd.example.com/crowd/services/
    crowd.base.url                          http://crowd.example.com/crowd/
    session.isauthenticated                 session.isauthenticated
    session.tokenkey                        session.tokenkey
    session.validationinterval              2
    session.lastvalidation                  session.lastvalidation
    
    
    <crowd home>/crowd.properties
    session.lastvalidation=session.lastvalidation
    session.tokenkey=session.tokenkey
    crowd.server.url=http\://localhost\:8095/crowd/services/
    application.name=crowd
    http.timeout=30000
    session.isauthenticated=session.isauthenticated
    application.login.url=http\://localhost\:8095/crowd
    session.validationinterval=0
    application.password=***
     
     
    ---------------------- As well as -------------------
     
    session.lastvalidation=session.lastvalidation
    session.tokenkey=session.tokenkey
    crowd.server.url=https\://crowd.example.com/crowd/services/
    application.name=crowd
    http.timeout=30000
    session.isauthenticated=session.isauthenticated
    application.login.url=https\://crowd.example.com/crowd
    session.validationinterval=0
    application.password=***
    
    

     

    But none of above settings worked for me I can get upto BaseURL setup stage but then complains "SSL handshake failed. Please make sure you have installed the SSL certificate into the JVMs keystore." if I use "https://crowd.example.com/crowd" as Base URL. Note it doesn't accept any other base url.

    I would highly appreciate your advice to get this resolved.

    1. if you get this error

      SSL handshake failed. Please make sure you have installed the SSL certificate into the JVMs keystore

      Try this, it helped me:

      Troubleshooting SSL certificates and Crowd


      If the following fails, then the troubleshooting will help you

      1. Download SSLPoke.class
      2. Execute the class as per the below, changing the URL and port appropriately.

      <JAVA_HOME>/bin/java SSLPoke crowd.example.com 443

      if environment is okay then you will get "Accepted" or something otherwise some error then you need to import your key to javas keystore

      PS: For the case you want to import your key the default password for keystore is "changeit"