Using SiteMinder 6.0 with Pramati Server 3.5 (SP5)

Enterprises can tightly secure applications running on Pramati Server using Netegrity SiteMinder solution and have single sign-on capability, using the custom Pramati Application Server Agent for SiteMinder. This replaces the standard procedure provided by Netegrity, which uses its reverse proxy server to intercept, authenticate and authorize, and forward web requests to Pramati Server. Both scenarios are described in this document.

Key terminologies

Table 1: Key Terminologies
Key Term	Description
SiteMinder	Identity Management Solution
Pramati Server	Application Serverthat processes and serves web requests
Policy Server	SiteMinder component providing authorization and authentication service to applications.
Agent	Web Agent of SiteMinder that authorizes requests for a secured resource and forwards requests to SiteMinder
Custom Agent	Single Custom Pramati Application Server Agent replaces the Agent and Reverse Proxy Server softwares. This component quickly integrates Netegrity SiteMinder with applications running on Pramati Server.

Software requirements

Pramati Server was integrated with SiteMinder running in the following environment:

About SiteMinder

Policy Server

Policy Server forms the core of SiteMinder and usually runs on a separate NT or UNIX system. It manages all key security operations for SiteMinder, and provides these services:

Agent

SiteMinder Agent is a component residing with the Web Server or Application Server hosting the resource to be protected and communicates with the Policy Server in order to enforce policies for user access to protected resources. Netegrity publishes information on several types of Agents that can be used with SiteMinder.

About Custom Pramati Application Server Agent

Custom Pramati Application Server Agent replaces the Agent and Reverse Proxy Server softwares. This component quickly integrates Netegrity SiteMinder with applications running on Pramati Server. The Custom Agent combines the security framework of Pramati Server with the installed SiteMinder infrastructure to provide rapid deployment applications that run on Pramati Server and use SiteMinder single sign-on features.

The Custom Agent is implemented as a JAAS LoginModule on Pramati Server that hosts resource to be secured. It uses the security interceptor in Pramati Server Web Container that intercepts all requests for secured resources, and determines if SiteMinder is registered to protect a resource.

If yes, the Custom Agent talks to the SiteMinder Policy Server and authenticates the user. If not, the request passes through for regular processing on Pramati Server.

The Custom Agent sets a cookie on the client (allowing page content to be personalized for the user). Subsequent requests from the authorized client carry request header parameters set by Pramati Server. The headers includes the following parameters:

Usage Scenarios

SiteMinder and Pramati Server can be used together in two possible configurations:

Scenario I: Standard Configuration using SiteMinder Web Agent

Pramati Server works outside the box and requires no extra configuration. SiteMinder Web Agent is configured to redirect requests to Pramati Server that hosts the secured resources. SiteMinder provides authorization, authentication and auditing for Pramati Server.

This is the basic topology of SiteMinder where all requests from clients are intercepted by a Reverse Proxy Server that is integrated with the SiteMinder Web Agent. The Agent then talks with the Policy Server for authenticating the client for accessing the secured resource on some server. The configuration is simple and requires only SiteMinder changes. Instructions are given further down in this document.

Scenario II: Pramati Configuration with Custom Agent

Pramati Server replaces the Reverse Proxy Server. All web requests are intercepted by the security interceptor in Pramati Web Container and, if the resource is secured using SiteMinder, the Custom Agent uses SiteMinder Policy Server for authorization and authentication.

Scenario I: Configuring SiteMinder for Pramati Server

This does not involve any configuration on Pramati Server. To configure SiteMinder Web Agent, use the Netegrity Policy Server Administration Tool as detailed below:

Start the Netgerity Policy Server Administration Tool.

Right click and select `Create Agent Type'.

Add the agent type as `pramati application server agent type' and add get and post as two actions for accessing the resources.

Now right click and select `Create Agent'.

Add `pramati_agent' as the name. This name has to provided in the web-config.xml in Pramati Server as explained in the Pramati web container specific configurations shown in the following sections. Also check the box `Support 4.x Agents'.

Select the agent type as `pramati application server agent type'.

Add the IP address information and the shared secret text value. The shared secret is configured in the web-config.xml.

Scenario II: Pramati Configuration with Custom Agent

Here the reverse proxy server is replaced by Pramati Server that now intercepts all web requests coming from the client.

The following steps assume that SiteMinder is running with the Web Agent type configured, as described in "Scenario I: Configuring SiteMinder for Pramati Server". Also, see "Software Requirements" for SiteMinder host environment details:

Step 1: Install Pramati Server with Custom Agent

Install Pramati Server SP5. For information on installing Pramati Server, refer to the Pramati Server Installation Guide.

Apply the patch server_patch.jar. This is done by copying the patch to the directory
<install-dir>/server/lib/pramati.

Start Server by executing runserver script from the directory<install-dir>/server/bin. This is required for applying the Custom Agent JAR on an existing Server installation.

Stop Server. Change setup.bat in the directory <install-dir>/server/bin as follows:

set sm =<siteminder java sdk installation directory>/webagent/java 
set CLASSPATH=%sm%\smconapi.jar;%sm%\dms.jar;%sm%\env.jar;
%sm%\jsafe.jar;%sm%\smconapi.jar;%sm%\smjavaagentapi.jar;
%sm%\smjavasdk2.jar;\c:\jdk1.3.1_04\\lib\tools.jar;
%install.root%\lib\pramati\server_patch.jar;
%install.root%\lib\pramati\classpath.jar;

Step 2: Configure Pramati Server Web Container for SiteMinder

To work, the Custom Agent must receive calls from security interceptor in the Web Container. To configure the Web Container, add the following snippet to the web-config.xml in the directory <install-dir>/server/nodes/default/config. The complete tags in the XMLs are reproduced in the appendix. Here, the tags are explained in parts for clarity.

Custom Agent class name and description

<security-interceptor-webagent  
		enabled="true" 
		can-check-for-protected-resources="true" 
		can-authorize-roles="true"> 
<classname>com.pramati.web.sso.siteminder.SMWebAgent</classname> 
<description>Custom Pramati Application Server Agent</description> 
...

security. enabled = true | false determines if the Custom Agent is to be used.

can-check-for-protected-resources = true | false. If true, Custom Agent is asked if the resource is secured, which means that any J2EE deployment descriptor based security constraint will not apply. The Custom Agent will contact SiteMinder or use its configured set of URLs. If false, J2EE security constraint rules apply.

can-authorize-roles = true | false. If true, Custom Agent is responsible also for authorization, not just authentication.

classname is the class name of Custom Agent.

Shared name for Custom Agent

This is a case-sensitive and unique name that SiteMinder uses to identity its agents. The name of the agent is also configured on SiteMinder. See "Scenario I: Configuring SiteMinder for Pramati Server" for configuring agent name "pramati_agent" on SiteMinder. The two names must match.

<entry> 
	<key>agent-name</key> 
	<value>pramati_agent</value> 
</entry>

Establishing connection between Pramati Server and SiteMinder

The connection details between Pramati Server and SiteMinder, such as shared names, ports and location of policy server, are entered in the form of key value pairs.

<entry> 
	<key>policy-server-ip</key> 
	<value>192.168.1.45</value> 
</entry>

<entry> 
	<key>connection-min</key> 
	<value>1</value> 
</entry>

<entry> 
	<key>connection-max</key> 
	<value>100</value> 
</entry>

<entry> 
	<key>connection-step</key> 
	<value>1</value> 
</entry>

<entry> 
	<key>timeout</key> 
	<value>20</value> 
</entry>

<entry> 
	<key>authorization-port</key> 
	<value>44443</value> 
</entry>

<entry> 
	<key>authentication-port</key> 
	<value>44442</value> 
</entry>

<entry> 
	<key>accounting-port</key> 
	<value>44441</value> 
</entry>

Adding shared secret for Custom Agent

Shared secret is a string that matches the value provided while configuring this agent in SiteMinder:

<entry> 
	<key>shared-secret</key> 
	<value>pramati</value> 
</entry>

Realm for the application that uses SiteMinder

Realm of the application that should use SiteMinder for authentication (can be an existing realm):

<entry> 
	<key>realm-name</key> 
	<value>siteminder</value> 
</entry>

Domain for the single sign-on cookie

        <entry> 
            <key>single-sign-on-cookie-domain</key> 
            <value>.pramati.com</value> 
        </entry>

List of protected URLs

A ";" separated list of urls that are protected. This is optional. If this entry is not provided the agent will access SiteMinder to check if the resource is protected.

	 <entry> 
            <key>protected-resources</key> 
            <value>/jspDeskWeb/numguess.jsp;/jspDeskWeb/gameofeight.jsp 
		</value> 
	</entry> 
	</details> 
</security-interceptor-webagent>

Step 3: Configure Custom Agent (SiteMinder LoginModule)

Add the realm information and the SiteMinder LoginModule information in security-config.xml located in the directory <install-dir>/server/nodes/default/config:

Realm name

<realm> 
      <!-- Name of the realm --> 
      <realm-name>siteminder</realm-name> 
      <user-manager>

User manager class

Class name of the user manager class to be used for the realm. By default system realm uses XML based user manager. User can define his own user manager for a realm. This class must implement com.pramati.services.security.spi.UserManager.

	<class-name> 
		com.pramati.security.loginmodules.xml.XMLUserManager 
	</class-name>

Start-up options

The init-options define map of key-value pair that are passed to the initialize method of the class.

<init-options> 
              <entry> 
                  <name>securityXML</name> 
                  <value>$NODE_DIR\config\system-security1.xml</value> 
              </entry> 
              <entry> 
                  <name>algotype</name> 
                  <value>encrypt</value> 
              </entry> 
              <entry> 
                  <name>algoname</name> 
                  <value>DES</value> 
              </entry> 
          </init-options> 
      </user-manager> 
  </realm>

LoginModule configuration

The SiteMinder Login Module configuration is located under this tag in the security-config.xml:

<login-module-configuration>

          <realm-name>siteminder</realm-name>

	 <class-name> 
		com.pramati.web.sso.siteminder.SiteMinderLoginModule 
	 </class-name>

	<flag>optional</flag> 
	</config-entry> 
</login-module-configuration>

Step 4: Copy the security configuration files

Copy system-security.xml from the <install-dir>/templates to $NODE_DIR\config\ and rename to system-security1.xml.

Step 5: Start Pramati Server and verify configuration

To verify the SiteMinder configuration, check the Server log for the string "Pramati Application Server Agent for SiteMinder installation successful". The log is located under <instal_root>/server/nodes/<node_name>/logs/servermsg/servermsg_<timestamp>.xml.

Appendix

Appendix A: Relevant tags in Pramati Server Web Container Configuration XML

 
<security-interceptor-webagent enabled="true" 
        can-check-for-protected-resources="true" 
        can-authorize-roles="true"> 
	<classname>com.pramati.web.sso.siteminder.SMWebAgent</classname> 
	<description>SiteMinder Custom Web Agent For Pramati Application 
	Server 
	</description> 
	<!-- details section needs to be configured for SiteMinder --> 
	<details> 
		<entry> 
            			<key>agent-name</key> 
            			<value>pramati_agent</value> 
        		</entry> 
        		<!-- The SiteMinder IP address --> 
        		<entry> 
            			<key>policy-server-ip</key> 
            			<value>192.168.1.45</value> 
        		</entry> 
        		<entry> 
            			<key>connection-min</key> 
            			<value>1</value> 
        		</entry> 
        		<entry> 
            			<key>connection-max</key> 
            			<value>100</value> 
        		</entry> 
        		<entry> 
            			<key>connection-step</key> 
            			<value>1</value> 
        		</entry> 
        		<entry> 
            			<key>timeout</key> 
            			<value>20</value> 
        		</entry> 
        		<!-- SiteMinder's authorization port --> 
        		<entry> 
            			<key>authorization-port</key> 
            			<value>44443</value> 
        		</entry> 
        		<!-- SiteMinder's authentication port --> 
        		<entry> 
            			<key>authentication-port</key> 
            			<value>44442</value> 
        		</entry> 
        		<!-- SiteMinder's accounting port --> 
        		<entry> 
            			<key>accounting-port</key> 
            			<value>44441</value> 
        		</entry> 
        		<!-- The shared secret which must match the string given while 
		config	during this agent in SiteMinder --> 		 
		<entry> 
            			<key>shared-secret</key> 
            			<value>pramati</value> 
        		</entry> 
        		<!-- The realm of the application which should use SiteMinder for 
		authentication --> 
        		<entry> 
            			<key>realm-name</key> 
            			<value>siteminder</value> 
        		</entry> 
        		<!-- The domain to set on the single-sign-on cookie --> 
        		<entry> 
            			<key>single-sign-on-cookie-domain</key> 
            			<value>.pramati.com</value> 
        		</entry> 
        		<entry> 
            			<key>protected-resources</key> 
            			<value> 
			/jspDeskWeb/numguess.jsp;/jspDeskWeb/gameofeight.jsp 
			</value> 
        		</entry> 
    </details> 
</security-interceptor-webagent>

Appendix B: Relevant tags in Pramati Server Security Configuration XML

 
<!-- realm configuraiton --> 
  <realm> 
      <!-- Name of the realm --> 
      <realm-name>siteminder</realm-name> 
      <user-manager> 
		<class-name> 
			com.pramati.security.loginmodules.xml.XMLUserManager 
		</class-name> 
		<init-options> 
              <entry> 
                  <name>securityXML</name> 
                  <!--  --> 
                  <value>$NODE_DIR\config\system-security1.xml</value> 
              </entry> 
              <entry> 
                  <name>algotype</name> 
                  <value>encrypt</value> 
              </entry> 
              <entry> 
                  <name>algoname</name> 
                  <value>DES</value> 
              </entry> 
          </init-options> 
      </user-manager> 
  </realm> 
       
	<login-module-configuration> 
          <!-- realm name for which this login module will be used --> 
          <realm-name>siteminder</realm-name> 
          <!-- Configuration for this login module --> 
          <config-entry> 
              <!-- LoginModule class to be used for authentication --> 
              <class-name> 
			com.pramati.web.sso.siteminder.SiteMinderLoginModule 
		 </class-name> 
              <!-- flag for LoginModule --> 
              <flag>optional</flag> 
              <!-- options define the Map of key-value pair which will  
		 be passed to the initialize method of the class. --> 
              <options> 
              </options> 
          </config-entry> 
      </login-module-configuration>