Installing SSL Certificates in an OpenAM Server

Being security software, the OpenAM server uses SSL certificates as part of its normal operations. For simple deployments the self-signed “test” certificates generated by the software itself on installation are sufficient. More complex architectures will probably require installing real certificates to the OpenAM server.

Most enterprise SSO environments are necessarily more complex that the usual desktop pilot. Many will involve two or more OpenAM servers run in separate containers on a pair of application servers that are front-ended by HTTP proxies and a load balancing device. These kinds of arrangements will usually require at a minimum the installation of SSL root, intermediate and server certificates for the SSL url.

The following operations are probably best accomplished by logging into the OpenAM server as the application user with the specific OpenAM environment sourced. In a multi-server environment these procedures should be followed for both servers.

The software used for these procedures are the ubiquitous openssl utility and the standard Java keytool (OpenAM runs best using Oracle’s Java rather than the OpenJDK, check ForgeRock’s documentation for which Java version to use with a particular version of OpenAM).

Default Keystore for OpenAM Servers

The default keystore created on installation of an OpenAM server is located under INSTALL_DIRECTORY/openam. For example, “/usr/share/tomcat/openam/openam”. The default key file name is keystore.jks.

Check the Current Keystore State

Sign in as the application server system user (e.g. “tomcat6”), source the environment (standard would be a .env file at the root of the app server user’s home, e.g. “/usr/share/tomcat/openam-test.env”), and run the following command:

keytool -list -v -keystore keystore.jks

The keystore should already contain a self-signed cert with your chosen alias (“sso.example.com”), created during setup. If it does not, or if you need to change the alias because you will be working with a different host name, your best course is to create a fresh keystore (after first backing up and renaming the old file!).

keytool -genkey -alias sso.example.com -keyalg rsa -keysize 2048 keystore keystore.jks.new

(Note that I changed the name of the keystore file just in case you failed to read my warning about backing the original up — you can manually rename the file later if you have to)

Obtaining SSL Certificates

To make a text file containing the required SSL certificates follow these procedures:

1. Root Certificate. Get the root certificate from the Certificate Authority (CA) that issued the SSL cert for your SSL url (e.g. VeriSign, CACert, etc.). Copy and paste the cert text between “—-BEGIN CERTIFICATE—-” and “—–END CERTIFICATE—–” to a file named something like “cacert.pem”.

2. Intermediate Certificate. Some CA’s like VeriSign require a class 3 intermediate cert to complete the certificate chain. This will also be available from your CA. Copy and paste the cert text between “—-BEGIN CERTIFICATE—-” and “—–END CERTIFICATE—–” to a file named something like “cacert-class3.pem”.

3. Server Certificate. A signed server cerificate is obtained from a CA after submitting a signing request to it.

To make a certificate request:

keyool -certreq \
-keystore keystore.jks \
-alias sso.example.com \
-file sso.example.com.req

The “sso.example.com.req” file is what gets submitted to the CA. Note that if your keystore does not have the requested alias, keytool will throw an error. To cure that you’ll need to create a fresh keystore as described above under “Check the Current Keystore State”.

After receiving the signed cert from the CA, paste its contents, including the header and footer “—-BEGIN CERTIFICATE—-” and “—–END CERTIFICATE—–” to a file named something like “sso.example.com.pem” (each SSL url has a unique server cert, so naming the cert file for the url should help avoid confusion — remember the cert contents cannot be directly read with a text editor, you need a tool like openssl to do that).

Importing with Keytool

Importing these certificates with the standard Java keytool is also done in 3 steps. Change your working directory to the location where you created the certificate files and execute the following commands:

1. Import the Verisign root certificate.

keytool -import -trustcacerts -alias cacert -file cacert.pem -keystore keystore.jks

2. Import the Intermediate certificate.

keytool -import -trustcacerts -alias cacert-class3 -file class3.pem -keystore keystore.jks

3. Import the server certificate.

keytool -import -trustcacerts -alias sso.example.com -file sso.example.com.pem -keystore keystore.jks

(the server cert is unique to each load balanced url, to avoid confusion you should name the cert file for that url)

Verifying the Installation

Verify the installation of the certificates by running this command against the keystore:

keytool -list -v -keystore keystore.jks