Since it's just taken me 4 days to get a working setup where JASPA will talk via a load balancer to multiple AM instances, I thought I'd better document what I've done. I started off following Rich Riley's guide OpenAM Clustering Setup but there are many pitfalls waiting which I'd like to avoid in the future.
Deploy N instances of OpenAM into N instances of Tomcat
I'm assuming here that you are familiar with each of the painful steps involved in doing this, so I'm going to gloss over them. Rich's document deals with this in more detail, although note that you will need to use Tomcat 8+ for your OpenAM containers in order for Websocket Notifications to work. JASPA is less fussy about the version of its container and will accept any old rubbish.
Download and deploy OpenDJ
Download OpenDJ from here and unpack it somewhere permanent (i.e. not /tmp). My first attempt was with version 2.5, but I found it impossible to uninstall, so I would recommend version 3 upwards. Version 3 seemed to uninstall version 2 without difficulty. Once you've downloaded OpenDJ and unpacked it, you'll find a "setup" script in the top level directory. This fires up a cute graphical installer. About the only things to do during the setup are:
- Set a password ("password" is quite sufficient, although you can choose to be more exotic)
- Set the base DN for data to
dc=openam,dc=forgerock,dc=org, i.e. not what Rich's document tells you to do
- Make a note of the port number. This will most likely be 1389.
Download and deploy haproxy
Download haproxy from the interweb and install it somewhere permanent. I have no idea how the default haproxy.cfg looks, but it will almost certainly be useless. The one I use is as follows. You will need to edit
OPENAM_URL_2, etc. etc. accordingly. Each will need to be the full path to one of your OpenAM instances, e.g.:
# this config needs haproxy-1.1.28 or haproxy-1.2.1 global log 127.0.0.1 local0 log 127.0.0.1 local1 notice maxconn 4096 user root group wheel defaults log global mode http option httplog option dontlognull retries 3 option redispatch maxconn 2000 contimeout 5000 clitimeout 50000 srvtimeout 50000 frontend http-farm bind *:8080 default_backend openam backend openam balance roundrobin cookie amlbcookie indirect nocache server openam1 OPENAM_URL_1 cookie 01 server openam2 OPENAM_URL_2 cookie 02 server openam3 OPENAM_URL_3 cookie 02
Wipe out any and all OpenAM configuration on your machine
While all your Tomcat instances are dead, you'll need to remove any and all previous OpenAM configuration. The directory $HOME/.openamcfg will contain one file per OpenAM instance, each containing the name of one directory. Each of these directories will need to be removed, followed by the $HOME/.openamcfg directory itself.
Configure the first OpenAM instance
Start up the Tomcat container for one of your OpenAM instances, it doesn't matter which one. In a browser, navigate to that OpenAM instance and select Create New Configuration
- At Step 2 "Server Settings", choose a configuration directory which will be unique to this instance. I usually make this the equivalent of $HOME/openamN where N is the instance number
- At Step 3 "Configuration Data Store Settings" you need to choose "First instance" and leave all the settings alone.
- At Step 4 "User Data Store Settings" you should select "Other User Data Store" and "OpenDJ"
- Specify the port number you noted down when installing DJ
- Specify the password you chose when installing DJ
- At Step 5 "Site Configuration" you must
- Select "Yes"
- Choose a site name - any name, it doesn't have to exist - the setup will create it for you. I chose main
- Enter the URL of haproxy. This will be http://YOUR-DOMAIN:BINDING-PORT/BACKEND
- You'll have to sort out YOUR-DOMAIN (mine is openam.example.com). Although I guess "localhost" would do, I didn't use it.
- BINDING-PORT is the one you specified under frontend > bind in the config file above (i.e. 8080)
- BACKEND is the "openam" thing in the config file above
- This makes my Load Balancer URL: http://openam.example.com:8080/openam
- Race through the remaining step and onwards to victory
Configure the remaining OpenAM instances
For each of the remaining instances, start up your Tomcat container and browse to OpenAM running in that instance and again select Create New Configuration
- At Step 3 "Configuration Data Store Settings" select "Add to Existing Deployment" and enter the URL of your first OpenAM instance (not the load balancer)
- Step 4 will be skipped
- At Step 5 "Site Configuration", enter the site name you gave when setting up the first instance and the load balancer URL
- Race onwards towards victory
Configure the JASPA instance
Deploy JASPA into your nominated Tomcat instance. You probably already know that OpenAM and JASPA don't play well in the same container, so choose a different container to the OpenAM ones.
Setup users and agents
It is about this point that I startup one of the OpenAM instances (it actually doesn't matter which one) and start setting up users and agents in CDSSO mode.
- Top Level Realm > Subjects: I add a group called "Accessors", create user who is a member of that group
- Top Level Realm > Agents > JEE: Create a J2EE agent with an appropriate password
- Global: Agent Root URL for CDSSO: Add the load balancer URL to the existing JASPA URL, i.e. http://openam.example.com:8080/openam
- Global: General: Agent Debug Level: Set to message
- Don't forget to save.
- SSO: Cross Domain SSO: check the box to enable, ensure the correct load balancer path is in the CDSSO Servlet URL (it will have cdcservlet stuck on the end of it).
- SSO: CDSSO Trusted ID Provider: Remove the URL containing the load balancer path and add the cdcservlet URL for EACH ONE of your OpenAM instances (this is necessary for LARES to work with Agent 3.x)
- SSO: CDSSO Domain List: Add the JASPA domain.
- Don't forget to save.
- Top Level Realm > Authorization > Policy Sets> Default Policy Set: Add a policy specifying that only "accessors" have access. The policy URI can just be the default with all the stars in it.
- NON CDSSO: If you're planning not to use CDSSO, I'd seriously advise you forget it.
What to look for
Watch to see if any of the Tomcat or OpenAM instances die on startup. By checking the catalina.log you will be able to see if there are any binding errors. This will indicate you have two or more of your Tomcat instances trying to use the same port. Unfortunately there is no easy way to configure this.