Sun ONE Identity Server J2EE Agent Guide: Chapter 4 Policy Agent for Sun ONE Application Server 7.0

Previous Contents Next

Sun ONE Identity Server J2EE Agent Guide

Chapter 4 Policy Agent for Sun ONE Application Server 7.0

This chapter describes how to install and configure Sun ONE Identity Server Policy Agent for Sun ONE Application Server 7.0 running on Solaris 8, Solaris 9 and Windows 2000 Server platforms. Topics include:

Overview

Limitations

Installing the Agent

Application Configuration

Agent Configuration

Uninstalling the Agent

Overview

The Sun ONE Identity Server Policy Agent for Sun ONE Application Server consists of two main components that affect the operation of Application Server as well as the behavior of the protected application. These components are:

Agent Realm. The Agent Realm component provides the ability to Application Server to interact with Identity Server's user and role information. This acts as the core of the Agent and has to be configured correctly in order for the Agent to function.

Agent Filter. The Agent Filter component provides the ability to the hosted application to enforce Sun ONE Identity Server based authentication and is responsible for creating the Security Principal associated with the logged on user. Every application that has to be protected by the Agent must have its Deployment Descriptors changed to reflect that it is now configured to use the Agent Filter component. Applications that do not have this setting will not be protected by the Agent and may malfunction or become unusable if deployed on a Application Server where the Agent Realm component is installed.
Together, the Agent Realm and Agent Filter components work in tandem with Identity Server and enforce authentication and authorization for clients trying to access protected J2EE Applications.

Limitations

The Sun ONE Identity Server Policy Agent for Sun ONE Application Server 7.0 is designed to enforce authentication and authorization for clients that interact with the application through the application server's web container. Typically, such clients are thin clients like web browsers that communicate with the application server's web container using the HTTP or HTTPS protocols.
When a client requests an application resource by accessing a URL of the application, the Agent Filter component intercepts such requests and enforces authentication as necessary. Once the client is authenticated, the Agent Realm component works with the application server to authorize the authenticated client for accessing a particular resource within the hosted application like an Enterprise JavaBeans component. Alternatively, for security aware applications that use the programmatic J2EE security APIs provided in the web container and Enterprise JavaBeans container, the Agent Realm component provides the underlying support necessary in order that such APIs respond to the caller correctly by evaluating the currently authenticated user's credentials.
If however, the client does not access the application via the HTTP or HTTPS protocol, thereby bypassing the web container of the application server, the Agent Filter component will not intercept the request. This is a likely case when the application is being accessed by a rich client using other protocols like RMI over IIOP etc. Since the Agent Filter component which resides in the web container is bypassed in such cases, the authentication cannot be enforced. Clients that do not get authenticated by the Agent Filter do not possess sufficient credentials for the Agent Realm component to evaluate the necessary J2EE security policies. Therefore, such clients will be denied access to all protected resources. Alternatively, for security aware applications that use the programmatic J2EE security APIs provided in the application server will be given negative results by such APIs.

Installing the Agent

The Sun ONE Identity Server Agent for Sun ONE Application Server 7.0 may be installed on platforms—Solaris 8, Solaris 9, or Windows 2000 Server. The following sections provide the detailed steps necessary for installing the Agent on each of these platforms.

Pre-installation Tasks

The following tasks must be completed before the Agent can be installed:

Install Sun ONE Application Server 7.0

Refer Sun ONE Application Server documentation for the necessary details. When the server is installed, test the installation by using the provided sample Applications to ensure that the server is installed correctly.

Test the deployment of application that you intend to protect

Before installing the Agent, it is important that the application that must be protected be deployed and tested for simple functionality. Once it is established the application can be deployed successfully, you are ready to install the Agent.

Stop the Application Server instance on which you want to install the Agent.

Stop the Application Server instance using the following command: /S1AS_Install_Dir/appserv/domains/domain-instance/server-instance/bin/stopserv

Launching the Installer on Solaris Platform

The binaries for Sun ONE Identity Server Policy Agent for Sun ONE Application Server 7.0 for Solaris 8 and Solaris 9 platform is provided as a tar-gzip archive. Copy this archive on the machine where Sun ONE Application Server is installed. Perform the following steps to launch the installation program:

Login as root.

Unzip the binary archive in a convenient location using the following command:

# gzip -dc as70agent-1.0-domestic-us.sparc-sun-solaris2.8.tar.gz | tar xvf -

Set your JAVA_HOME environment variable to JDK version 1.4.0 or higher. If your system does not have the required version of JDK, use the JDK supplied with Sun ONE Application Server 7.0. This JDK is located under:

S1AS_Install_Dir/jdk

The installer provides two types of interfaces—a graphical user interface (GUI) and a command line interface. In most cases, the GUI installer can be used for installing the Agent. However, in cases when you are installing the Agent over a telnet session on a remote server and do not have windowing capabilities, then the GUI installer cannot be used. In such a case it is recommended that you use the command line installer for installing the Agent. This can be launched by executing the setup script and passing in a command line argument -nodisplay as follows:

# ./setup -nodisplay

However, if you choose to use the GUI installer, then it is required that you set your DISPLAY environment variable to ensure that the GUI installer window appears on the correct console.

.

Note If you choose to use the command-line based installer using the -nodisplay option, you may skip the following step and proceed directly to the next section, which details out the installation procedure.

Launch the GUI installer by invoking the setup script as follows:

# ./setup

The installer requires that you setup your JAVA_HOME variable correctly as pointed out in the Step 3. However, in case you have incorrectly set the JAVA_HOME variable, the setup script will prompt you for supplying the correct JAVA_HOME value:

Enter JAVA_HOME location (Enter "." to abort):

Type the full path to the Sun ONE Application Server JDK installation directory for launching the installation program. Otherwise, enter a period (.) to abort the installation.

In order that the GUI installer be displayed on your console, the DISPLAY environment variable of your shell must be set correctly. If your DISPLAY environment variable is not set at the time of invoking the setup script, the installer will prompt you for the DISPLAY environment variable value as follows:

Please enter the value of DISPLAY variable (Enter "." to abort):

Provide the DISPLAY value by typing the exact value at the above prompt. Otherwise, enter a period (.) to abort the installation.

Note You can also use agent_platform.class file to install the agent. You can find this file in the directory where you have untarred the binaries.

Launching the Installer on Windows 2000 Server

The binaries for Sun ONE Identity Server Policy Agent for Sun ONE Application Server 7.0 for Windows platform are provided as a zip archive. Copy this archive on the machine where Application Server server is installed. Perform the following steps to launch the installation program:

You must have administrative privileges when you run the installation program. If you do not have administrative privileges, either log on as the "Administrator" user or request such privileges to be granted to your account by the system administrator of the machine or domain as applicable.

Unzip the Agent binaries in a convenient location. This may be done by using any Zip utility available on your system.

The above operation results in two executable files setup.bat and setup.exe, which may be used to launch the installer. Each of these two files provide different features for launching the installer. You can choose either of these two files depending upon your installation requirements.

Using setup.bat

In order to use the setup.bat file to launch the installer, you must have JDK version 1.4.0 or higher. This can be verified by typing the following command in a command prompt window:

C:\> java -version

java version 1.4.0_01

Java(TM) 2 Runtime Environment, Standard Edition (build 1.4.0_01-b03)

Java HotSpot(TM) Client VM (build 1.4.0_01-b03, mixed mode)

If you do not have JDK of required version in your system path, you can use the JDK supplied with Application Server 7.0 located at:

S1AS_Install_Dir\jdk

The setup.bat can be executed by typing the file name at the command prompt window in a directory where it is present, or by double clicking the file in Windows Explorer. For example:

C:\>setup.bat

The installer provides two types of interfaces—a graphical user interface (GUI) and a command line interface. By invoking the setup.bat file from a command prompt window or by double clicking the file in Windows Explorer, the installer is launched in the GUI mode. To launch the installation program with the command line argument -nodisplay, type the following:

C:\>setup.bat -nodisplay

Using setup.exe

You can invoke setup.exe either from the command prompt window or by double clicking the file from Windows Explorer. Unlike setup.bat, setup.exe does not take the -nodisplay command line argument and can launch only the GUI installer.

Note Since the command line installer cannot be launched using setup.exe, in cases where the command line installer is required, it is recommended that you use setup.bat to launch the command line installer.

Installing the Agent Using GUI

The installation program begins with a Welcome screen. Click Next to step through the installation screens, answering the questions.

Read the License Agreement. Click Yes (Accept License) to continue with the Installation.

If you do not accept all the terms of the Software License Agreement, click No to end the Installation program without installing the product.

In the Select Installation Directory screen, enter the path where you want to install.

If you wish to install the Agent in a directory different from the default directory, click the Browse button and choose the directory. Once you have selected the appropriate directory, click the Next button to proceed to the next screen.

Note If you select a directory that does not exist on your system, the installer will prompt you to specify if the new directory should be created. You can either choose to create this new directory by clicking on the Create Directory button or select a new directory by clicking on the Choose another Directory button.

In the Select an Agent screen, select the component you wish to install in this by selecting the check box against the component name. The only component available for installation is the Sun ONE Identity Server Policy Agent for un ONE Application Server 7.0, which is selected by default.

Note
For a given system, only one installation of Sun ONE Identity Server Policy Agent for Sun ONE Application Server 7.0 is allowed at a time. If a previous installation of the Agent has not been removed completely from this system, the selection box will be disabled and no selections can be made. In that case it is recommended that you exit the installer by clicking the Exit button and remove the previous installation completely before starting the install again.

Figure 4-1    Component Selection Screen

In the Sun ONE Identity Server Information screen, provide the following information about the Sun ONE Identity Server and click Next.
Figure 4-2    Sun ONE Identity Server Information Screen

Sun ONE Identity Server Host: Enter the fully qualified host name of the system where Sun ONE Identity Server is installed.

Sun ONE Identity Server Port: Enter the port number for the Web Server that runs Sun ONE Identity Server Services.

Sun ONE Identity Server Protocol: Select the protocol that will be used by the Agent to communicate with Sun ONE Identity Server services. This protocol may either be HTTP or HTTPS.

Sun ONE Identity Server Deployment URI: Enter the URI that should be used for accessing Sun ONE Identity Server Services.

amAdmin Password: Enter the password for amAdmin user.

Re-enter Password: Re-enter the password for amAdmin user for confirmation.

Note The password supplied during installation is recorded by the Agent in a secure manner. However, if in the future you change this password in Identity Server, you will have to update the password in the Agent as well. This can be done by using the agentadmin tool provided with the Agent. Once the Agent has been installed on the system, the agentadmin tool can be invoked from the location: Agent_Install_Dir/SUNWam/asAgent/bin/agentadmin
The agentadmin tool is available as agentadmin.bat on the Windows platform.
To change the password, invoke this tool as follows:
#./agentadmin -password oldpassword newpassword

In the Directory Information screen, provide the following information about the Directory Server that is associated with Sun ONE Identity Server services.
Figure 4-3    Directory Information Screen

Directory Host: Enter the fully qualified host name of the system where the Directory Server is installed.

Directory Port: Enter the port number used by the Directory Server.

Root Suffix: Enter the root suffix to be used with this Directory Server.

Installation Organization: Enter the name of the installation organization as used when installing the Sun ONE Identity Server.

In the Sun ONE Application Server Details screen provide the following information about the Sun ONE Application Server on which the Agent is installed.
Figure 4-4    Sun ONE Application Server Details Screen

Sun ONE Application Server config Directory: Enter the full path to the location of the config directory of the Application Server instance.

Sun ONE Application Server JAVA_HOME directory: Enter the full path to the location of the JDK installation home used by the Sun ONE Application Server.

Name of the Agent Realm: Enter the name of the Realm that will be configured as the default realm to be used by Sun ONE Application Server.

The Sun ONE Application Server config directory is used to modify server.xml, login.conf and server.policy under this directory. Default location is the following directory:

S1AS_Install_Dir/appsrv/domains/domain-instance/server-instance/config

The Sun ONE Application Server JAVA_HOME directory refers to the JDK installation that is used by the Sun ONE Application Server. Typically the value of this is the full path to the following directory:

S1AS_Install_Dir/jdk

In case the value supplied is incorrect or is not the JDK used by the Application Server, it will result in malfunction of the Agent. To avoid this problem, ensure that the value you specify for Sun ONE Application Server JAVA_HOME is accurate.

Caution

The installation program modifies the Application Server's server.xml file to include certain libraries in the Application Server CLASSPATH, as well as adds certain required parameters to the JVM options. Also it add the Agent Realm and makes it default Realm to be used. If you specify an incorrect value for the config directory, the necessary classes and parameters will not get added, resulting in malfunction of the Agent, which can render the Sun ONE Application Server unusable. To avoid this problem, ensure that the value you specify for Sun ONE Application Server config directory is accurate.

The Installer modifies the Application Server's login.conf file to define LoginModule for the jaas-context.

The Installer modifies the Application Server's server.policy to give ProgramaticLogin permission to agent-filter.jar.

In the Agent Configuration Details screen provide the key configuration information necessary for the Agent to function correctly.
Figure 4-5    Agent Configuration Details Screen

Audit Log File: Enter the complete path to the log file to be used by the agent to record Audit messages.

Enable Audit log file Rotation: Select this item to enable rotation of Audit Log files.

Host URL: Enter a valid URL to be used as the base URL by the Agent to redirect users as necessary. This value may be left blank.

Login Attempt Limit: Enter the number of unsuccessful access attempts in succession after which the user will not be allowed to access the requested URL temporarily for security purposes. Specify the value 0 to disable this feature.

Enable Not-Enforced List Cache: Select this item to enable caching of Not-Enforced List evaluation results.

Number of Entries in Cache: Specify the number of entries that cache can hold at a given instance.

Cache Expiration Time: Specify the time in seconds to be used as the limit for entries that can exist in the Not-Enforced List cache.

Enable LDAP Attribute Headers: Select this item to enable the passing LDAP attributes associated with the current user as HTTP Headers.

Important Tips

The Audit Log file is a necessary requirement for the Agent. You may provide the name of a non-existing file on the system to be used as the Audit file. In which case, the Agent creates this file and the necessary directories in its path on first use. Alternatively, you can provide the file name of an existing file, which can be used by the Agent as well. However, in either case, it is required that the specified file has write permissions for the Application Server process. This is because the Agent executes in the same process as the Sun ONE Application Server. Providing an incorrect value for this will result in the malfunction of the Agent, which can render the Application Server unusable.

When a request is intercepted by the Agent without sufficient credentials, the Agent redirects the user to the Identity Server's authentication service. Along with this redirect, the Agent also passes information regarding the original request to the authentication services, which is used to redirect the user back to the original requested destination. A part of this request is the Host URL that is used to identify the web container/server which the user was originally trying to access. This Host URL can be specified by setting the Host URL value on this screen. If the Host URL value is left blank, the Agent reconstructs the original Host URL from the request and uses that when redirecting the user to authentication service. The implication of having a Host URL is that no matter which web container/server that the user was originally trying to access, the user will be sent to the specified Host URL after successful authentication. While this configuration value can be used to override the default behavior, an incorrect value may lead to the application becoming inaccessible. It is therefore recommended that this value be left empty unless there is a specific need based on the deployment scenario, which calls for setting this value appropriately.

The Login Attempt Limit feature can be used to guard the hosted application from Denial-Of-Service attacks where the end user can overload the application server by repeated authentication requests. By disabling this feature, the system remains vulnerable to such attacks. Therefore this feature should not be disabled unless there is a specific requirement necessitates the disabling of this feature.

When the Agent must process a large list of Not-Enforced pattern rules specified in the configuration, every incoming request must be evaluated against every such rule to determine if the request can be allowed without authentication or not. In scenarios where the user load is high, the time spent in evaluating these rules can add up and degrade the overall performance of the system. To avoid this problem, it is recommended that Not-Enforced List Cache be enabled.

Enabling the Not-Enforced List Cache may result in degraded performance if the values for Number of Entries in Cache and Cache Expiration time are not set up appropriately. In case when the cache expiration time duration is more than necessary, the cache will get filled up very fast and new requests will still be evaluated against all the specified pattern rules, resulting in no improvement in performance of the system. If the Number of Entries in Cache is set very high, it may result in excessive consumption of system memory, thereby leading to degraded performance. Therefore, these values must be set up after careful deliberation of the deployment scenario and should be changed as necessary to reflect changing usage scenario of the system. It is recommended that the system be tested with various values of these two parameters in a controlled environment to identify the optimal values, and only then be deployed in production.

By enabling the LDAP Attribute Headers, for every incoming request, the Agent must retrieve the LDAP Attributes associated with the authenticated user and add them as Header values in the request. This feature should be used only in the case when the deployed application requires these header values for business logic implementation. Turning this feature on without an appropriate need will result in performance degradation of the system that can be easily avoided.

In the Summary screen review and verify the installation options that you have specified for the Agent. In case you find that certain values are in error, you may navigate back and correct them before proceeding further. Click the Next button to proceed with the installation.
Figure 4-6    Summary of all the selections Screen

In the Ready to Install screen, click the Install Now button to begin the installation.

The Install Progress screen displays the progress of the installation as the installer makes changes to your system. If necessary, you may interrupt this process by clicking the Stop button.

Note It is strongly recommended that you do not interrupt this process as this may lead to a partially installed product, which may also cause problems with uninstall, and may as well render the Application Server unusable. This process should be interrupted only in cases where it is absolutely necessary to do so.

In the Installation Summary window, click Details for a detailed summary of the configuration information that was processed during installation. Click Exit to end the program.

Note
If the status of the installation is "Failed", you must view the log file for the install by clicking on the Details button to identify which installation task failed. In this situation, you may uninstall the Agent and try again after fixing the root cause of failure during this installation.

The Agent installation program modifies the Application Server's server.xml file to include certain libraries in the Application Server CLASSPATH, as well as adds certain required parameters to the JVM options. For the changes to take effect you must configure application server, which can be done by following either of these methods:

To apply changes to application server instance using the Administration interface, perform the following steps:

Access the Administration interface and click the name of the application server interface you want to reconfigure.

Click the General tab.

Click Apply Changes.

When the changes are applied, the screen displays a message.

To configure an application server instance using the command-line interface, execute the following command:

asadmin reconfig -u admin -w password -H hostname -p admin-port --keepmanualchanges=true server-instance

Note asadmin is located at S1AS_Install_Dir/bin directory.

Installing the Agent Using Command-Line

You must have root permissions when you run the agent installation program.

Run the setup program with the command line argument -nodisplay. You'll find the program in the directory where you untarred the binaries.

# ./setup -nodisplay

When prompted provide the following information:

Have you read, and do you accept, all of the terms of the preceding Software License Agreement? Type Yes.

Install Sun(TM) ONE Identity Server Agent in this directory: Enter the full path to the directory in which you want to install the Policy Agent.

The following text is displayed:

Sun(TM) ONE Identity Server Policy Agent components showing a checked box will be installed. Only one agent may be installed at a time.

[X] 1 Sun(TM) ONE Identity Server Policy Agent for Sun(TM) ONE Application S

Select a component [0] {"<" goes back, "!" exits}:

By default, 1 is already checked, type 0 or press enter key to install the Sun ONE Identity Server Policy Agent component.

Provide the following information about the Web Server that runs Identity Server:

Sun(TM) ONE Identity Server Host

Sun(TM) ONE Identity Server Port

Sun(TM) ONE Identity Server Protocol

Sun(TM) ONE Identity Server Deployment URI

amAdmin Password

Re-enter Password

For details on each of these items, see "Installing the Agent Using GUI."

Provide the following information about the Web Server that runs Identity Server Directory:

Directory Host

Directory Port

Root Suffix

Installation Organization

For details on each of these items, see "Installing the Agent Using GUI."

Provide the following information about the Sun ONE Application Server:

Sun(TM) ONE Application Server config Directory

Sun(TM) ONE Application Server JAVA_HOME directory

Name of the Agent Realm

For details on each of these items, see "Installing the Agent Using GUI."

Provide the configuration details for the installation of Sun ONE Identity Server Agent for Sun ONE Application Server.

Agent Audit Log File

Enable Audit log file Rotation

Host URL

Login Attempt Limit

Enable Not-Enforced List Cache

Enable LDAP Attribute Headers

For details on each of these items, see "Installing the Agent Using GUI."

When displayed, review the summary of the installation information you have specified. Press Enter to continue.

The following text is displayed:

Ready to Install

1. Install Now
2. Start Over
3. Exit Installation

When prompted, What would you like to do? Type 1 to start the installation.

The following text is displayed:

Installation details:

Product                                    Result     More Info

1.Sun_TM_ONE Identity Server Policy Agent  Installed  Available
2.Done

Enter the number corresponding to the desired selection for more information, or enter 2 to continue [2] {"!" exits}:

To see log information, type 1. To exit the Installation program, type 2.

Silent Installation

Silent installation provides a means for scripting the installation of Sun ONE Identity Server Policy Agent. When you perform a silent installation, you use a StateFile, to predefine all the answers that you would normally supply to the setup program interactively. This saves time and is useful when you want to install multiple instances of Sun ONE Identity Server Policy Agents using the same parameters in each instance.
Silent installation is a two-step process. First you generate a StateFile that contains all the parameter information the installation program needs. Then you run the silent installation program that automatically reads the parameters you've defined in the StateFile.

Silent Installation on Solaris

To Generate a StateFile

Run the installation program in the directory where the setup script is located. Enter the following command:

# ./setup -saveState StateFile

Proceed through the installation program, keeping in mind that your answers to the prompts are being recorded in the StateFile.

Follow the instructions given in the section "Installing the Agent Using GUI".

When installation is complete, the file StateFile is created in the same directory as setup.

To Run the Silent Installation

Enter the following command to run the silent installation:
# ./setup -nodisplay -noconsole -state StateFile

Silent Installation on Windows 2000

To Generate a StateFile

Run the installation program in the directory where the setup program is located. Open a DOS command prompt window and enter the following command:

setup.bat -saveState StateFile

Note As an alternative, you can use the following command:
java -classpath . agent_WINNT -saveState StateFile

Proceed through the installation program, keeping in mind that your answers to the prompts are being recorded in the StateFile.

Follow the instructions given in the section "Installing the Agent Using GUI".

When installation is complete, the file StateFile is created in the same directory as setup.exe.

To Run the Silent Installation

Type the following command:
setup.bat -nodisplay -noconsole -state StateFile

Note As an alternative, you can use the following command:
java -classpath . agent_WINNT -nodisplay -noconsole -state StateFile

Application Configuration

The Agent Realm component of Agent for Application Server 7.0 provides runtime mapping of various principals in Sun ONE Identity Server with abstract security role names used by the hosted application in order to determine if the currently authenticated user is authorized to access a particular resource or is otherwise a member of a given role. This runtime evaluation can occur only if the user is authenticated as a Sun ONE Identity Server principal by the means of Identity Server's authentication service. Without the user being authenticated appropriately, the results of such evaluations done by the Agent Realm will always be negative, resulting in access being denied to the user for the requested resource.
It is the Agent Filter component that enforces authentication for users who try to access particular application resources, thereby enabling the Agent Realm component to correctly evaluate the principal mappings as desired.
Unlike the Agent Realm component which is installed in the core of Application Server, the Agent Filter is installed in the deployed application, which must be protected by Identity Server. This is true for every application that must be protected on the Application Server using the Agent. It is also recommended that applications that are not protected using the Agent should not deployed on the Application Server on which the Agent Realm has been installed. This is to ensure that such applications can independently enforce their own security requirements as necessary. The presence of Agent Realm will interfere with the security evaluations done by such applications resulting in their malfunction.

Installing the Agent Filter Component in an Application

The Agent Filter can be installed by simply modifying the deployment descriptor of the application that needs to be protected. The following steps outline the process to install the Agent Filter component for a given application:

If the application is currently deployed on the Application Server, it must be removed using the Application Server's Administration Console or by the use of Application Server's deployment tools.

It is recommended that you create a backup of the deployment descriptor that will be edited in order to install the Agent Filter in this application.

Edit the application's web.xml deployment descriptor. Since the Filters were introduced in Servlet Specification 2.3, the web.xml's DOCTYPE element must be changed to reflect that the deployment descriptor is a Servlet 2.3 compliant deployment descriptor. This can be done by setting the DOCTYPE element as:

<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN" "http://java.sun.com/dtd/web-app_2_3.dtd">

After the DOCTYPE element has been changed, add the Filter elements in the deployment descriptor. This can be done by specifying the Filter element and the Filter-mapping element in the web.xml deployment descriptor immediately following the description element of the web-app element. The following is a sample web.xml with the Filter and Filter-mapping elements.

<web-app>

  <display-name>...</display-name>

  <description>...</description>

  <filter>

  <filter-name>Agent</filter-name>

  <display-name>Agent</display-name>

  <description>SunTM ONE Idenitity Server Policy Agent for SunTM ONE Application Server 7.0</description>

  <filter-class>com.sun.amagent.as.filter.AgentFilter</filter-class>

  </filter>

  <filter-mapping>

  <filter-name>Agent</filter-name>

  <url-pattern>/*</url-pattern>

  </filter-mapping>

  ...

  ...

</web-app>

Once the web.xml deployment descriptor has been modified to reflect the new DOCTYPE and filter elements, the Agent Filter has been added to the application.

Creating Role-to-Principal Mapping

Once the application has been configured to have the Agent Filter component in it, the Agent Filter will enforce authentication, thereby enabling the Agent Realm to successfully resolve the role-to-principal mappings. However, these mappings must first be created in order that the hosted application may use them during runtime.

To Create Role-to-Principal Mapping

Edit the Application Server specific deployment descriptors.

The Application Server specific deployment descriptors should be edited to create the role-to-principal mappings. These descriptors are in the files sun-application.xml and sun-ejb-jar.xml files. Refer Application Server reference documentation to learn the details on how these descriptors may be edited to create the role-to-principal mappings. Alternatively, you can refer Appendix C for sample descriptors which create such mappings.

Application-Specific Agent Configuration

Often the deployed applications are partitioned into public and protected parts, which have varying access restrictions. In most cases, the public portions of the application are accessible to anonymous users, whereas the protected portions of the application are accessible only to the registered users. The Agent can be configured to allow this type of access by letting anonymous users access the public portions of the application without requiring that they authenticate using Identity Server's authentication service. This information is provided as a part of the Agent's configuration properties file that is present in the following location:
Agent_Install_Dir/SUNWam/asAgent/amAgent/config/AMAgent.properties
This file may be edited to provide general as well as application-specific configuration for the Agent.
The properties specified in the AMAgent.properties file are required for the Agent to function properly. Invalid values specified in this file can lead to malfunction of the Agent, application becoming inaccessible, or the entire system to become unusable. It is recommended that you use extreme caution when modifying the values in this file and always create backups before such modifications to ensure that you can back out your changes to restore the system to its original state.

Note The properties specified in the AMAgent.properties file are loaded during the Application Server startup time. Any changes made to this file while the Sun ONE Application Server is running will not take effect until the server has been restarted.

Providing Application Specific Not-Enforced-List

In order to allow anonymous users to access portions of the application, the AMAgent.properties file must include an entry for the specific application. The entry that specifies this property is called the application not-enforced list and is identified by the string:
com.iplanet.amagent.config.filter.AppName.notEnforcedList[index]=pattern
This property requires that you format it correctly in order that it can be used by the Agent during runtime. The entries appearing in italics should be replaced by their appropriate values as follows:
AppName: This string should be replaced by the deployed application's context path. The context path is the first URI segment that is used to identify which application the user is trying to access. For example, if the user accesses your application by typing the URL:
http://myserver.mydomain.com/SomeApp/index.html or http://myserver.mydomain.com/SomeApp/SomeModule/doSometing.jsp
then, in both these cases, the AppName is SomeApp.
index: This is an integer value starting from 0 for every deployed application and is unique for every entry in the application not-enforced list. For example, the following are two entries of application not-enforced list for an application called with context path SomeApp:
com.iplanet.amagent.config.filter.SomeApp.notEnforcedList[0]=/public/*
com.iplanet.amagent.config.filter.SomeApp.notEnforcedList[1]=/images/*
pattern: This is a pattern string that will be matched with the incoming request to evaluate if the request should be allowed to pass without enforcing authentication or not. The pattern string could be a specific URI, for example /public/RegistrationServlet, or could be a generic pattern using the wild card character '*' that can be used for denoting 0 or more characters in the request URI; for example /public/* will match with any URI that begins with /public/.
Using this property, you could specify pattern strings and URIs that the Agent will treat as not-enforced. In other words, user requests that match these particular patterns will be allowed to pass through without enforcing authentication.

Providing Application-Specific Access Denied URI

In cases when the Login Attempt Limit is enabled (refer to section "Installing the Agent" for details on how this feature can be configured, or refer "Agent Configuration" for details on this feature), the Agent is required to block the user's access. The default behavior of the Agent in this situation is to send an HTTP Status Code 403 Forbidden. In such a situation, the web container can display its preconfigured Forbidden page or simply send the status code in which case the user's browser displays the details of the error message in its own manner. While this is the default behavior of the Agent, it can be changed to suit the needs of the application by allowing the Agent to use an application-specific URI that will be used as the access denied error page.
This can be done by setting the following property in AMAgent.properties file:
com.iplanet.amagent.config.filter.AppName.accessDeniedURI=/URI to use
This property requires that you format it correctly in order that it can be used by the Agent during runtime. The entries appearing in italics should be replaced by their appropriate values as follows:
AppName: This string should be replaced by the deployed application's context path. The context path is the first URI segment that is used to identify which application the user is trying to access. For example, if the user accesses your application by typing the URL:
http://myserver.mydomain.com/SomeApp/index.html or
http://myserver.mydomain.com/SomeApp/SomeModule/doSometing.jsp then, in both these cases, the AppName is SomeApp.
URI to use: is an application specific URI that the Agent will use to locate the display page for blocking the user request. This URI can be a static HTML page, or a JSP or even a Servlet. However, this URI must be a part of the application itself. In other words, this URI must begin with /AppName/rest of the URI.

Special Case: Default Web Application

A default web application in Application Server is accessible without providing any context path in the request URI. For example, the following URL is that of a default web application:
http://myserver.mydomain.com/index.html
Clearly, this URL does not have an associated context path.
For such applications, the Agent provides a convenient means of identifying that an entry is specific to the default web application. This is done in two steps as follows:

The following property is set to a name that represents the default web application:

com.iplanet.amagent.config.filter.defaultWebAppName=DefaultWebApp

This name is then used to specify the application not-enforced list as well as the application's access denied URI as follows:

com.iplanet.amagent.config.filter.DefaultWebApp.notEnforcedList [0]=/index.html

com.iplanet.amagent.config.filter.DefaultWebApp.notEnforcedList[1]=/about.html

com.iplanet.amagent.config.filter.DefaultWebApp.accessDeniedURI=/URLAccessDenied.html

Using this scheme, the default web application that does not have a context path associated with it, may be configured just like any other application that has a context path. The same rules apply to the default web application for specifying the not-enforced list entries and access-denied URI as are applicable for the rest of the application. However, the only difference is that the access-denied URI of the default web application as well as the not-enforced list entries do not begin with the /DefaultWebApp/ path segment since such a path segment does not exist on the application server in reality. It is only provided as a convenience to specify the properties associated with the default web application and not their values.

Global Agent Configuration

The AMAgent.properties file provides a way to specify a global not-enforced list, which will be applicable to all the deployed applications on the server. This list is specified by using the following property:
com.iplanet.amagent.config.filter.global.notEnforcedList[0]=pattern
where pattern is either an exact URI or a pattern specified by using the wild card character '*', which can be substituted for zero or more characters in the request URI.

Not-Enforced List Usage Considerations

Although the use of Not-Enforced List can be extremely helpful in partitioning your application for public and protected domains, it can also lead to undesirable effects if not used appropriately.
For example, if a request URI that represents a Servlet is matched by some not-enforced list pattern, then the Agent Filter will not enforce authentication for users who try to access that particular Servlet. However, consider the case where this Servlet access an Enterprise JavaBeans component that is protected by the Agent using role-to-principal mapping. In such a case, since the user is not authenticated, the access to the protected component will result in a an security violation exception being generated by the application server.
Therefore, before an entry is added to the not-enforced list, it must be ensured that it does in any way covers a resource that may be protected or may try to access a protected resource.
Another interesting aspect of the use of non-enforced list are the images. Typically, in a web page there are many images for various purposes like buttons, place holders, banners and logos. Every time the user accesses this page, the browser issues a request to the application server to get the images contained in this page. Each of such requests are treated as individual requests coming from the client and goes through the same evaluation mechanism for authentication and not-enforced list check as does any other request. This results in one client generating multiple calls to the server for displaying of a single page. Considering the overhead involved in enforcing authentication for every such request, it can impact the overall performance of the system. A solution to this problem is to have a global not-enforced list entry or entries that match all images. For example:
com.iplanet.amagent.config.filter.global.notEnforcedList[0]=*.gif
com.iplanet.amagent.config.filter.global.notEnforcedList[1]=/images/*
This indicates that any request URI that ends with .gif will be not enforced and nor will be any URI that begins with /images/. In heavy user load situations, this can significantly increase the performance of the system.

Agent Configuration

The file AMAgent.properites located at: Agent_Install_Dir/SUNWam/asAgent/amAgent/config directory provides the core configuration needed by the Sun ONE Identity Server Policy Agent for Sun ONE Application Server 7.0 to function correctly. This property file provides many configuration settings that can be modified in order to customize the Agent's operation for your deployment scenario. This section provides a brief explanation of all the properties that are listed in the properties file.
Before proceeding, it is important to note that this file and the information within it are critical for the operation of the Agent. It is strongly recommended that you always create backup of this file before modifying it. Also it is strongly recommended that you do not modify this file unless you it is absolutely necessary. Please note that invalid data entries present in this file can lead to the malfunction of the Agent, the malfunction of the deployed applications, and could render the entire system unusable.
The settings provided in this file can be classified as follows:

Common Configuration: Settings in this section are general settings that affect the behavior of the Agent as a whole.

Audit Configuration: These settings are exclusively used to configure the Audit Engine used by the Agent.

Global Filter Configuration: These settings are used to configure the Agent Filter component.

Application Filter Configuration: These settings are used to configure the Agent Filter for a particular application.

Debug Engine Configuration: These settings are used to configure the Debug Engine to generate diagnostic information.

Common Configuration

Organization Name

Key: com.iplanet.amagent.config.org
Description: This property specifies the organization name to be used when searching for principals in Identity Server.
Valid Values: A string that represents the organization name in Sun ONE Identity Server

Note This property is set during Agent installation and need not be changed unless absolutely necessary.

Example: com.iplanet.amagent.config.org=sun.com

Root Suffix

Key: com.iplanet.amagent.config.rootsuffix
Description: This property specifies the root suffix to be used when searching for principals in Sun ONE Identity Server
Valid Values: A string that represents the root suffix in Sun ONE Identity Server

Note This property is set during Agent installation and need not be changed unless absolutely necessary.

Example: com.iplanet.amagent.config.rootsuffix=o=isp

People Container Level

Key: com.iplanet.amagent.config.realm.peopleContainerLevel
Description: This property specifies the people container level to be used when searching for principals in Sun ONE Identity Server.
Valid Values: Non-zero unsigned integer representing the People Container Level in Identity Server, which may be used when searching for principals.

Note This property is set during Agent installation and need not be changed unless absolutely necessary.

Example: com.iplanet.amagent.config.realm.peopleContainerLevel=1

Audit Configuration

Language Code

Key: com.iplanet.amagent.config.audit.localeLanguageCode
Description: This property specifies the Locale for Audit log messages.
Valid Values: The localeLanguageCode must be a valid ISO Language Code. Default value of this property is en

Note For more information, refer ISO 639 specification:
http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt

Example: com.iplanet.amagent.config.audit.localeLanguageCode=en

Country Code

Key: com.iplanet.amagent.config.audit.localeCountryCode
Description: This property specifies the Locale for Audit log messages.
Valid Values: The localeCountryCode must be a valid ISO Country Code. Default value of this property is US.

Note For more information, refer ISO 3166 specification:
http://www.chemie.fu-berlin.de/diverse/doc/ISO_3166.html

Example: com.iplanet.amagent.config.audit.localeCountryCode=US

Audit Log File

Key: com.iplanet.amagent.config.audit.logfile.name
Description: This property specifies the Audit log file to be used for recording Audit messages.
Valid Values: String representing the complete path name of the file to be used by Agent to record Audit messages.

Note Be sure the Application Server process has sufficient permissions to write to this file. Invalid value specified for this property may result in the failure of the system to start up correctly.

Example: com.iplanet.amagent.config.audit.logfile.name=/var/opt/SUNWam/asAgent/audit/agent.log

Audit Log File Rotation Flag

Key: com.iplanet.amagent.config.audit.logfile.rotate
Description: This property specifies if the Audit log file should be rotated by the Agent.
Valid Values: true/false

Note Default value of this property is false and should be changed as necessary.

Example: com.iplanet.amagent.config.audit.logfile.rotate=false

Audit Log File Rotation Size

Key: com.iplanet.amagent.config.audit.logfile.rotate.size
Description: This property specifies the approximate size of the Audit log file in bytes, which should be used to evaluate when the log file needs to be rotated.
Valid Values: Non-zero unsigned integer indicating the size in bytes to be used to evaluate when the log file needs to be rotated.

Note Audit Log file rotation size is effective only when rotation flag is true.
Default value of this property is 52428800 bytes (~ 50 MB) and should be changed as necessary.

Example: com.iplanet.amagent.config.audit.logfile.rotate.size=52428800

Global Filter Configuration

SSO Token Name

Key: com.iplanet.amagent.config.filter.ssoTokenName
Description: This property specifies the name of the Cookie that represents SSO Token.
Valid Values: A string that represents the name of SSO Token Cookie issued by Sun ONE Identity Server authentication service.

Note This property is set during Agent installation and need not be changed unless absolutely necessary.

Example: com.iplanet.amagent.config.filter.ssoTokenName=iPlanetDirectoryPro

Login URL

Key: com.iplanet.amagent.config.filter.loginURL
Description: This property specifies the login URL to be used by the Agent to redirect incoming users without sufficient credentials to the Sun ONE Identity Server authentication service.
Valid Values: A string that represents the complete URL to be used as the redirect URL in order to send users without sufficient credentials to Sun ONE Identity Server authentication service.

Note This property is set during Agent installation and need not be changed unless absolutely necessary.

Example: com.iplanet.amagent.config.filter.loginURL=http://myserver.mydomain.com:58080/amserver/login

Host URL

Key: com.iplanet.amagent.config.filter.hostURL
Description: This property specifies the host URL to be used by the Agent to reconstruct the request issued by the browser. This value is used by Sun ONE Identity Server Authentication service to redirect the user back to the original request destination after successful authentication.
Valid Values: A string value that represents the host URL that the user is expected to access in order that the Agent can intercept. This value must match the format of this property.
The format of this property value is as follows:
protocol://hostname.optional-sub-domain.domain:port
protocol can be http or https
hostname.optional-sub-domain.domain is the fully qualified host name that the user is expected to access in order that the Agent may intercept.
port is the port number on which the receiving web server is listening.

Note If left unspecified, the Agent will try to reconstruct the host URL from the request.

Example:
com.iplanet.amagent.config.filter.hostURL=http://www.iplanet.com:80

Login Attempt Limit

Key: com.iplanet.amagent.config.filter.loginAttemptLimit
Description: This property specifies the number of login attempts that a user can make without success using a single browser session, which will trigger the blocking of the user request.
Valid Values: Unsigned integer value, including 0, which indicates the number of unsuccessful login attempts that are allowed for any user trying to gain access to protected resources.

Note This option can be disabled by setting the value to 0. The default value of this property is 5.

Example: com.iplanet.amagent.config.filter.loginAttemptLimit=5

Login Counter Cookie Name

Key: com.iplanet.amagent.config.filter.loginCounterCookieName
Description: This property specifies the name of the cookie that will be used to track the number of unsuccessful login attempts made by the user.
Valid Values: A string that represents the name of the cookie to be issued by Agent in order to track the number of unsuccessful login attempts made by the user.

Note This property is set during Agent installation and need not be changed unless absolutely necessary.

Example: com.iplanet.amagent.config.filter.loginCounterCookieName=iPlanetLoginAttemptID

Not-Enforced-List Cache Enable Flag

Key: com.iplanet.amagent.config.filter.notEnforcedList.cache
Description: This property specifies if the requests URIs that are evaluated as enforced or not-enforced may be cached to increase performance of the system.
Valid Values: true/false

Note The default value of this property is true.

Example: com.iplanet.amagent.config.filter.notEnforcedList.cache=true

Not-Enforced-List Cache Size

Key: com.iplanet.amagent.config.filter.notEnforcedList.cacheSize
Description: This property specifies the number of entries that will be kept in the cache of not-enforced URIs and enforced URIs by the Agent.
Valid Values: Non-zero unsigned integer indicating the number of enforced as well as not enforced request URIs to be cached during runtime.

Note Values that are valid but not suited for the deployment scenario may result in degradation of system performance.
The value for optimal system performance will depend on the type of application deployed, the number of possible request URIs in the deployed application, the user load on the system, the expiration time set for cache entries and a host of other deployment specific factors.

To determine the most optimal value of this property, the application should be load tested in a controlled test environment before being deployed for production.
Example: com.iplanet.amagent.config.filter.notEnforcedList.cacheSize=1000

Not-Enforced-List Cache Expiration Time

Key: com.iplanet.amagent.config.filter.notEnforcedList.cacheTime
Description: This property specifies the amount of time in seconds that will be used to evaluate if a cached entry can be removed from the cache to free up resources for new cache entries.
Valid Values: Non-zero unsigned integer indicating the time in seconds that will be used as the cache expiration time for entries in the cache during cleanup operation.
Values that are valid but not suited for the deployment scenario may result in degradation of system performance.
The value for optimal system performance will depend on the type of application deployed, the number of possible request URIs in the deployed application, the user load on the system, the expiration time set for cache entries and a host of other deployment specific factors.
To determine the most optimal value of this property, the application should be load tested in a controlled test environment before being deployed for production.
Example: com.iplanet.amagent.config.filter.notEnforcedList.cacheTime=60

LDAP Attribute Header Enable Flag

Key: com.iplanet.amagent.config.filter.enableLDAPAttributeHeaders
Description: This property specifies if the Agent should populate the HttpServletRequest with LDAP Attributes associated with the currently authenticated user.
Valid Values: true/false
The default value of this property is false and should be changed as necessary.
Example: com.iplanet.amagent.config.filter.enableLDAPAttributeHeaders=true

LDAP Attribute Header Map

Key: com.iplanet.amagent.config.filter.ldapAttribute[attr-name]
Description: This property specifies the LDAP Attributes to be populated under specific header names for the currently authenticated user.
Valid Values: Valid values must comply with the syntax of this property. The specified LDAP Attribute should be a valid attribute. The specified HTTP Header name should conform to HTTP Header name conventions.
The format for specifying this property is as follows:
com.iplanet.amagent.config.filter.ldapAttribute[attr-name]=header-name
attr-name is the name of the LDAP Attribute to be looked up for the authenticated user, and header-name is the name of the Header that will be used to store this value.

Note

Be sure that the specified Header Names do not conflict with the existing Header names.

Any number of such properties may be specified as long as they are valid properties conforming to the above stated requirements.

Example:
com.iplanet.amagent.config.filter.ldapAttribute[cn]=CUSTOM-Common-Name
com.iplanet.amagent.config.filter.ldapAttribute[ou]=CUSTOM-Organization-Unit
com.iplanet.amagent.config.filter.ldapAttribute[o]=CUSTOM-Organization
com.iplanet.amagent.config.filter.ldapAttribute[c]=CUSTOM-Country
com.iplanet.amagent.config.filter.ldapAttribute[mail]=CUSTOM-Email
com.iplanet.amagent.config.filter.ldapAttribute[employeenumber]=CUSTOM-Employee-Number

LDAP Date Header Attribute Format String

Key: com.iplanet.amagent.config.filter.ldapAttributeDateHeaderFormat
Description: This property specifies the format of Date/Time value to be expected as a result of an attribute lookup. This is required when using the specialized get methods of the
javax.servlet.http.HttpServletReqeust interface that return Date values for headers.
Valid Values: Valid java.text.SimpleDateFormat Time Format Syntax string. For more information, see: documentation at
http://java.sun.com/j2se/1.4/docs/api/java/text/SimpleDateFormat.html

Note The default value of this property is set to EEE, d MMM yyyy hh:mm:ss z and should be changed as necessary.
Invalid value of this property may result in runtime exceptions in the application.

Example:
com.iplanet.amagent.config.filter.ldapAttributeDateHeaderFormat=EEE, d MMM yyyy hh:mm:ss z

SSO Token URL Decode Flag

Key: com.iplanet.amagent.config.filter.urlDecodeSSOToken
Description: This property indicates if the SSO Token needs to be URL Decoded by the Agent before it may be used.
Valid Values: true/false

Note The default value of this property is set to true

Example: com.iplanet.amagent.config.filter.urlDecodeSSOToken=true

Default Web Application Name

Key: com.iplanet.amagent.config.filter.defaultWebAppName
Description: This property specifies a name for the Default Web Application deployed on the application server.
Valid Values: A string consisting of lower case and or upper case letters that can be used as the name for default web application.

Note

The default value of this property is DefaultWebApp

This property is necessary if the protected application is deployed as the default web application.

Example:
com.iplanet.amagent.config.filter.defaultWebAppName=DefaultWebApp

Global Not-Enforced List

Key: com.iplanet.amagent.config.filter.global.notEnforcedList[index]
Description: This property specifies a list of patterns that can be used to evaluate if the requested URI does not require the protection enforced by the Agent.
Valid Values: Valid values must comply with the syntax of this property. The valid values can be exact URIs or patterns consisting of wild-card character `*' to indicate zero or more characters.
The syntax of this property is as follows: com.iplanet.amagent.config.filter.global.notEnforcedList[index]=pattern
index is an integer that starts from 0 and increments for every entry in this property list.
pattern is a string that represents request URIs that are not enforced by Agent.

Note

The pattern string may consist of wild card character `*', which may match zero or more characters.

The index must start from zero for the first entry and continue till the last in a sequence. Missing index values in this list will result in partial or complete loss of list entries.

No value for this property indicates empty global not enforced list.

Example:
com.iplanet.amagent.config.filter.global.notEnforcedList[0]=*.gif
com.iplanet.amagent.config.filter.global.notEnforcedList[1]=/public/*
com.iplanet.amagent.config.filter.global.notEnforcedList[2]=/images/*

Application Filter Configuration

Access Denied URI

Key: com.iplanet.amagent.config.filter.AppName.accessDeniedURI
Description: This property specifies the application specific Access Denied URI for the protected application.
Valid Values: The URI within the deployed application that must be used as the access denied URI to block in coming requests when necessary.
This property is specific to the protected application. Therefore if there are more than one protected applications deployed on the system, there should be one property for each such application.
Note: This property must specify a URI that is within the application. Failing to do so can result in runtime internal server errors.
Note: The format for specifying this property is as follows:
com.iplanet.amagent.config.filter.AppName.accessDeniedURI=URI
AppName is the context path name for the deployed application and URI is the URI to be used.

Note

The difference between AppName and context path of the application is that the context path has a leading / character.

If the protected application is the default web application, the AppName should be set to the same string as specified in for the value of the property Default Web Application Name.

If the property is not specified for a given application, the Agent uses HTTP Status Code 403 (Forbidden) to indicate a blocked access.

Example:
com.iplanet.amagent.config.filter.Portal.accessDeniedURI=/Portal/AccessDenied.html
com.iplanet.amagent.config.filter.BankApp.accessDeniedURI=/BankApp/Block.jsp
com.iplanet.amagent.config.filter.DefaultWebApp.accessDeniedURI=/URLAccessDenied.htm

Application Not-Enforced-List

Key: com.iplanet.amagent.config.filter.AppName.notEnforcedList[index]
Description: This property specifies a list of patterns that can be used to evaluate if the requested URI does not require the protection enforced by the Agent for a particular application.
Valid Values: Valid values must comply with the syntax of this property. The valid values can be exact URIs or patterns consisting of wild-card character '*' to indicate zero or more characters.
The syntax of this property is as follows:
com.iplanet.amagent.config.filter.AppName.notEnforcedList[index]=pattern
AppName is the context path name without the leading `/' character for the deployed application.
index is an integer that starts from 0 and increments for every specified property for the particular application.
pattern is a string that represents the URIs that are not enforced by the Agent.

Note

The pattern string may consist of wild card character `*', which may match zero or more characters.

The index must start from zero for the first entry and continue till the last in a sequence. Missing index values in this list will result in partial or complete loss of list entries. The index value will be independent for different AppName specified in this property list.

In case the protected application is the default web application, the AppName should be set to the same string as specified in for the value of the property Default Web Application Name.

No value for this property indicates empty not-enforced list.

Example:
com.iplanet.amagent.config.filter.Portal.notEnforcedList[0]=/Portal/GuestPages/*
com.iplanet.amagent.config.filter.Portal.notEnforcedList[1]=/Portal/Registration/*
com.iplanet.amagent.config.filter.Portal.notEnforcedList[2]=/Portal/WebServices/PollServlet
com.iplanet.amagent.config.filter.BankApp.notEnforcedList[0]=/BankApp/ModuleGuestTour/*
com.iplanet.amagent.config.filter.BankApp.notEnforcedList[1]=/BankApp/index.html
com.iplanet.amagent.config.filter.DefaultWebApp.notEnforcedList[0]=/index.html
com.iplanet.amagent.config.filter.DefaultWebApp.notEnforcedList[1]=/about.html

Debug Engine Configuration

Debug Level

Key: com.iplanet.amagent.config.debug.level
Description: This property specifies the amount of debug messages that will be emitted by the Agent's Debug Engine.
Valid Values: Any of 0, 1, 3, 7, 15, and 31. These values indicate the following:

0 : No debugging

1 : Only Error messages

3 : Error and Warning messages

7 : Error, Warning and Brief Informational messages

15: Error, Warning and Verbose Informational messages

31: Error, Warning and Very Verbose Informational messages

Note

For better performance of the system, this property should be set to a value 0. Values other than that will affect the system performance depending upon the amount of information the Debug Engine has to emit.

Values other than the ones specified in the Valid Values list above will lead to invalid configuration of the Debug Engine, thereby affecting the volume of messages that will be emitted.

Example: com.iplanet.amagent.config.debug.level=7

Debug Log File

Key: com.iplanet.amagent.config.debug.logfile.name
Description: This property specifies the Debug log file to be used for recording Debug messages.
Valid Values: String representing the complete path name of the file to be used by Agent to record Debug messages.

Note

Be sure that the Application Server process has sufficient permissions to be able to write to this file.

Invalid or empty value of this property will lead to Debug messages not being logged in the log file.

Example:
com.iplanet.amagent.config.debug.logfile.name=/debug/agent_debug.log

Debug Log File Rotation Flag

Key: com.iplanet.amagent.config.debug.logfile.rotate
Description: This property specifies if the Debug log file should be rotated by the Agent.
Valid Values: true/false

Note Default value of this property is false and should be changed as necessary.

Example: com.iplanet.amagent.config.debug.logfile.rotate=false

Debug Log File Rotation Size

Key: com.iplanet.amagent.config.debug.logfile.rotate.size
Description: This property specifies the approximate size of the Debug log file in bytes, which should be used to evaluate when the log file needs to be rotated.
Valid Values: Non-zero unsigned integer indicating the size in bytes to be used to evaluate when the log file needs to be rotated.

Note

Default value of this property is 52428800 bytes (~ 50 MB) and should be changed as necessary.

This property is not used if the Debug Log File Rotation Flag is set to false

Example: com.iplanet.amagent.config.debug.logfile.rotate.size=52428800

Debug Time/Date Format String

Key: com.iplanet.amagent.config.debug.date.format
Description: This property specifies the format of time stamp that is used to mark the exact time when the Debug message was recorded.
Valid Values: Valid java.text.SimpleDateFormat Time Format Syntax string. For more information, see URL:
http://java.sun.com/j2se/1.4/docs/api/java/text/SimpleDateFormat.html

Note The default value of this property is set to:
MMM d, yyyy h:mm:ss a z 'Agent' and should be changed as necessary.
Invalid value of this property will result in loss of time stamp data with debug messages.

Example:
com.iplanet.amagent.config.debug.date.format=[yyyy/MM/dd HH:mm:ss zzz]

Debug Print STDOUT Flag

Key: com.iplanet.amagent.config.debug.print.stdout
Description: This property specifies if the Debug Engine should print the debug messages on Standard Output stream.
Valid Values: true/false

Note

The default value of this property is true and should be changed as necessary. When set to true, the Debug Engine prints all debug messages on the Standard output stream. This results in the debug messages being displayed on the console window where the Application Server startup script was executed from.

This property has no affect on the ability of Debug Engine to write to debug log files.

Example: com.iplanet.amagent.config.debug.print.stdout=true

Uninstalling the Agent

When you install the Sun ONE Identity Server Policy Agent for Sun ONE Application Server software, an uninstallation program is created in the installation directory. Using this uninstallation program the Agent can be removed completely from your system. While the uninstallation program deletes all the installed files from your system, certain files such as audit log messages are not deleted. You can delete them manually.
The uninstallation program for Sun ONE Identity Server Policy Agent for Application Server should be launched according to the following steps for Solaris or Windows platform as applicable.

Launching the Uninstallation Program on Solaris

The uninstallation program for Solaris platform may be launched by executing the generated uninstall script located in the installation directory. The following steps provide details on how to achieve this:

Login as root.

Stop the Application Server instance using the following command:

/S1AS_Install_Dir/appserv/domains/domain-instance/server-instance/bin/stopserv

Set your JAVA_HOME environment variable to JDK version 1.4.0 or higher. If your system does not have JDK of required version, use the JDK supplied with Sun ONE Application Server. This JDK is located under:

S1AS_Install_Dir/jdk

The uninstallation program provides two types of interfaces—a graphical user interface (GUI) and a command-line. In most cases, the GUI installer can be used for uninstalling the Agent. However, in cases when you are uninstalling the Agent over a telnet session on a remote server and do not have windowing capabilities, then the GUI uninstallation program cannot be used. In such a case it is recommended that you use the command line uninstallation program for uninstalling the Agent. This can be launched by executing the uninstall script and passing in a command line argument -nodisplay as follows:

#./uninstall_asagent -nodisplay

However, if you choose to use the GUI uninstallation program, then it is required that you set your DISPLAY environment variable to ensure that the GUI uninstallation program window appears on the correct console.

Note If you choose to use the command-line uninstallation program using the -nodisplay option, you may skip the following step and proceed directly to the next section, which details out the uninstallation procedure.

Launch the GUI uninstallation program by invoking the uninstall script as follows:

# ./uninstall_asagent

The uninstallation program requires that you setup your JAVA_HOME variable correctly as pointed out in the Step 3. However, in case you have incorrectly set the JAVA_HOME variable, the uninstall script will prompt you for supplying the correct JAVA_HOME value:

Enter JAVA_HOME location (Enter "." to abort):

Type the full path to the JDK installation directory for launching the installation program. Otherwise, enter a period (.) to abort the uninstallation.

In order that the GUI uninstallation program be displayed on your console, the DISPLAY environment variable of your shell must be set correctly. In case your DISPLAY environment variable is not set at the time of invoking the uninstall script, the uninstallation program will prompt you for the DISPLAY environment variable value as follows:

Please enter the value of DISPLAY variable (Enter "." to abort):

Provide the DISPLAY value to the installer by typing in the exact value at the above prompt. Otherwise, enter a period (.) to abort the installation.

Launching the Uninstallation Program on Windows 2000 Server

The uninstallation program for the Windows 2000 Server platform may be launched by executing the generated uninstall script located in the installation directory.

You must have administrative privileges when you run the uninstallation program. If you do not have administrative privileges, either login as "Administrator" or request such privileges to be granted to your account by the system administrator of the machine or domain as applicable.

Stop the Application Server instance using the following command:

S1AS_Install_Dir\appserv\domains\domain-instance\server-instance\bin\stopserv

Go to the directory where Agent is installed.

The uninstall script uninstall_asagent.bat is located in this directory. In order to use the uninstall_asagent.bat script to launch the uninstallation program, you must have JDK version 1.4.0 or higher. This can be verified by typing the following command in a command prompt window:

C:\> java -version

java version "1.4.0_01"

Java(TM) 2 Runtime Environment, Standard Edition (build 1.4.0_01-b03)

Java HotSpot(TM) Client VM (build 1.4.0_01-b03, mixed mode)

If you do not have JDK of required version in your system path, you can use the JDK supplied with Application Server located at:

S1AS_Install_Dir\jdk

The uninstall_asagent.bat may be executed by typing the file name at the command prompt window in a directory where it is present, or by double clicking the file in Windows Explorer. For example:

C:\Sun\uninstall_asagent.bat

The uninstallation program provides two types of interfaces—a graphical user interface (GUI) and a command line interface. By invoking the uninstall_asagent.bat file from a command prompt window as shown above or by double clicking it in Windows Explorer, the uninstallation program is launched in the GUI mode. However, in a case where it is it is required that you use the command line based uninstallation program for uninstalling the Agent, the uninstallation program may be launched by executing the uninstall_asagent.bat file and passing in a command line argument -nodisplay as follows:

Agent_Install_Dir\uninstall_asagent.bat -nodisplay

Note

If the required JDK is configured to be in the system path, the uninstallation program can be launched from the Control Panel Add/Remove programs control. In the list of the installed programs on your system, select Sun ONE Identity Server Policy Agent for Application Server and click the Change/Remove button. If your system path is not configured with an appropriate JDK version, the uninstall can fail.

When using the Control Panel Add/Remove programs to launch the uninstallation program for Agent, the uninstallation program will be launched in GUI mode only. To launch the uninstallation program in command line mode, use the provided uninstall script as mentioned previously.

Uninstalling the Agent Using GUI

The uninstallation program begins with a Welcome screen. Click Next to step through the uninstallation screens, answering the questions.

In the Uninstall Type Selection screen select the type and click Next.

Full: Select this type to remove the product and all the components from your system.

Partial: Select this type if you want to remove only certain Agent components. Select the component you want to uninstall and click Next.

Figure 4-7    Uninstall Type Selection Screen

In the Ready to Uninstall screen, review the uninstallation information. If you need to make changes, click Back. Otherwise, click Uninstall Now.

The Uninstall Progress screen displays the progress of uninstall process.

In the Uninstallation Summary window, click Details for a detailed summary of the configuration information that was processed during uninstallation. Click Exit to end the program
Figure 4-8    Uninstall Summary Screen

Note If the status of the uninstall is "Failed", you must view the log file for the uninstall by clicking on the Details button to identify which uninstall task failed. In certain situations these failures can be recovered from and the system can be restored to its original state. Refer to the next section for the detail of how to restore the system to its original state.

Uninstalling the Agent Using Command-Line

You must have root permissions when you run the agent installation program.

Run the uninstall program with the command line argument -nodisplay. You'll find the program in the directory where you have installed the agent.

# ./uninstall_asagent -nodisplay

The following text is displayed:

Please select the type of uninstall to perform from the following choices:
1. Full
2. Partial

Choose one option from above [1]

Type 1 to uninstall full.

The following text is displayed:

Sun(TM) ONE Identity Server Policy Agent for Sun(TM) ONE Application Server 7.0

Ready to Uninstall

1. Uninstall Now
2. Start Over
3. Exit
Choose one option from above [1] {"<" goes back, "!" exits}

Enter 1 to uninstall.

The following text is displayed:

Uninstallation Summary

Installation summary                   Summary Result More Details
1. Sun_TM_ONE Identity Server Policy   Full           Enter 1 to view the log

Done

To see log information, enter 1. To exit the Uninstallation program, press Enter.


<web-app>
<display-name>...</display-name>
<description>...</description>

<filter>
<filter-name>Agent</filter-name>
<display-name>Agent</display-name>
<description>SunTM ONE Idenitity Server Policy Agent for SunTM ONE Application Server 7.0</description>
<filter-class>com.sun.amagent.as.filter.AgentFilter</filter-class>
</filter>
<filter-mapping>
<filter-name>Agent</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>
...
...
</web-app>

Previous Contents Next
Copyright 2003 Sun Microsystems, Inc. All rights reserved.

Last Updated January 20, 2003