When web applications are accessed across the internet, there is always the possibility of usernames and passwords being intercepted by intermediaries. These intercepts may occur when the data is travelling between a client and the server. It is often a good idea to enable access via HTTPS (HTTP over SSL) and require the use of HTTPS for pages where passwords are sent.

In some cases where transmitted data is sensitive, all pages should be accessed via HTTPS.

Note: Using HTTPS may result in slower performance.

On this page:

Using Crowd over SSL

The process of enabling SSL 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 SSL Access

Edit CROWD/apache-tomcat/conf/server.xml, and at the bottom before the </Service> tag (not to be confused with </Server> tag!), add this section (or uncomment it if it's already there):

<Connector port="8443" maxHttpHeaderSize="8192" maxThreads="150"
minSpareThreads="25" maxSpareThreads="75" enableLookups="false"
disableUploadTimeout="true" acceptCount="100" scheme="https" secure="true"
clientAuth="false" sslProtocol="TLS" SSLEnabled="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).

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)

The keytool utility will 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:

1. 'changeit' (this is the default value Tomcat expects), or

2. if you use a value other than 'changeit', you must also specify this value in conf/server.xml. You must add the following attribute to the Connector tag described above:

   keystorePass="<password value>"

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

• $JAVA_HOME/bin/keytool -import -alias serverCert -file file.cer -keystore $JAVA_HOME/jre/lib/security/cacerts

For information on adding a key pair issued by a Certificate Authority (CA), refer to the section entitled 'Installing a Certificate from a Certificate Authority' in 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 Sun documentation for more information on the keytool:

• Solaris and Linux
• Windows

Try this blog post for a handy tutorial:

• Talkingtree blog post

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/

Step 4: Create or Modify setenv.sh or setenv.bat

In order to ensure that XFire calls work over SSL you will need to pass keystore values to the JVM. To do this either edit or create a setenv.sh or setenv.bat file located in Tomcat's bin directory: apache-tomcat/bin/setenv.sh or setenv.bat

The contents of the file should look similar to this:

JAVA_OPTS="-Xms128m -Xmx256m -XX:MaxPermSize=256m $JAVA_OPTS -Djavax.net.ssl.keyStore=/<pathtokeystore>/.keystore -Djavax.net.ssl.keyStorePassword=changeit -Djavax.net.ssl.trustStore=/<pathtokeystore>/.keystore -Djavax.net.ssl.trustStorePassword=changeit"

Replace <pathtokeystore> with the path to your .keystore file and the password with your keystore's password if modified.

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

https://localhost:8443/crowd/console

トラブルシューティング

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)

これは、Tomcat がキーストアを見つけられなかったことを意味します。キーツール ユーティリティは、現在のユーザーのホーム ディレクトリに .keystore という名称のキーストアをファイルとして作成します。Unix / Linux ではホーム ディレクトリは多くの場合 /home/<username> です。Windows では多くの場合 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

Tomcat のキーストアパスワードとキーパスワードに異なるパスワードが使われていることを意味します。この二つのパスワードは同一でなければなりません。

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

関連トピック

Configuring an SSL Certificate for Microsoft Active Directory
Configuring Crowd