How To
Archived

How do I install an SSL enabled OpenAM 12.x cluster with SSL load balancer?

Last updated Jan 5, 2021

The purpose of this article is to guide you through installing an SSL enabled OpenAM cluster with an SSL load balancer. This example uses two CentOS™ virtual machines (VMs), where one VM has an Apache Tomcat™ 6 server installed and an Apache™ 2.2 server with OpenSSL® installed for load balancing, and the other VM has a Tomcat 6 server installed.


1 reader recommends this article

Archived

This article has been archived and is no longer maintained by ForgeRock.

Configuring Tomcat servers and Apache for SSL

  1. Enable SSL on both Tomcat servers (example is for host1): # cd /usr/share/tomcat6/conf # mkdir certs # keytool -genkey -alias host1.example.com -keyalg RSA -keystore /usr/share/tomcat6/conf/certs/keystore.jks Enter keystore password: Re-enter new password: What is your first and last name? [Unknown]: host1.example.com What is the name of your organizational unit? [Unknown]: test What is the name of your organization? [Unknown]: test What is the name of your City or Locality? [Unknown]: test What is the name of your State or Province? [Unknown]: CO What is the two-letter country code for this unit? [Unknown]: US Is CN=host1.example.com, OU=test, O=test, L=test, ST=CO, C=US correct? [no]: yes
Note

You will be prompted for the key password for <tomcat>, which is the password specifically for this certificate (as opposed to any other certificates stored in the same keystore file). You must use the same password here as was used for the keystore password itself. This is a restriction of the Tomcat implementation. Currently, the keytool prompt will tell you that pressing the ENTER key does this for you automatically.

  1. Enter key password for <tomcat>    (RETURN if same as keystore password):
  2. Modify the Tomcat server.xml file to enable SSL: # /usr/share/tomcat6/conf # cp server.xml server.xml.orig # vi server.xml Change: <!-- <Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true"   maxThreads="150" scheme="https" secure="true" clientAuth="false" sslProtocol="TLS" /> --> to: <Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true"    maxThreads="150" scheme="https" secure="true"     keystoreFile="/usr/share/tomcat6/conf/certs/keystore.jks" keystorePass="password"     clientAuth="false" sslProtocol="TLS" />
  3. Generate an SSL certificate for the Apache server that you've installed for load balancing: # cd /tmp # openssl req -out ca.csr -new -newkey rsa:2048 -nodes -keyout ca.key Generating RSA private key, 2048 bit long modulus … Country Name (2 letter code) [XX]:US State or Province Name (full name) []:CO Locality Name (eg, city) [Default City]:test Organization Name (eg, company) [Default Company Ltd]:test Organizational Unit Name (eg, section) []:test Common Name (eg, your name or your server's hostname) []:host1.example.com Email Address []:test@test.com Please enter the following 'extra' attributes to be sent with your certificate request A challenge password []: An optional company name []: # openssl x509 -req -days 365 -in ca.csr -signkey ca.key -out ca.crt Signature ok subject=/C=US/ST=CO/L=test/O=test/OU=test/CN=host1.example.com/emailAddress=test@test.com Getting Private key # cp ca.crt /etc/pki/tls/certs # cp ca.key /etc/pki/tls/private/ca.key # cp ca.csr /etc/pki/tls/private/ca.csr
  4. Modify the Apache ssl.conf file to enable SSL: # yum install mod_ssl openssl
Note

mod_ssl is needed for Apache to run in SSL mode.

  1. # cd /etc/httpd/conf.d/ # cp ssl.conf ssl.conf.orig # vi ssl.conf Change: SSLCertificateFile /etc/pki/tls/certs/localhost.crt SSLCertificateKeyFile /etc/pki/tls/private/localhost.key to: SSLCertificateFile /etc/pki/tls/certs/ca.crt SSLCertificateKeyFile /etc/pki/tls/private/ca.key
  2. Start Tomcat and Apache: # service tomcat6 start # service httpd start

Configure Apache to load balance between Tomcat servers using SSL (HTTPS)

  1. Modify the Apache ssl.conf file to enable load balancing: # cd /etc/httpd/conf.d/ # cp ssl.conf ssl.conf.orig # vi ssl.conf Add the following to the end of the ssl.conf file (right before the final tag), ensuring you update the server names, ports, LB cookie and deployment URI to match your deployment details: ProxyRequests off ProxyPreserveHost on SSLProxyEngine on SSLProxyCheckPeerName off SSLProxyVerify none SSLProxyCheckPeerCN off <Proxy *> order deny,allow Allow from all </Proxy> <Proxy balancer://openam> BalancerMember https://host1.example.com:8443 retry=300 route=server1 BalancerMember https://host2.example.com:8443 retry=300 route=server2 ProxySet lbmethod=byrequests ProxySet stickysession=AMLBCOOKIE </Proxy> Header add Set-Cookie "AMLBCOOKIE=APACHE.%{BALANCER_WORKER_ROUTE}e; path=/;" env=BALANCER_ROUTE_CHANGED ProxyPass / balancer://openam/ ProxyPassReverse / https://host1.example.com:8443/ ProxyPassReverse / https://host2.example.com:8443/
  2. Restart Apache: # service httpd restart

Exchanging Tomcat certificates to establish trust

In certain circumstances, OpenAM servers will communicate with one another using server to server calls. This is called Back Channel Communication and is often used when one OpenAM server needs to validate an SSO session that was created on another OpenAM server.

Since we are using SSL for our OpenAM servers, these servers must trust the certificate of the other server in order to connect via SSL for Back Channel Communications. In this step, we will export the Tomcat SSL certificate from one server, and import that certificate into the truststore of the other Tomcat server. We will then repeat the process so that both Tomcat servers contain the certificate of the other Tomcat server in their truststores.

  1. Export the certificate from Tomcat server 1: # cd /usr/share/tomcat6/conf/certs # keytool -exportcert -alias host1.example.com -file host1_openam.crt -keystore ./keystore.jks Enter keystore password: Certificate stored in file <host1_openam.crt> …
  2. Copy the exported certificate to Tomcat server 2.
  3. Import the certificate from Tomcat server 1 into server 2 (on server 2): # cd /usr/share/tomcat6/conf/certs # keytool -importcert -alias host1.example.com -file ./host1_openam.crt -trustcacerts -keystore /etc/pki/java/cacerts Enter keystore password: Owner: CN=host1.example.com, OU=test, O=test, L=test, ST=CO, C=US … Trust this certificate? [no]: yes Certificate was added to keystore
Note

The certificate will be imported into the Java® truststore, not the keystore we created for Tomcat. The location will depend on the location of the Java version Tomcat is using; Tomcat is using the Java located in: /usr/lib/jvm/jre-1.7.0-openjdk.x86_64/. This links to: /etc/pki/java/cacerts, which is why we used this file for the keystore. The default password for the Java keystore is changeit.

  1. Verify the certificate: # keytool -list -alias host1.example.com -keystore /etc/pki/java/cacerts Enter keystore password: host1.example.com, Mar 25, 2015, trustedCertEntry, Certificate fingerprint (SHA1): 15:4A:2E:BA:B2:C0:7F:D5:79:A5:7B:3D:85:BC:70:04:EC:3B:5C:A3
  2. Repeat steps 1 to 4 to import certificate from server 2 into server 1.

Installing OpenAM on the second Tomcat server

Note

Java® 7 supports Server Name Indication (SNI). If Tomcat is using a Virtual Host, SSL negotiation will fail with a “handshake alert: unrecognized name” error. If you see this error when trying to configure your second OpenAM instance, then either use Java 6 or add "-Djsse.enableSNIExtension=false" to $JAVA_OPTS in …/tomcat6/conf/tomcat6.conf

  1. Install OpenAM on host1: # cp OpenAM-12.0.0.war /usr/share/tomcat6/webapps/openam.war
  2. Use browser to run configurator (https://host1.example.com:8443/openam):
    • Select Custom Configuration.
    • Select First Instance in step 3.
    • Set site configuration to Yes in step 4 and populate the following details: Site Name: lb1 Load Balancer URL: https://lb1.example.com:443/openam Enable Session HA Persistence and Failover: [checked]
  3. Install OpenAM on host2: # cp OpenAM-12.0.0.war /usr/share/tomcat6/webapps/openam.war
  4. Use browser to run configurator (https://host2.example.com:8443/openam):
    • Select Custom Configuration.
    • Select Add to Existing Deployment in step 3 - Server URL:  https://host1.example.com:8443/openam
    • Set site configuration to Yes in step 5 and populate the following details: Site Name: lb1 Load Balancer URL: https://lb1.example.com:443/openam Enable Session HA Persistence and Failover: [checked]
Note

If the certificate you imported in the previous section is incorrect, the configurator will say the URL is invalid when you add to existing deployment in step 3 and not allow you to proceed as the host is not trusted.

Testing the installation

  1. Verify the install:
    • Navigate to https://lb1.example.com:443/openam and log in to the console.
    • Refresh the browser and see that you are bound to a single OpenAM server.
    • Comment out the following line in the Apache ssl.conf file and observe the browser bounce between OpenAM servers. ProxySet stickysession=AMLBCOOKIE
  1. Test the CTS failover:
    • Navigate to https://lb1.example.com:443/openam and log in to the console. Note the server name. 
    • Shut down that server and then refresh the browser. You will not be prompted to log in again.
  2. Test OpenAM Back Channel Communication – part 1:
    • Disable Session Failover on both OpenAM servers by navigating to: Configuration > Global > Session and select the Secondary Configuration Instance created during the install (in this example, lb1). Deselect the Session Persistence and High Availability Failover Enabled option.
    • Restart both Tomcat servers.
    • Repeat step 2 (Test the CTS failover). This time you will be prompted to log in again because the OpenAM server that had the user session is now down and the session is not stored in the CTS since Session Failover has been disabled.
  3. Test OpenAM Back Channel Communication – part 2:
    • Ensure Session Failover is still disabled on both OpenAM servers as per step 3.
    • Comment out the following line in the Apache ssl.conf file and restart the Apache server. ProxySet stickysession=AMLBCOOKIE
    • The browser will bounce from one OpenAM server to another and not require the user to log in again. This is because the OpenAM server without the user session is making a back channel call to the server that created the session to validate the session.

See Also

FAQ: SSL/TLS secured connections in AM and Agents

How do I enable SSL in AM (All versions) post-install?

How do I enable SSL in AM (All versions) for an existing installation?

How do I configure a Web Agent (All versions) for SSL offloading?

How do I configure a Java Agent (All versions) for SSL offloading?

How do I configure SSL offloading at the Agent (All versions) for virtual hosts?

How do I make AM 5.x and 6.x communicate with a secured LDAP server?

Related Training

ForgeRock Access Management Core Concepts (AM-400)

Related Issue Tracker IDs

N/A


Copyright and Trademarks Copyright © 2021 ForgeRock, all rights reserved.