I tried to implement the concept presented in this excellent article from my colleagues Robert Skoczylas and Marina Sum. Their article is quite well detailed. I thought the implementation would be painless and that I should have a demo to show to partners and customers in a couple of minutes.
Actually, it was a little more complex than I originally anticipated and I would like to share and describe my experience with you. Reading the above-mentioned article is a prerequisite to understand or implement the project described here under.
The objective is to create a web application that will leverage OpenSSO (or Access Manager) for
- user authentication - with the help of the Policy Agent
- user authorization - with the help of the Policy Agent for URL authorization and a Custom Policy Service and the AM Client SDK for fine grained authorization.
The NetBeans project and some other supporting file needed to compile and run this example are also available.
To implement the concept presented in the above mentioned article, you have to
#1 Download & Install NetBeans 6.0
At the time of this writing, the latest beta version of NetBeans is 6.0 M10. Install it using a full option installation : this will install Glassfish, OpenSSO, JBI, ...
The NetBeans 6.0 installer will take care of installing and configuring Glassfish and OpenSSO for you. However, you will need to change one OpenSSO configuration parameter, as the default value is incorrectly set by the installer (See CR110896).
- Open the file : <glassfish root>/domains/domain1/config/amflatfiledir/AMConfig.properties
- Change com.iplanet.am.cookie.encode=false to com.iplanet.am.cookie.encode=true
#2 Add AM Admin Tools
Access Manager comes with a set of command line tools allowing you to manage the server, add or modify services etc ... Unfortunately, the OpenSSO implementation bundled with NetBeans 6M10 does not include these command line tools. You will need these tools to install a Custom Policy Service, as described below.
To get these tools, you must download the complete Access Manager 7.1 package from Sun's web site, then follow these instructions to install them.
The only parameter that you will need to know to install the tools is the full path to your AM Config directory :
This step is not necessary if you are implementing this sample with Access Manager 7.1, as the command line tools are installed by default.
#3 Create an AS domain to host you own application
OpenSSO is installed in the default domain, created when you installed NetBeans 6 and Glassfish. Although it is officially possible to deploy a Policy Agent on the same instance as Access Manager, I do not like the idea and prefer to keep things clearly separate. Therefore, I would advise to create a second instance of Glassfish, separate from the one hosting Access Manager, dedicated to host your home-made applications.
To create a second domain, type the following command :
<glassfish root>/bin/asadmin create-domain --user admin --adminport 14848 --domaindir <glassfish root>/domains --instanceport 18080 --savemasterpassword=true --savelogin=true webdomain
You will need to change <glassfish_root> to your Glassfish installation directory.
#4 Download and Install Policy Agent
Now that your second instance is ready to deploy your applications, you must download and install the OpenSSO policy agent. I used the nightly builds from OpenSSO and the docs from Access Manager.
The state file containing all the answers I gave for my installation is available for you to download. Do not forget to create a Policy Agent profile in OpenSSO Console before installing the agent.
#5 Create a web application to test Policy Agent installation
Next step is to create a simple web application, protect it with the policy agent to test your installation.
- Use NetBeans to craete a HelloWorld-complexity web application (or use the FineGrainedSample application I do provide with this blog)
- Modify web.xml to add the <filter> element that will enable the Policy Agent as described in the documentation. (you can also have a look at my web.xml in the NetBeans project provided with this blog entry)
- Deploy the application
- Create a user in OpenSSO console
- Create a URL Policy to authorize your user to access your application
- Access and test your application
#6 Create a custom policy service and import it to OpenSSO
Now, it is time to create a custom policy service to be used with your application. The process and concepts are clearly explained in the article I mentioned above.
I slightly changed the Service description XML file :
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE ServicesConfiguration PUBLIC "=//iPlanet//Service Management Services (SMS) 1.0 DTD//EN""jar://com/sun/identity/sm/sms.dtd">
<Service name="CustomPolicyService" version="1.0">
<AttributeSchema name="serviceObjectClasses" type="list" syntax="string" i18nKey="CustomPolicyService"/>
i18nKey="Choose Bank Account Access">
<ChoiceValue i18nKey="Read Only">READONLY</ChoiceValue>
and I used this command to load the file into OpenSSO
$AM_TOOLS_BASE/bin/amadmin --verbose --runasdn $AM_ADMIN --password $ADMIN_PWD --schema $POLICY_FILE
#7 Call The Custom Policy service from your code
The next steps involve modifying the code in a web application to call the OpenSSO Custom Policy Service we just created.
The Java code is explained in Robert and Marina's article. You will find it also in the NetBeans project I do provide with this blog entry.
You will need to change the NetBeans project classpath to compile it because the code refers to classes provided by the AM Client SDK. Strictly speaking, it is not necessary to install the AM Client SDK because all the required jar files and config files are already installed as part of the OpenSSO and Policy Agent installation.
I choose to use the files provided by the Policy Agent. the files you need to add to your project classpath are :
<policy agent root>/Agent_001/config
<policy agent root>/locale
<policy agent root>/lib/amclientsdk.jar
#8 Create users, roles and policies with OpenSSO console
I created three users and three roles.
Then I created three policies, each one giving an access level (Hidden, Read Only, Full) to each role.
#9 Deploy, Test the application and have fun !
Depending on the user you authenticate with, you will have partial or full access to all attributes on the screen.
Should you have comments, remarks about missing pieces or errors in this short tutorial, do not hesitate to leave your comments.