1. WEB DEVELOPMENT
Securing Web Applications
with OpenAM
As software developers, we seek to design software that gets people’s
attention. Software that meets the needs of the user, performs well, and
pleases the eye is sure to get users’ attention. The security model of an
application, on the other hand, gets very little attention from the average
user - that is until something goes wrong. One serious security breach could
permanently blacklist an application or even a developer in the eyes of the
users affected by that breach.
You’ll learn: You should know:
• How OpenAM can secure web applications and how to • Should have a clear understanding of how web appli-
set up OpenAM in a development environment. cations work.
• For the tutorial, some experience with Linux and the Li-
nux command line will be helpful.
G
ood software design dictates that security be ta-
ken into account throughout the requirements-
-gathering process and the actual build. Unfortu- be scalable. For example, an application server may store
nately, security considerations are often an afterthought session state for each user and expect the user to send
in software design, again because developers are often a session cookie with each request. This is a very com-
so focused on functionality, performance and looks that mon approach and honestly works well for most one-off
security ends up taking a backseat. Even if you as a de- applications. But what happens when one of our applica-
veloper give careful consideration to security in all your tions needs to connect (on behalf of the user) to some
applications, you may end up “inheriting” an application service we’ve written. Let’s say the service runs on a se-
with a weak security model. cond server and also requires authentication? The ses-
sion cookie means nothing to that second server so will
Authentication and Authorization we force the user to pass in credentials again? Or will
Security in web applications is a very broad topic. Let’s the developer compromise and hard code some creden-
narrow it down by talking about two major security con- tials in the application for making the call to the external
siderations - authentication and authorization. Authen- service?
tication is about verifying that the user is who they say Or what if the developer simply wants to distribute
they are. For example I may enter my username and a large application across multiple servers for perfor-
password to identify myself to an application. Depending mance but doesn’t want the user to have to log in more
on the circumstances, I may have to answer some per- than once? Each of those servers would need to “know”
sonal questions or I may be prompted to install a certifi- about the user’s session.
cate in my web browser’s store.
Once an application “knows” who the user is, it can HTTP Authentication
move onto the authorization phase which is deciding Up until this point we have talked about users being pro-
whether to fulfill or deny a particular request (i.e. to ac- visioned a session and that session being tracked by so-
cess a resource, take a certain action, etc.) on behalf of me stateful server. But it should be noted that we could
that particular user. For example, user “pmorris” may be build our web applications such that their servers could
authorized to view resource “x” but may not be autho- be essentially stateless. In other words each request wo-
rized to edit resource “x”. uld be made in isolation. In such a case the user would
have to be authenticated and authorized for each and
Will it scale? every request. Some may frown upon such a design but a
In some cases a web application may handle authentica- stateless design is inherently scalable.Take a look at how
tion and authorization very well but the solution may not well the World Wide Web has scaled over the past 20
34 5/2011

2. Securing Web Applications with OpenAM
years. This is due in large measure to its stateless design. So where does that leave us then? Well we’re back to
Most calls that happen over HTTP are in isolation altho- a stateful server maintaining sessions for all our users
ugh it has to be admitted that most requests made over and we’re back to the problems with scalability that we
HTTP do not need to be authenticated or authorized. mentioned earlier.
HTTP as a protocol does include standards for authen-
tication, namely Basic and Digest Authentication both of OpenAM as an Authentication and
which allow for a stateless approach. So why don’t we see Authorization Solution
more applications using Basic or Digest Authentication? Meet OpenAM. (You see? I didn’t forget the title of this ar-
In the case of Basic authentication there are inherent se- ticle.) The “AM” stands for Access Management. OpenAM
curity weaknesses since credentials are passed over the is a child project of OpenSSO (“SSO” for single-sign-on),
wire in clear text. Digest Authentication is very secure an open source product formerly sponsored by Sun Mi-
however since it uses one-way hashing to obscure the crosystems, now by Oracle.When Oracle bought out Sun
credentials such that it’s impossible to extract them. It al- they took back the latest release of OpenSSO (version
so includes policies for preventing the harvesting and re- 9.x) and now offer 8.x as the latest and greatest.A number
playing of hashed credentials. So why don’t we see Digest of former Sun executives went on to head up a company
Authentication more in web applications? Well for one called Forge Rock, which has taken version 9.x of OpenS-
thing it is not trivial to learn and implement the standard. SO, named it OpenAM and started to maintain and build
But the overriding reason is that frankly HTTP authen- on it (up to 9.5.x now), pledging to follow its original pro-
tication is just “not there yet.” A lot of it seems to have ject roadmap from when it was under the oversight of Sun.
to do with the inconsistent and incomplete manner that I see OpenAM as a solution for building security into
web browsers have implemented the Digest Authentica- your distributed applications from the start, as well as a
tion standard. The details on that are beyond the scope way to secure that pre-existing, not-so-secure applica-
of this article, (Did you notice I haven’t mentioned Ope- tion that you may have “inherited” as a hired developer
nAM once yet?) so I encourage you to read these two (since we know you would never build an unsecure ap-
articles if you want to learn those details: plication yourself).
http://www.artima.com/weblogs/viewpost.jsp?thre- Authenticating with OpenAM
ad=155252 and http://www.vsecurity.com/download/pa- So OpenAM can be our stateful server for provisioning
pers/WeaningTheWebOffOfSessionCookies.pdf and tracking sessions for users. It can hook into an iden-
Figure 1. OpenDJ Server Settings Figure 3. OpenDJ Directory Data
Figure 2. OpenDJ Topology Options Figure 4. OpenDJ Runtime Options
en.sdjournal.org 35

3. WEB DEVELOPMENT
tity repository that already exists (i.e. Microsoft Active Scale Applications Securely with
Directory) or you could set up its “sister” application, OpenAM
OpenDJ (formerly OpenDS) as the user store. OpenDJ Let’s talk about why OpenAM scales so well. OpenAM is
is an open source LDAP directory service also sponso- a Java-based application that runs within a servlet conta-
red by Forge Rock. And apparently, at least some users iner (Apache Tomcat, Glassfish, JBoss, etc.). So OpenAM
just use a plain old relational database as the identity is itself a web application but it is not your web applica-
store. Using the identity repository to verify the identity tion. It partners with your web application. It has a sin-
of each user, OpenAM provisions a session and can set gle responsibility: to keep other applications secure. To
cookies that represent that session in the user’s browser. illustrate: large office buildings with offices that handle
(I actually put together a proof of concept that elimina- very sensitive or secured resources often have a securi-
tes the need for OpenAM to set cookies in the user’s ty team operating within the building. That team’s focus
browser.) is to keep the building and everything in it secure. The
other teams of people within the building don’t have to
Authorizing with OpenAM focus so much on security since there is already a team
OpenAM can be conFigured with fine-grained poli- dedicated to that purpose operating within the building.
cies that dictate which identity subjects (users and/ The other teams are able to focus on what they do best
or groups) have access to which resources and even (whatever that might be).
which HTTP methods can be invoked by a particu- OpenAM as a framework operates as that security
lar subject against a particular resource. So in other team in your infrastructure, keeping your applications
words OpenAM can be conFigured to allow user secure so that your application code can focus more on
“pmorris” to GET the resource at http://www.exam- things like functionality, usability and performance.
ple.com/resource but not POST to that same resource OpenAM exposes services (SOAP or REST) that can
(that same URL). be invoked from your applications for authenticating
Figure 5. OpenAM General Figure 7. OpenAM Configuration Store
Figure 6. OpenAM Server Settings Figure 8. OpenAM User Store
36 5/2011

4. Securing Web Applications with OpenAM
users, checking their authorization to make a certain Take OpenAM for a Test Drive
request, and even interacting with your identity reposi- So if you’re like me you like getting your hands on a
tory to add users, to get the groups a user belongs to, technology so you can evaluate it yourself. Following
etc. For the proof of concept I spoke of earlier I set up is a step-by-step tutorial on how to set up OpenAM
very simple filters in front of a RESTful service to per- with OpenDJ as a user repository. All the prerequi-
form authentication and authorization before allowing sites for our tutorial, from the OS (Ubuntu 10.04), to
access to the service itself. Can you see how such an the servlet container (Apache Tomcat 7.0), to the two
approach can scale to practically any size? As long as applications themselves, they’re all open source (i.e.
you have the session token representing the session, free!) so you’ve got no reason not to jump right in!
you can call OpenAM’s services from anywhere (even Let’s get started.
outside your own domain) to authenticate and autho-
rize a request. Set up Ubuntu
The OpenAM framework not only includes the central Download Ubuntu 10.04 LTS from http://releases.ubuntu.
application itself but also a family of policy agents that com/lucid/ubuntu-10.04.2-desktop-i386.iso
can be deployed to remote application servers or web If you’re setting up Ubuntu as a virtual machine be
servers to “police” said servers and all the applications sure and up the RAM to at least 1024MB.
running on them.There are policy agents for J2EE servlet Walk through the installation process
containers, and web servers (i.e. Apache and IIS). A policy normally.
agent is like a remote “security officer” that intercepts Once logged in go to System -> Administration -> Users
all requests coming in to the server (J2EE container, web and Groups and change the user you created to an Ad-
server) and consults with the “chief security officer”, the ministrator.
OpenAM application itself, to determine if the request
should be fulfilled or denied.
Figure 11. OpenAM Subjects
Figure 9. OpenAM Site Configuration
Figure 10. OpenAM Agent Information Figure 12. OpenDJ Control Panel
en.sdjournal.org 37

5. WEB DEVELOPMENT
Install Java
While an OpenJDK package is available out-of the-box with
10.04, the Sun JDK is not, and that’s the one we want. So open
a terminal window and run the following commands first:
sudo add-apt-repository „deb http://archive.
canonical.com/ lucid partner”
sudo apt-get update
Then install the Sun JDK:
sudo apt-get install sun-java6-jdk
Install Tomcat
We need a fully qualified domain name (FQDN) when
we install OpenAM (i.e. localhost will not work for con-
figuration) so we need to add an entry to the hosts file.
Run the following command to edit the file:
Figure 13. OpenDJ Manage Entries
sudo nano /etc/hosts
I added this line:
127.0.0.1 devbox.apius.org
Be sure and exit (Command + x on the Mac), and save
changes on the way out (“y” followed by Enter)
Download Apache Tomcat 7 by running wget with a
current link address as in:
wget http://apache.ziply.com/tomcat/tomcat-7/v7.0.12/
bin/apache-tomcat-7.0.12.tar.gz
Untar it with this command:
tar xzvf apache-tomcat-7.0.12.tar.gz
Figure 14. OpenDJ New User
If running on VMware Fusion follow this documenta- I decided to move it to a more standardized folder lo-
tion to install VMware Tools: https://help.ubuntu.com/com- cation with:
munity/VMware/Tools
Reboot. mv apache-tomcat-7.0.12 /usr/local/tomcat7
Figure 15. OpenAM New User
38 5/2011

6. Securing Web Applications with OpenAM
Figure 16. OpenAM REST Authentication Response
Figure 17. OpenAM REST Validate Token Response
We need to set a couple of environment variables to Install OpenAM
ensure the Tomcat 7 instance uses the Sun JDK and Download OpenAM 9.5.2.The 9.5.x releases take advan-
that OpenAM will have sufficient memory to install tage of Java EE 6.
and run. Run the following command:
sudo nano /usr/local/tomcat7/bin/setenv.sh
And add these two lines:
JAVA_HOME=/usr/lib/jvm/java-6-sun
export CATALINA_OPTS=“$CATALINA_OPTS -Xms128m
-Xmx1024m -XX:MaxPermSize=256m”
Next run:
sudo nano /usr/local/tomcat7/conf/tomcat-users.xml
I added what is in listing 1 so as to access the Tomcat
management console.
Start Apache Tomcat with:
/usr/local/tomcat7/bin/startup.sh
Figure 18. OpenAM Identity Subject 1
en.sdjournal.org 39

7. WEB DEVELOPMENT
Extract it and move it into place using the following
two commands:
unzip OpenDJ-2.4.1.zip
sudo mv OpenDJ-2.4.1 /usr/local/opendj
These commands should be run in order to conFigure
the installation and open the GUI interface for final con-
figuration settings.
sudo /usr/local/opendj/bin/create-rc-script
--outputFile /etc/init.d/opendj
sudo update-rc.d opendj defaults
/etc/init.d/opendj start
cd /usr/local/opendj/
./setup
Figure 19. OpenAM Identity Subject 2
wget http://www.forgerock.org/downloads/openam/ ConFigure OpenDJ
snapshot9.5/openam_s952.war Choose a password for the Directory Manager (admin)
account. (Figure 1 – OpenDJ Server Settings)
Moving the war to the webapps folder of the Tomcat Select stand alone. (Figure 2 – OpenDJ Topology
installation will deploy it. Options)
Just create a base DN using whatever domain you pre-
sudo mv openam_s952.war usr/local/tomcat7/webapps/ fer. (Figure 3 – OpenDJ Directory Data)
openam.war Keep the defaults. (Figure 4 – OpenDJ Runtime
Options)
Install OpenDJ Review the configuration settings and hit “Finish”. Once
Now download OpenDJ using: the installation is complete go ahead and launch the Con-
trol Panel and log in to “Local Server” using the Directory
wget http://www.forgerock.org/downloads/opendj/2.4.1/ Manager password you entered during setup. Go ahead and
OpenDJ-2.4.1.zip minimize the Control Panel and let’s conFigure OpenAM.
Figure 20. OpenAM URL Policy 1
40 5/2011

8. Securing Web Applications with OpenAM
ConFigure OpenAM with OpenDJ as user store
http://devbox.apius.org:8080/openam will open the web Listing 1. Tomcat configuration
configurator. <role rolename=”manager-gui”/>
Enter a password of at least 8 characters. (Figure 5 – <role rolename=”manager-script”/>
OpenAM General) <role rolename=”manager-jmx”/>
Note the following use of that FQDN we added to our <role rolename=”manager-status”/>
hosts file earlier. (Figure 6 – OpenAM Server Settings) <user username=”admin” password=”admin”
We’ll use OpenAM’s embedded optimized OpenDS roles=”manager-gui,manager-
application to store configuration settings. (Figure 7 – script,manager-jmx,manager-
OpenAM Configuration Store status”/>
Select OpenDS (the predecessor of OpenDJ) as the
user store and make sure the Directory Name is cor- /usr/local/opendj/bin/control-panel
rect. It should automatically grab the first host name that
the loopback address (127.0.0.1) resolves to. Enter the (Figure 12 – OpenDJ Control Panel)
Directory Manager’s password that you set at installa- Select “Manage Entries” from the left menu.
tion. (Figure 8 – OpenAM User Store) Right click on “people” and select “New User”. (Figure
This is a development environment so we won’t worry 13 – OpenDJ Manage Entries)
about load balancing. (Figure 9 – OpenAM Site Configu- Be sure and change the “Naming Attribute” to “uid”.
ration) Click OK and look for the Entry Created message. (Figu-
Choose another password 8 characters or longer. (Fi- re 14 – OpenDJ New User)
gure 10 – OpenAM Agent Information) Now go back to the OpenAM console and refresh the
In the final screen, verify your configuration and press page. You should see the new user you created in the
the Create Configuration button. OpenDJ repository. (Figure 15 – OpenAM New User)
Test OpenAM Authentication Service
Add User Let’s run a quick and simple test using the REST au-
Log in to OpenAM using amadmin as a username and the thentication service in OpenAM to create a session. En-
password you entered in Step 1 of the setup. ter the following into your web browser’s address bar.
We’re going to test the authentication interface using Adjust the URL and the parameter values based on your
OpenAM’s REST services but first we’ll create a user ac- settings:
count. A user account can be created using one of the
REST services or from the OpenAM console itself but http://devbox.apius.org:8080/openam/identity/authenticate?
to illustrate the relationship between OpenAM and the username=pmorris&password=pmorrispmorris
underlying user data store, OpenDJ, we’ll add the user
from the OpenDJ control panel. This action requests OpenAM to create a session
“Access Control” tab. -> “(Top Level Realm)” -> “Sub- for the specified user and once created a token re-
jects” tab. I see two users, namely “amadmin” and “ano- presenting that session is passed back to the caller.
nymous”. (Figure 11 – OpenAM Subjects)
Again, we could add a new user from here but let’s do
it from OpenDJ.
If the Control Panel is still minimized go ahead and pull
it up if it’s not running, run this command:
Figure 21. OpenAM URL Policy 2 Figure 22. OpenAM URL Policy 3
en.sdjournal.org 41

9. WEB DEVELOPMENT
(Figure 16 - OpenAM REST Authentication Respon- You should get back the following response. (Figure 17
se) - OpenAM REST Validate Token Response)
One note though: What I did above I did only to
expedite the tutorial. In reality this is a poor prac- Test OpenAM Authorization Service
tice. Why? Since I used a browser’s address bar to Now let’s create a URL policy and test out the authori-
make this call we know that the HTTP method was zation feature. Go to the “Access Control” tab. -> “(Top
a GET. Obviously this will work but in a real world Level Realm)” -> “Policies” tab. Click on “New Policy”.
implementation it’s a bad idea. For one thing, with a I’m calling mine “Hello World Policy”. We need to assign
GET request the password parameter value will be this policy to the user we created so scroll down and
written to server logs and for another this practice click on “New” in the “Subjects” section.
breaks RESTful constraints. HTTP as a standard sta- Let’s make this a specific subject, not just any authen-
tes that GET should have no side effects. Creating ticated user. Click “Next”. (Figure 18 - OpenAM Identity
a session is definitely a side effect (a desirable side Subject)
effect but a side effect nonetheless). So in produc- Next, we’ll give the Identity Subject a name and in
tion it’s best practice to always coerce this call to our case search for our user using the “User” filter and
a POST. “Add” the user (in my case “pmorris”) to the Identity
Now let’s test the authentication service using the Subject and click “Finish” and “OK” in the next screen.
token value as a parameter. Copy the token value from (Figure 19 - OpenAM Identity Subject 2)
the response page and paste it into another call like Keep in mind that we would probably not do this in
so: real life – that is assign a single user to an Identity Sub-
ject. More likely we would create a group, add pmorris
http://devbox.apius.org:8080/openam/identity/isTokenValid- to that group and then add the group to the Identity
?token=AQIC5wM2LY4SfcxmYwlY5mX1vtaiGhw8cJd8TGJY Subject. But again, to expedite the tutorial we’ll do it
Hv6ar4M.*AAJTSQACMDE.* this way.
Figure 23. OpenAM REST Authorization Response
42 5/2011

10. Securing Web Applications with OpenAM
You should be back out at the policy listing now. (Figu- http://devbox.apius.org:8080/openam/identity/authori-
re 20 - OpenAM URL Policy 1) ze?uri=hello-world&action=POST&subjectid=AQIC5wM2LY
Under “Rules” click on “New” and make sure the set- 4SfcwUIYd-YJ4_0ubuuGDJ6-_jzFrwrDrHhsg.*AAJTSQACM-
ting is “URL Policy Agent”. Then click “Next”. (Figure 21 DE.*
- OpenAM URL Policy 2)
Name the new URL Policy Agent and assign it to a I won’t add another screen shot because the only chan-
particular URL. In our case “hello-world”. Don’t worry if ge you see is that the response now reads “boole-
that resource doesn’t actually exist on the server. Note an=false”, which is precisely what we expect based on
that I am allowing the Hello World Identity Subject to the URL Policy Agent we conFigured earlier.
GET the resource but not POST to it. Click “Finish”.
NOTE: By default, the OpenAM allows for control Conclusion
over GET and POST actions on resources, but does not OenAM is a mature application and, as such, feature-rich.
offer options for the other HTTP methods like PUT There’s full support for OAuth, which is widely used in
and DELETE. Thanks to the http://blogs.sun.com/docte- social networking sites. Identity federation is also an im-
ger/entry/enabling_put_and_delete_actions I was able to portant part of OpenAM services. Federation refers to
find and successfully modify the two files that provide storing an identity across multiple identity management sys-
the options for this configuration view within the Ope- tems or multiple organizations so that disparate systems
nAM console, namely amWebAgent.xml and amWebA- can establish a circle of trust for authenticating a user. In
gent.properties. Both are found under /WEB-INF/clas- other words, if I log in at Company X’s web application
ses of the OpenAM web application that we’re going to ad am redirected to Company Y’s web application, Com-
deploy. For each method you wish to add, simply create pany Y considers me authenticated to their application ba-
the desired AttributeSchema elements in the XML file sed on the trust relationship between the two systems. A
with their nested tags and add the name-value pairs to framework for logging and monitoring is included to sa-
the properties file. It’s simply a matter of repeating the tisfy stringent auditing requirements in some enterprises.
pattern of the GET and POST actions that are already As already mentioned for many small, one-off applications
accounted for in each the files. (Figure 22 - OpenAM OpenAM would probably be overkill. But it’s a viable candi-
URL Policy 3) date for distributed architectures and use cases of dispara-
We’ve now told OpenAM that this policy with its rule te applications needing to interface with one another and
applies to the indicated Identity Subject. share a common authentication and authorization scheme.
Let’s get a fresh session token now. Once again follow OpenAM is open source so the only up-front commit-
the pattern below and copy the response token value to ment to adoption is time to get over the learning curve. I
your clipboard: hope this article and the accompanying tutorial have given
you a boost if you are interested in learning this technolo-
http://devbox.apius.org:8080/openam/identity/authenticate? gy.Although OpenAM and OpenDJ are open source, Forge
username=pmorris&password=pmorrispmorris Rock offers support for everything from proof of concept
engagements to robust 24 hours a day by 7 days a week by
Let’s use the authorization service to check for access 2 hour response time support contracts.
rights. Enter a URL following the pattern below aga- If you think OpenAM might end up in your toolbox, check
in adjusting the path and parameters to your configu- out these additional resources for learning.
ration: https://www.packtpub.com/glassish-security-with-java-ee/book
Glassfish Security by Masou Kalali – Chapter 7, http://blogs.
http://devbox.apius.org:8080/openam/identity/authorize?uri- sun.com/doceger Doc Teger’s blog, https://wikis.forgerockorg/
=hello-world&action=GET&subjectid=AQIC5wM2LY4SfcwU confluence/display/openam/OpenAM+Documentation Forge
IYd-YJ4_0ubuuGDJ6-_jzFrwrDrHhsg.*AAJTSQACMDE.* Rck’s site, https://www.packtpub.com/openam-snaphot-9-for-
securing-your-web-applications/book New book abou Ope-
The “uri” parameter is the resource for which we are nAM
checking user authorization, the “action” is the HTTP
method, and the “subjectid” is the token value repre-
PAUL MORRIS
senting pmorris’s active session. We set the policy to
Paul is a Java and ActionScript developer in
allow pmorris to GET this resource so we expect a the Chicago area. He colaborates with a di-
“true” response when we inquire regarding authori- stributed team of developers in the United
zation. (Figure 23 - OpenAM REST Authorization Re- States and Canada.
sponse) Contact to the author (paul@quietbus.com,
Now let’s try this same request but change the “ac- http://paulmorris.drupalgardens.com/)
tion” parameter to POST as in:
en.sdjournal.org 43