Print-friendly Version

Single Sign-On Using Sun Java System Access Manager 2005Q4 and Sun Java System Access Manager Policy Agent 2.2

Manikandan Chandrasekaran, August 2006

Abstract: This Quick-Start Guide is designed to help the user set up single sign-on (SSO) for web applications on Sun Java Enterprise System software.

Disclaimer: This article is not meant to be a comprehensive guide for the various Sun products mentioned here. The official documentation on http://docs.sun.com is the final and authoritative source for all information.

One of the primary security requirements when developing web applications is to do authentication and authorization. As the number of applications grows, both in type and complexity, the different ways in which authentication and authorization is achieved also become more numerous. Hence, a user who has access to multiple applications will probably end up having multiple identities: Even if the applications share a single user repository, the user will still need to log in again, as the user credentials have not been carried between applications. Therefore, SSO between applications has grown to be of vital importance within enterprises.

Sun Java System Access Manager is the primary product in the Sun Java Enterprise System middleware stack for providing user authentication, authorization, and SSO of applications. It uses an agent-based approach for protecting web applications. Individual agents make up the Sun Java System Access Manager Policy Agent software set. These individual agents belong to two distinct categories: web agents and Java 2 Platform, Enterprise Edition (J2EE) agents. Web agents protect content on web and proxy servers while J2EE agents protect content on a variety of deployment containers, including application servers and portal servers.

The agent intercepts a request to a protected resource (this can be configured for the whole container or to a specific application) running in the deployed container (such as a web or application server), which is protected by the agent. The agent checks for a session token embedded in a cookie and validates the SSO token. The agent then sends this request to the Java System Access Manager Policy Service, to either grant or deny access to the protected resource. A policy decision is then made whether to grant or deny the request. More architectural details can be found in the Sun Java System Access Manager documentation and in the Sun Java System Access Manager Policy Agent User's Guide.

A list of agents available for Sun Java System Access Manager is given in the section "Useful Links."

Sun Java System Access Manager Policy Agent 2.2, the latest version, has many new features (see the Sun Java System Access Manager Policy Agent 2.2 Release Notes documentation under "Useful Links"). This article aims to demonstrate a small subset of these features to enable developers to quickly set up a simple SSO between web applications as a first step. The other features of Java System Access Manager and agents can be used later. This document demonstrates the following features:

1. SSO between multiple containers: applications running on Sun Java System Web Server, Sun Java System Application Server, and Apache Tomcat
2. Some of the commonly used scripts, configuration files, and log files to set up SSO and for debugging agents
3. Configuration of the new sample demo application that ships with Java System Access Manager Policy Agent 2.2
4. The non-administrative-based (non-root) install of Java System Access Manager Policy Agent 2.2
5. The new profile-based install of Java System Access Manager Policy Agent 2.2

Figure 1: SSO-Enabled Applications
(Click to Enlarge)

The previous diagram shows one simple test scenario used here to demonstrate SSO between different types of containers (web and application servers) and between products from different suppliers (Sun Microsystems and Apache Software Foundation).

Follow these steps to achieve SSO:

1. Install Sun Java Enterprise System 2005Q4.
2. Install and configure Sun Java System Web Policy Agent 2.2 on Sun Java System Web Server 2005Q4 (6.1).
3. Install and configure Sun Java System Application Policy Agent 2.2 on Sun Java System Application Server 8.1 2005Q4.
4. Install and configure Sun Java System Application Server Policy Agent 2.2 on Apache Tomcat 5.5.
5. Test SSO between the various applications.

Step 1: Install Sun Java Enterprise System 2005Q4

Install Java System Access Manager 2005Q4 on a supported web container (such as Sun Java System Application Server or Sun Java System Web Server). Make sure that the data used in the install is documented as shown in the following table.

Note: In this example am is the host name and india.sun.com is the domain name of Java System Access Manager, and Java System Access Manager is running on port 80. Verify that you can access Java System Access Manager at http://am.india.sun.com:/amconsole (as user amadmin and password).

Log in to Java System Access Manager as amadmin and create the following Access Manager roles (with one exception given). Create users and assign the roles according to the following matrix.

Step 2: Install and Configure Sun Web Server Policy Agent 2.2 on Sun Java System Web Server 2005Q4(6.1)

Creating a Web Server Instance

Log in to Java System Web Server administration server and start the default web server instance, for example, ws.india.sun.com running on port 80. This server instance will be used for testing the SSO. Make sure that you can access http://ws.india.sun.com from a browser.

Installing Java System Access Manager Policy Agent

1. Stop the web server instance running on port 80.
2. Use the correct Access Manager Policy Agent 2.2 for Sun Java System Web Server 2005Q4 (6.1) and for the correct operating system.
3. Start agent setup and enter the directory location for the web server instance where this agent will be installed (in this case at /jes4/opt/SUNWwbsvr/https-ws.india.sun.com).
4. Enter the Java System Access Manager configuration data correctly, especially the Java System Access Manager server name (fully qualified domain name), port, and the amldappassword (NOT the amadmin password) for the shared secret fields. Click Install.
5. Restart the web server instance running at ws.india.sun.com using the Sun Java System Web Server admin server. If you need to apply changes, click Apply (on the right-hand corner) and do so.

Testing Web Server Instance

Access the Web Server at http://ws.india.sun.com. You should now be prompted to log in.

Creating Policies for Accessing the Web Server

1. Log in to Access Manager at http://am.india.sun.com/amconsole and click on View Policy and create a new URL policy.

2. To this policy, add a new rule to allow GET and POST access to http://ws.india.sun.com/*.

Figure 2: Create a New URL Policy
(Click to Enlarge)

3. Search and add to this policy the Access Manager role employee as a subject.

Figure 3: Search and Add the Access Manager Role Employee as a Subject
(Click to Enlarge)

4. Click Finish and save.

Note: If Access Manager and the agent (protecting the web server) are running on the same server, Microsoft Internet Explorer has a problem in differentiating port numbers while redirecting users. You need to set the following property to fix this. If the agent and Access Manager are running on different servers, or if you are accessing using Mozilla or Firefox browsers, the following change is not required:

1. Back up this file (the default agent properties location):

/etc/opt/SUNWam/agents/es6/config/_jes4_opt_SUNWwbsvr_https-ws.india.sun.com/AMAgent.properties

Figure 4: Generic Sun xterm
(Click to Enlarge)

Change com.sun.am.policy.agents.config.override_port=true in this property file.

2. You can configure a custom error page for the web agent. Create an HTML page called error.html under /opt/SUNWwbsvr/docs/. In the Amagent.properties file, change the following property to give your own custom error page:

# The URL of the access denied page.  If no value is specified, then
# the agent will return an HTTP status of 403 (Forbidden).
#
com.sun.am.policy.agents.config.accessdenied.url =http://ws.india.sun.com/error.html

3. Any changes in the AMAgent.properties file will require a restart of the web server instance ws.india.sun.com.

Log in to http://ws.india.sun.com. When challenged, any user in the role of employee should be allowed to the page.

Step 3: Install and Configure Sun Java System Application Server Policy Agent 2.2 on Sun Java System Application Server 2005Q4 (8.1)

1. Download Access Manager Policy Agent 2.2 for Sun Java System Application Server 8.2 (see "Useful Links"). Create a directory and unzip the downloaded agent.

2. Create an agent profile in Access Manager:

• Log in to Access Manager console at http://am.india.sun.com/amserver/console (or you can also use the old console at http://am.india.sun.com/amconsole) as amadmin. (Note: If you are using Access Manager 6.3, the console can only be accessed at http://am.india.sun.com/amconsole).
• Click on Access control and select Realm. Click Subjects and then Agents. Create a new agent (such as TestProfile). This data will be required when installing the agent.

3. Log in to the Application Server admin console and create a new application server instance. Let's call it test1, running on http port 80. You may need to create an application server node agent at this stage.

4. Stop the Application Server domain admin server and the app server instance test1.

5. Start the agent install.

./agentadmin -install

Note: If the agentadmin does not have execute permissions, add execute permissions as in chmod +x agendadmin.

6. Enter the correct data when installing the agent. A sample agent summary sheet is as follows:

Application Server Config Directory : 
/jes4/var/opt/SUNWappserver/domains/domain1/config
Application Server Instance name : test1
Access Manager Services Host : am.india.sun.com
Access Manager Services Port : 80
Access Manager Services Protocol : http
Access Manager Services Deployment URI : /amserver
Agent Host name : sunas.india.sun.com
Domain Administration Server Host is remote : false
Application Server Instance Port number: 80
Protocol for Application Server instance : http
Deployment URI for the Agent Application : /agentapp
Encryption Key : GYI3egsTP5FeDHtxf6WuBzj9nQdG2Y
Agent Profile name : TestProfile
Agent Profile Password file name : /jes4/agentpassword
Agent installed on the DAS host for a remote instance : false
Agent and Access Manager on same application server instance : false

(Note: If Access Manager Policy Agent and Access Manager are installed on the same server, then this property should be made true.)

7. Start the App Server domain server and the application server instance test1.

8. Deploy the Access Manager Policy Agent Application agentapp (located at <agent-base>/etc/agentapp.war), provided by Access Manager Policy Agent 2.2, to the application server instance test1 using the application server admin console. Access Manager Policy Agent will use this application.

9. Deploy the sample J2EE test application agentsample (which ships with the Access Manager J2EE agent) to the application server instance test1. This will be located at <agent base installdirectory>j2ee_agents/am_as81_agent/sampleapp/dist/agentsample.ear.

This is the sample application used to test the SSO.

10. If you would like to use your own J2EE application, please ensure that the web.xml has the required filter and filter-mapping tags as specified in the Access Manager Policy Agent documentation.

11. Create the policies using the Access Manager console as specified in the readme.txt present at <agent base installdirectory>j2ee_agents/am_as81_agent/sampleapp. (Note: The roles and users have already been created in Step 1.)

12. Restart the application server instance test1.

13. Verify that you can access http://sunas.india.sun.com without being challenged. Also verify that you can access http://sunas.india.sun.com/agentapp and that the Access Manager login screen appears. You can log in as any user in the employee role, manager role, or customer group, or as any user in the india domain.

Step 4: Install and Configure Sun Java System Application Server Policy Agent 2.2 on Apache Tomcat 5.5

Note: All operations for Apache Tomcat 5.5 will be done as a non-root user tomcat and in the group tomcat. This demo is also intended to demonstrate that the Access Manager Policy Agent can be installed as a non-root/non-administrative user.

1. Create a group called tomcat and create a user tomcat that belongs to this group.

2. Download and install Apache Tomcat 5.5 as a non-root user tomcat. Install the core and administration web modules of Apache Tomcat 5.5. Refer to the Apache Tomcat documentation for installation and configuration.

Add the following entries in $CATALINA_HOME/conf/tomcat-users.xml:

<user name="manager" password="manager" roles="standard,manager" />
<user name="admin" password="admin" roles="admin" />

You will access the admin application via a user called adminuser. Therefore, another entry for adminuser must be made in $CATALINA_HOME/conf/tomcat-users.xml (the password for adminuser can be a dummy password, as it is not used by Access Manager).

A sample file is shown:

<?xml version='1.0' encoding='utf-8'?>
<tomcat-users>
  <role rolename="tomcat"/>
  <role rolename="role1"/>
  <role rolename="standard"/>
  <role rolename="manager"/>
  <role rolename="admin"/>
  <user username="tomcat" password="tomcat" roles="tomcat"/>
  <user username="role1" password="tomcat" roles="role1"/>
  <user username="both" password="tomcat" roles="tomcat,role1"/>
  <user username="adminuser" password="admin123" roles="admin"/>
  <user username="manager" password="manager" roles="standard,manager"/>
  <user username="admin" password="admin" roles="admin"/>
</tomcat-users>

If you are going to create a user called admin in Access Manager to access the Tomcat admin application, the previous steps are not needed, as this user ID is already present in tomcat-users.xml.

3. Start Tomcat and verify access to the Apache Tomcat home page http://tomcat.india.sun.com and the manager/admin applications as user IDs manager and admin.

4. Download the Sun Java System Access Manager Policy Agent 2.2 for Apache Tomcat 5.5 Servlet/JavaServer Pages (JSP) Container (see "Useful Links"). Create a directory <PolicyAgentHome> and unzip the downloaded agent.

5. Use the following steps to create an agent profile in Access Manager:

• Log in to the Sun Access Manager console at http://am.india.sun.com/amserver/console (or you can also use the old console at http://am.india.sun.com/amconsole) as amadmin.

Note: If you are using Access Manager 6.3, the console can only be accessed at http://am.india.sun.com/amconsole.

• Click on Access control and select Realm. Click Subjects and then Agents. Create a new agent (TomcatProfile). This data will be required when installing the agent.

• Copy the password used for creating the profile in this file: /export/home/tomcatuser/agentpassword.

6. Shut down the Tomcat server.

7. Start the agent install <PolicyAgentHome>/j2ee_agents/am_tomcat_agent/bin/agentadmin -install from the directory created in Step 2. The summary of a sample install is as follows:

Tomcat Server Config Directory :
/export/home/tomcat/apache-tomcat-5.5.15/conf
Access Manager Services Host : am.india.sun.com
Access Manager Services Port : 80
Access Manager Services Protocol : http 
Access Manager Services Deployment URI : /amserver 
Agent Host name : tomcat.india.sun.com 
$CATALINA_HOME environment variable :
/export/home/tomcat/apache-tomcat-5.5.15 
Tomcat global web.xml filter install : true 
Application Server Instance Port number : 5555
Protocol for Application Server instance : http 
Deployment URI for the Agent Application : /agentapp 
Encryption Key : KEQBXNuosQ5ntb5+lmpo2L1BM9OIK7 
Agent Profile name : TomcatProfile
Agent Profile Password file name : /export/home/tomcat/agentpassword

8. Copy <PolicyAgentHome>/j2ee_agents/am_tomcat_agent/etc/agentapp.war to the webapps directory of Apache Tomcat. This application is required by the Access Manager Policy Agent.

9. Copy <PolicyAgentHome>/j2ee_agents/am_tomcat_agent/sampleapp/dist/agentsample.war to the webapps directory of Apache Tomcat. This will be the sample application used to test the SSO.

10. Follow the steps mentioned in the <PolicyAgentHome>/j2ee_agents/am_tomcat_agent/sampleapp/readme.txt to create policies in the Access Manager for the application running on Tomcat.

Note: Since the roles and users have been created when installing the Access Manager Policy Agent for Sun Java System Application Server, they need not be repeated and can be reused while creating the policies for the URLs relating to the Tomcat application.

11. Follow the steps mentioned in the <PolicyAgentHome>/j2ee_agents/am_tomcat_agent/sampleapp/readme.txt file to make changes in this file: <PolicyAgentHome>/j2ee_agents/am_tomcat_agent/agent_001/config/AMAgent.properties.

  com.sun.identity.agents.config.filter.mode[admin]=ALL
  com.sun.identity.agents.config.filter.mode[manager]=ALL
  com.sun.identity.agents.config.filter.mode[host-manager]=ALL
  com.sun.identity.agents.config.filter.mode = J2EE_POLICY

12. Since the Tomcat admin and manager applications will also be protected by the Access Manager Policy Agent, follow the steps mentioned in Conditional Post-Installation Steps for J2EE Agents in Policy Agent 2.2. Make the following changes in web.xml of the manager, admin and host-manager web applications present at <TOMCAT-Home>/server/webapps:

	
  id=manager,ou=role,dc=india,dc=sun,dc=com
  id=admin,ou=role,dc=india,dc=sun,dc=com

The web.xml in the agentsample application also needs to be modified to change the dc=iplanet,dc=com to the installed realm.

Note: Please make the changes according to your realm in Access Manager. The aforementioned changes were made as the Access Manager was installed in the dc=india,dc=sun,dc=com realm.

13. Start the Apache Tomcat server and access the Tomcat applications running at these locations:

• http://tomcat.india.sun.com/agentsample
• http://tomcat.india.sun.com
• http://tomcat.india.sun.com/admin/
• http://tomcat.india.sun.com/manager/html

Testing SSO

Log in as amadmin in Access Manager and verify that the following policies have been created.

Test the SSO to various applications according to the following access control matrix.

The agentsample application shipped with Access Manager Policy Agent has filter tags specific to Access Manager in the deployment descriptors. If you need to use the Access Manager Policy Agent for protecting your J2EE applications, you will need to add these filters. Refer to the sample application for specific details.

Summary

This article has demonstrated the setting and configuring of SSO between different web containers using Sun Java System Access Manager Policy Agent and Sun Java System Access Manager. This should serve as a good starting point for Sun Java System Access Manager and SSO. Later, the more advanced features of Java System Access Manager Policy Agent and Java System Access Manager can be rolled out.

Troubleshooting Tips

1. If you are unable to see the protected Apache Tomcat home page after the policy agent install and configuration, make sure that all the files under /export/home/tomcat are owned by user tomcat:tomcat.

2. Make a backup of the AMAgent.properties file before making any changes. The web container will need to be restarted after making changes to the AMAgent.properties file (unless the hot-swap flags are enabled).

3. You can enable debugging in the policy agent by setting the com.iplanet.services.debug.level=message property in AMAgent.properties.

Useful Links

• Sun Java System Access Manager Download with Sun Java Enterprise System
• Sun Java System Access Manager Policy Agent Download Page (with list of agents available)
• Sun Java System Access Manager Policy Agent 2.2 Documentation
• Sun Java System Web Server Download Page
• Apache Tomcat
• Sun Developer Network (SDN)

Unless otherwise licensed, code in all technical manuals herein (including articles, FAQs, samples) is provided under this License.