Cams Web Agent Guide

Sun ONE 6.1 Web Agent Integration

Cams web agents are integrated into web and application servers to protect the resources that they provide. When a user's web browser makes a request to a web or application server, the Cams web agent asks a Cams policy server if access is granted or denied. The Cams web agent enforces the decision, possibly prompting the user for authentication if required.

This document provides instructions on how to install and configure the Cams Sun ONE 6.1 web agent, which is an Sun ONE version 6.1 NSAPI plugin available for the following operating systems and hardware architectures:

Solaris 8 for sparc

If you need support for another operating system or hardware architecture, please contact Cafésoft support.

NOTE: For known issues with the Cams Sun ONE 6.1 web agent, see ReleaseNotes.html found in the root directory of the Cams Sun ONE 6.1 web agent distribution.

Installation and Configuration Overview

The Sun ONE 6.1 web server management environment includes an "Administration Server" and one or more web server instances. Each web server instance is configured and managed independently, providing access to content and web applications for one or more "Virtual Hosts".

From the perspective of the Cams Sun ONE 6.1 web agent, the key characteristics of this environment are:

A central directory is used to make NSAPI plugins available to all web server instances
Each web server instance runs in its own multi-threaded process
Each web server instance may be configured independently to use (or not use) available NSAPI plugins
Each web server instance has its own log files
Each web server instance manages its own set of web applications

The Cams Sun ONE 6.1 web agent is designed to install within this environment. The installation script included with the agent distribution can be used to:

Install/uninstall the Cams Sun ONE 6.1 web agent NSAPI plugin and related libaries
Install/uninstall configuration and resource files to selected Sun ONE 6.1 web server instances
Install/uninstall the 'cams' web application, which provides sample login and test pages
View installed Cams Sun ONE 6.1 web agent components and configuration directives

Once agent files are installed using the installation script, various web server-specific configuration files will also need to be edited using a text editor. Installation and configuration of the Cams Sun ONE 6.1 web agent is summarized by the following steps:

1. Install the NSAPI plugin and related libraries into the central library directory (script)

For each Sun ONE 6.1 web server instance where you'd like to use Cams:

2. Install the cams-webagent.conf file and resource files into the "config" directory (script)

3. Install the "cams" web application into the "webapps" directory (script)

4. Edit the "magnus.conf" file to register the Cams Sun ONE 6.1 web agent NSAPI plugin (text editor)

5. Edit the "obj.conf" file to register a Cams Sun ONE 6.1 web agent function (text editor)

6. Edit the "server.xml" file to register the 'cams' web application (text editor)

7. Edit the "cams-webagent.conf" file to configure the Cams web agent (text editor)

NOTE: Before starting the Cams Sun ONE 6.1 web agent installation, you should install and configure the Cams Policy Server according to the Cams Administrator's Guide.

Installation

These instructions guide you through the installation of the Cams Sun ONE 6.1 web agent. Prerequisites for installation include:

Installing the Sun ONE 6.1 web server and lates service pack (SP2)
Installing and configuring the Cams Policy Server according to the Cams Administrator's Guide
Identifying the root directory where your Sun ONE 6.1 web server is installed
Downloading the Cams Sun ONE 6.1 web agent for your operating system and hardware architecture

To identify your Sun ONE web server version, open a Unix shell, change directories to the location where Sun ONE web server binaries are installed, and use the "webservd -V" command. For example, if your Sun ONE web server is installed in directory tree /opt/SUNWwbsvr :

% cd /opt/SUNWwbsvr/bin/https/bin
% ./webservd -v

You should see a line that looks something like this:

Sun ONE Web Server 6.1SP2 B04/07/2004 16:09

NOTE: Please contact Cafésoft support if you have questions on supported Sun ONE web server versions and platforms.

Unpacking Distribution Files

The name of your downloaded Cams Sun ONE 6.1 web agent distribution file will vary by release, so substitute your file name in the instructions that follow.

Copy cams-webagent-sunone61-solaris-sparc-3.0.X.tar.gz to a temporary directory on the target host. You must login as root and navigate to the directory where you copied the cams-webagent-sunone61-solaris-sparc-3.0.X.tar.gz file and unpack it into the temporary directory.

cd /tmp
gunzip cams-webagent-sunone61-solaris-sparc-3.0.X.tar.gz
tar xvf cams-webagent-sunone61-solaris-sparc-3.0.X.tar

Change directories to cams-webagent-sunone61-solaris-sparc-3.0.X. The files shown in Figure 1 should have been extracted from the distribution.

<!-- Cams Sun ONE 6.1 web agent documentation and license -->
install-webagent.sh
LICENSE
README.txt
ReleaseNotes.html

<!-- Cams web application files -->
webapps/cams/camstest.jsp
webapps/cams/login.jsp
webapps/cams/WEB-INF/web.xml

<!-- Cams Sun ONE 6.1 web agent configuration files -->
conf/access-control.properties
conf/cams-webagent.conf  
conf/webagent.properties

<!-- Cams Sun ONE 6.1 web agent libraries -->
lib/libapr-0.so.0.9.5
lib/libcams.so.0
lib/libcamsclient_mt_cams_3_0.so.0
lib/libcams-common.so.0
lib/libcams-webagent-sunone61.so
lib/libcscore.so.0
lib/libcsconv_iconv_1_0.so
lib/libcscrypto.so.0.9.7
lib/libcrypto.so.0.9.7
lib/libssl.so.0.9.7

Figure 1 - Directory listing of the Cams Sun ONE 6. 1 web agent files after unpacking

Installing the Agent

The target directories into which agent files will be copied by the installation script depends on where your Sun ONE 6.1 web server environment is installed and the web server instances that have been created. Assuming that your Sun ONE 6.1 web server is installed in a directory tree at /opt/SUNWwbsvr and you have one web server instance named "www.myserver.com", files will be copied to the following locations:

/opt/SUNWwbsvr/bin/https/lib - the agent NSAPI plugin and libraries
/opt/SUNWwbsvr/https-www.myserver.com/config - the agent configuration and resource files
/opt/SUNWwbsvr/https-www.myserver.com/webapps - the 'cams' web application directory tree

To run the installation script, use the following commands:

cd /tmp/cams-webagent-sunone61-solaris-sparc-3.0.X/
./install-webagent.sh

Follow the prompts to provide required information, install the Cams web agent libraries and install a Cams web agent configuration to one or more web server instances. After running the installation script, you'll still need to edit the following files in the config directory for each web server instance where an agent configuration was installed:

cams-webagent.conf
magnus.conf
obj.conf
server.xml

More details on how to edit these files is provided below.

Cams Web Agent Configuration

The Cams Sun ONE 6.1 web agent is configured using the cams-webagent.conf file. However, you'll also need to edit your Sun ONE 6.1 web server's magnus.conf, obj.conf and server.xml files to register the Cams Sun ONE 6.1 web agent module and integrate Cams login and test pages.

NOTE: To secure resources on your Sun ONE 6.1 server, you'll also need to configure a Cams security domain. See the Cams Policy Server Configuration section in this document for more information.

Editing cams-webagent.conf

Open the cams-webagent.conf file in a text editor. The file contains comments to help you understand the property values that you may need to change. You can also reference more detailed information on the properties in the Configuration Properties document.

NOTE: The most important properties are at the top of cams-webagent.conf. In most cases, the default property values will work if the Cams policy server and Cams web agent are on the same host. As you begin to integrate more web and application servers, reference Configuration Properties to understand the properties that will usually be the focus of your attention.

Editing magnus.conf

When a Sun ONE Web Server starts up, it reads a file named magnus.conf in its "config" directory to establish a set of global variable settings that affect the server’s behavior and configuration. The Cams Sun ONE 6.1 web agent NSAPI plugin and entry point functions must be registered in this file by using a directive like the one shown in Example 1 below.

NetsiteRoot /opt/SUNWwbsvr
ServerName www.myserver.com
ServerID https-www.myserver.com
#
RqThrottle 128
DNS on
Security off
PidLog /opt/SUNWwbsvr/https-www.myserver.com/logs/pid
User webservd
StackSize 131072
TempDir /tmp/https-www.myserver.com-9d93b4d6
#
Init fn=flex-init access="$accesslog" 
  format.access="%Ses->client.ip% - %Req->vars.auth-user% [%SYSDATE%] \"%Req->reqpb.clf-request%\" 
  %Req->srvhdrs.clf-status% %Req->srvhdrs.content-length%"
Init fn="load-modules" shlib="/opt/SUNWwbsvr/bin/https/lib/libj2eeplugin.so" shlib_flags="(global|now)"
Init fn=load-modules shlib=/opt/SUNWwbsvr/bin/https/lib/libcams-webagent-sunone61.so 
  funcs=CamsSunOne61WebAgent-init,CamsSunOne61WebAgent-pathCheck
Init fn=CamsSunOne61WebAgent-init CamsWebAgentHome="/opt/SUNWwbsvr/https-www.myserver.com"

Example 1 - Cams Sun ONE 6.1 web agent directives to be added to the magnus.conf file

When editing magnus.conf be sure to:

Substitute /opt/SUNWwbsvr with the path to your Sun ONE 6.1 web server root directory
Add these lines as the last "Init" directives in this file
Make sure that if a directive spans multiple lines (like the first Cams directive), that continued lines start with a space or tab character

Editing obj.conf

The file obj.conf contains instructions that tell the web server how to process HTTP requests received from clients. Each instruction is enacted either during server initialization or during a particular stage of the request-handling process. Each instruction invokes a Server Application Function (SAF). The Cams Sun ONE 6.1 web agent is invoked by the web server via an SAF for every HTTP request.

To register the Cams Sun ONE 6.1 web agent SAF, add the directive shown in Example 2 below:

<Object name="default">
AuthTrans fn="match-browser" browser="*MSIE*" ssl-unclean-shutdown="true"
NameTrans fn="ntrans-j2ee" name="j2ee"
NameTrans fn=pfx2dir from=/mc-icons dir="/opt/SUNWwbsvr/ns-icons" name="es-internal"
NameTrans fn=document-root root="$docroot"
PathCheck fn=unix-uri-clean
#PathCheck fn="check-acl" acl="default"
PathCheck fn=find-pathinfo
PathCheck fn=find-index index-names="index.html,home.html,index.jsp"
PathCheck fn=CamsSunOne61WebAgent-pathCheck
ObjectType fn=type-by-extension
ObjectType fn=force-type type=text/plain
Service method=(GET|HEAD) type=magnus-internal/imagemap fn=imagemap
Service method=(GET|HEAD) type=magnus-internal/directory fn=index-common
Service method=(GET|HEAD|POST) type=*~magnus-internal/* fn=send-file
Service method=TRACE fn=service-trace
Error fn="error-j2ee"
AddLog fn=flex-log name="access"
</Object>

...

Example 2 - Cams Sun ONE 6.1 web agent directives to be added to the obj.conf file

When editing obj.conf be sure to:

Add the Cams PathCheck directive exactly as shown
Add the Cams PathCheck directive as the last PathCheck directive
If present, comment out the "check-acl" PathCheck directive. (NOTE: Cams replaces the access control and authentication functionality triggered by this directive).

Editing server.xml

Among other web server configuration options, server.xml specifies the web applications available to virtual servers. If you installed the 'cams' web application to provide login and test pages, you'll need to edit this file as shown in Example 3 below.

...
<VSCLASS id="vsclass1" objectfile="obj.conf" rootobject="default" acceptlanguage="off">
  <PROPERTY name="docroot" value="/opt/SUNWwbsvr/docs"/>
  <VS id="https-www.myserver.com" connections="ls1" mime="mime1" aclids="acl1" urlhosts="www.myserver.com" state="on">
    <PROPERTY name="docroot" value="/opt/SUNWwbsvr/docs"/>
    <USERDB id="default"/>
    <SEARCH>
      <WEBAPP uri="/search" path="/opt/SUNWwbsvr/bin/https/webapps/search" enabled="true"/>
    </SEARCH>
    <WEBAPP uri="/cams" path="/opt/SUNWwbsvr/https-www.myserver.com/webapps/cams" enabled="true"/>
    <WEBAPP uri="/webapp1" path="/opt/SUNWwbsvr/https-www.myserver.com/webapps/webapp1" enabled="true"/>
    <WEBAPP uri="/webapp2" path="/opt/SUNWwbsvr/https-www.myserver.com/webapps/webapp2" enabled="true"/>
    <WEBAPP uri="/webapp3" path="/opt/SUNWwbsvr/https-www.myserver.com/webapps/webapp3" enabled="true"/>
  </VS>
</VSCLASS>
...

Example 3- cams web application directives to be added to the server.xml file

When editing server.xml be sure to:

Add the /cams WEBAPP directive exactly as shown
Add the /cams WEBAPP directive after the </SEARCH> tag, but in any order with other WEBAPP directives

Java Server Pages

The distribution webapps/cams directory is a J2EE compliant webapp that includes four sample Java Server Pages (JSP) for user interaction:

camstest.jsp - facilitates integration testing
login.jsp - displays a login page if a protected resource request is made and the user's identity is not known

For information on how to customize these pages, see Scripts. For information on how to configure the Cams web agent to redirect to these pages, see Configuration Properties.

NOTE: The camstest.jsp page is extremely useful for integration testing. You use it to quickly confirm correct Cams web agent communications with a Cams policy server, validate authentication configuration and determine if expected user session values are available in the web environment for authenticated users.

Using Server-Parsed HTML

If your site makes use of server-parsed HTML (See the Sun ONE Web Server 6.1 Administrator Guide), one client HTTP request can trigger multiple "internal" HTTP requests within your web server. These "internal" HTTP requests can cause the Cams Sun ONE 6.1 web agent to reject "internal" HTTP requests because they already contain Cams HTTP request headers from the original "parent" request.

If you find that server-parsed HTML is not working, set the following value in cams-webagent.conf:

cams.http.headers.accept.proxied=true

This will cause the Cams web agent to accept HTTP request headers that were inserted when the original "parent" resource was processed as long at the appropriate "proxy signature" header is also available.

Cams Policy Server Configuration

Before you start a web server with a Cams Sun ONE 6.1 web agent, you'll need to ensure that the Cams policy server knows about it. See the Cams Administrator's Guide - Integration Quick Start to learn more. Pay close attention during integration to steps 4 and 5, which provide information on the settings that must be configured correctly for a Cams web agent to connect to a Cams policy server. You'll need to configure an access control policy corresponding to your site requirements.

Testing

That's it, you should now be able to start your Sun ONE web server to test your Cams Sun ONE 6.1 web agent configuration. After you've started both the Sun ONE web server with the Cams Sun ONE 6.1 web agent and the Cams policy server, test the configuration using:

http://[hostname:port]/cams/camstest.jsp

Login to an account in the security domain that you've established. See the test page for more configuration and testing information.

Debugging

Debugging information is available in the following web server-specific log files:

The Sun ONE 6.1 web server errors log file (https-server_id/logs/errors)
The Cams web agent cams-webagent.log file (https-server_id/logs/cams-webagent.log)

During Cams web agent integration, it is helpful to set the following values in cams-webagent.conf:

cams.debug=true
cams.cluster.debug=true

If the Cams web agent is successfully loaded and initialized, verbose DEBUG messages will be logged to cams-webagent.log. If the Cams web agent fails to load or initialize, errors will be reported in the https-server_id/logs/errors file. In most cases, errors will be cause by misconfigured values in magnus.conf, obj.conf and/or cams-webagent.conf.

WARNING: Remember to disable all Cams web agent debug flags for production environments. Leaving them enabled will decrease performance and result in very large log files.

Installation Management

The installation script (install-webagent.sh) provides a way to query and remove the installed Cams Sun ONE 6.1 web agent files and configuration directives for a selected Sun ONE 6.1 web server. After starting the installation script (as you would for initial installation) and identifying the Sun ONE 6.1 web server executable you will be prompted by the following menu:

[INFO] - Cams Sun ONE 6.1 Web Agent installation management options
================================================================================
1 - Install Cams Sun ONE 6.1 Web Agent
2 - Uninstall Cams Sun ONE 6.1 Web Agent
3 - Query installed Cams Sun ONE 6.1 Web Agent files and settings
E - Exit

[????] - Choose an option:

Simply choose management option 2 for installation and 3 for a report specific to your installed options or configuration settings will display.

NOTE: During Cams Sun ONE 6.1 web agent removal, the script will give you the opportunity to save (or leave in place) the cams-webagent.conf and the Cams login and test scripts for future use or reference.

WARNING: After the Cams Apache 2.0 web agent files have been removed, you must remove (or comment out) the changes you made to the Sun ONE 6.1 web server's magnus.conf, obj.conf and server.xml files, which register the Cams Sun ONE 6.1 web agent module and integrate Cams login and test pages. See Cams Web Agent Configuration for more information on configuration changes you may have made.

Back | Next | Contents