Download and Install OpenSSO on Ubuntu

Installing OpenAM (OpenSSO) on Tomcat 7 on Ubuntu 12.04

For a project recently, I wanted to integrate OpenSSO with Joomla and Tomcat. The first step was finding and installing OpenSSO. Problem was I could not find where to download OpenSSO from. Turns out Oracle killed OpenSSO as a download a few years ago, and it has been re-incarnated as OpenAM or Open Access Management.

First step was to download and install OpenAM. And this is the topic of this blog post.

Pre-requisites and Downloads

I am assuming that Tomcat 7 is already installed on your Ubuntu box. If not, follow the steps outlined in my previous post http://opendesignarch.blogspot.com/2012/10/how-to-install-tomcat-7-on-ubuntu-1204.html

Now lets proceed with installing OpenAM. Open a browser windows and access the website http://openam.forgerock.org/

 Access the download page link from the main web site. (http://forgerock.org/openam.html)

I downloaded the latest Stable version called OpenAM 10.0.0

Access the Install Guide as part of the site Wiki

We will follow the Install guide step by step to setup the Open AM environment. First step is to copy the downloaded file to a location, where we can extract it....

Interestingly, unzipping the zip file creates a folder called opensso, as shown below

Ensuring a Fully Qualified Domain Name

The next step as per the install guide is to ensuring that the machine has a fully qualified domain name. That is easy to do. Open a terminal window on Ubuntu and type the following.

> sudo gedit /etc/hosts

This ensures that we can edit the hosts file.

Now make a fully qualified domain entry in the hosts file for the 127.0.0.1 IP address. Mine looks as follows

127.0.0.1 ub1204.arthgallo.com

Now save the file and exit. Just to make sure, we have got everything setup correctly, open a browser window and type the fully qualified domain name you just created.

http://ub1204.arthgallo.com/

And, I see the following page, from my local Apache installation.

Not only that, I can also enter

http://ub1204.arthgallo.com:8080/ and I can see my Tomcat installation.

Configuring Tomcat 7 prior to installation

It is important that the Tomcat 7 instance is able to handle the memory requirements for OpenAM. In order to achieve this, we need to first shut down Tomcat and alter some configuration parameters. To stop the Tomcat service enter the following on the command line.

> sudo /etc/init.d/tomcat7 stop

Now, we need to edit the configuration parameters such that there is adequate memory for OpenAM to load correctly.

To do this we must change the JAVA_OPTS that are used to run the process. Navigate to /usr/share/tomcat7/bin folder and open the file setenv.sh in a text editor.

It is important to confirm, why we are editing the setenv.sh file, when the first instinct is to change the JAVA_OPTS in the startup.sh file. However, that points to catalina.sh. The file catalina.sh clearly states that any Java parameters for Tomcat should be altered through the CATALINA_OPTS parameter. Further, we find that catalina.sh suggests that any custom changes be done through a setenv.sh file so it can be maintained going forward. Hence, the reason for editing the setenv.sh file.

> cd /usr/share/tomcat7/bin

> sudo gedit setenv.sh

In my case, the setenv.sh file did not exist previously. So the editor created a new file with that name. Now add the following lines in the setenv.sh file

CATALINA_OPTS="$CATALINA_OPTS -Xmx1024m -XX:MaxPermSize=256m"

Next, save and close the file. Once, we closed the file it is very important to give execute permissions to setenv.sh. We do this by entering the following on the command prompt.

> sudo chmod a+x *.sh

We can confirm that the setenv.sh has now been marked as an executable.

Copying over the .war file

Now, I can deploy the openam.war simply by copying the .war file that is included in the distribution into the Tomcat webapps folder as below.

On my machine the webapps folder is at /var/lib/tomcat7, and I unzipped the contents of the OpenAM download at ~/Work/Servers/OpenAM. The deployable .war file is at the location ~/Work/Servers/OpenAM/opensso/deployable-war.

> cd ~/Work/Servers/OpenAM/opensso/deployable-war

> sudo cp opensso.war /var/lib/tomcat7/webapps

Now that the deployable .war file is copied, it is time for the next step.

Giving tomcat7 user write permissions

The next step that is very important is to give the Tomcat user write permissions on the tomcat folder. Turns out that this does not happen by default.

We need to issue the following commands on the command prompt.

> sudo chgrp -R tomcat7 /usr/share/tomcat7

> sudo chmod -R g+w /usr/share/tomcat7

Starting the Tomcat 7 service

Before starting the service, I wanted to make sure that the new configuration parameters for Java run time actually took effect. So, I took a quick look at my CPU and memory before starting the Tomcat 7 process. It looked like this...

Now lets start Tomcat7. We can start the service as follows

> sudo /etc/init.d/tomcat7 start

Now we can see the impact on memory, of our configuration changes.

Configuring OpenAM

Next step is to configure OpenAM. It is very important to access the browser with the fully qualified domain name.

In my case, it is http://ub1204.arthgallo.com:8080/opensso.

MAKE SURE you enter your Fully Qualified Domain Name ONLY in the browser.

Entering this I am shown the following screen.

Now, I am ready to start configuring the opensso instance, which will be the subject of my next post where we configure this OpenSSO installation against ApacheDS.