Sun ONE logo     Previous     Contents     Next     
Sun ONE Identity Server J2EE Agent Guide



Chapter 2   Policy Agent for WebLogic 6.1 SP2


This chapter provides a brief overview of WebLogic Agent and describes how to install and configure Sun ONE Identity Server Policy Agent for WebLogic 6.1 SP2 Application Server running on Solaris 8, Windows 2000, and HP-UX 11 operating systems. Topics include:



Overview

The Sun ONE Identity Server Policy Agent enables WebLogic Server to enforce authentication and authorization using Sun ONE Identity Server services, thereby securing client access to the hosted J2EE applications and enforcing J2EE security policies defined in the deployed application's deployment descriptors

The Sun ONE Identity Server Policy Agent for WebLogic 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.



Guidelines


The following guidelines will help you use Identity Server Policy Agent for WebLogic most optimally:

  • Use Agent-Based Authentication

    After the Agent is installed and the application has been configured to use Agent Filter component, the Agent Filter component enforces authentication for all web based access to the protected application's enforced portions. Working in tandem with the Agent Realm component, the Agent Filter ensures that the J2EE policies defined for the protected application get evaluated correctly based on the set role-to-principal mappings, at the same time offering other key services like Single Sign-On etc. Therefore, it is recommended that protected applications do not use their own authentication mechanism or any container based authentication mechanisms which would result in the Agent Filter component being bypassed during the application operation.

  • Create Enhanced Security Aware Applications

    The Agent provides the rich APIs offered by Sun ONE Identity Server SDK libraries, which are available for use within the protected application. Using these APIs, the application architect can create enhanced security aware applications that are customized to work in the security framework offered by Identity Server. For more information on how to use the Sun ONE Identity Server SDK, refer Sun ONE Identity Server Programmer's Guide.



Installing the Agent

The Sun ONE Identity Server Policy Agent for WebLogic Server 6.1 SP2 may be installed on these platforms—Solaris 8, Windows 2000, or HP-UX 11. The installation program for Sun ONE Identity Server Policy Agent for WebLogic Server 6.1 SP2 should be launched according to the following steps as applicable to the respective platform in use. Once the installation program is launched successfully, you may skip to the next section, which details the steps necessary to install the Agent.


Pre-installation Tasks

The following tasks must be performed before installing the Sun ONE Identity Server Policy Agent for WebLogic Server 6.1 SP2:

  1. Install the WebLogic Server 6.1 SP2.

    See the WebLogic Server documentation for the necessary details. When the server is installed, test the installation by using the provided sample application to ensure that the server is installed correctly.

  2. Test the deployment of application that you intend to protect.

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


Launching the Installation Program on Solaris 8

The binaries for Sun ONE Identity Server Policy Agent for WebLogic Server 6.1 SP2 for Solaris platform are provided as a tar-gzip archive. Copy this archive to the machine where WebLogic Server is installed. Follow the steps to launch the installation program:

  1. Login as root.

  2. Unzip the binary archive using the following command:

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

  3. Set your JAVA_HOME environment variable to JDK version 1.3.1 or higher. If your system does not have the required version of JDK, use the JDK supplied with WebLogic Server 6.1 SP2 server. This JDK is located at:

    WebLogic_Install_Dir/bea/jdk131

    The installation program provides two types of interfaces—a graphical user interface (GUI) and a command line interface. In most cases, the GUI installation program 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 it is recommended that you use the command-line installation program for installing the Agent. You can launch this by executing the following command:

    # ./setup -nodisplay

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


    Note If you choose to use the command line installation program using the -nodisplay option, you may skip the following step and proceed directly to the section "Installing the Agent Using GUI", which details out the installation procedure.


  4. Launch the GUI installation program by invoking the setup script as follows:

    # ./setup

    • The installation program requires that you set up your JAVA_HOME variable correctly as pointed out in the Step 3. However, if you have incorrectly set the JAVA_HOME variable, the setup script will prompt you for the correct JAVA_HOME value: oblige

      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 installation.

    • In order that the GUI installation program 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 installation 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 installation program by typing the exact value at the above prompt. Otherwise, enter a period (.) to abort the installation.


Launching the Installation Program on Windows 2000

The binaries for Sun ONE Identity Server Policy Agent for WebLogic Server 6.1 SP2 for Windows platform are provided as a zip archive. Copy this archive to the machine where WebLogic Server is installed and follow the steps to launch the installation program:

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

  2. Unzip the Agent binaries in a convenient location using the Zip utility. This operation results in two executable files setup.bat and setup.exe, which may be used to launch the installation program. Each of these files provide different features for launching the installation program. You may 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 installation program, you must have JDK version 1.3.1 or higher. This can be verified by typing the following command in a command prompt window:

    C:\> java -version

    java version "1.3.1_02"

    Java(TM) 2 Runtime Environment, Standard Edition (build 1.3.1_02-b02)

    Java HotSpot(TM) Client VM (build 1.3.1_02-b02, mixed mode)

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

    WebLogic_Install_Dir\bea\jdk131

    The setup.bat may be executed by typing the file name in 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 installation program provides two types of interfaces—a graphical user interface (GUI) and a command line interface. By invoking setup.bat file from a command prompt window as shown above or by double clicking it in Windows Explorer, you can launch the installation program 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

    Using setup.exe relieves you from the task of setting up your environment path to include a valid version of JDK. This program first checks your system for the presence of a compatible JDK version and uses the one that was found. However, if no compatible version is found, this program installs the necessary runtime and uses it to launch the installation program.

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


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



Launching the Installation Program on HP-UX 11

The binaries for Sun ONE Identity Server Policy Agent for WebLogic Server 6.1 SP2 for HP-UX 11 platform are provided as a tar-gzip archive. Copy this archive on the machine where WebLogic Server is installed. Follow the steps to launch the installation program:

  1. Login as root.

  2. Unzip the binary archive using the following command:

    # gzip -dc j2eeagents-1.0-domestic-us.hppa1.0-hp-hpux11.00.tar.gz | tar xvf -

  3. Set your JAVA_HOME environment variable to JDK version 1.3.1 or higher. If your system does not have the required version of JDK, use the JDK supplied with WebLogic Server 6.1 SP2 server. This JDK is located under:

    WebLogic_Install_Dir/bea/jdk131

  4. The installation program provides two types of interfaces—a graphical user interface (GUI) and a command line interface. In most cases, the GUI installation program 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 it is recommended that you use the command line installation program for installing the Agent. You can launch this by executing the following command:

    # ./setup -nodisplay

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


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


  5. Launch the GUI installation program by invoking the setup script as follows:

    # ./setup

    • The installation program requires that you set up 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 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 installation.

    • In order that the GUI installation 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 setup script, the installation 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 installation program by typing in the exact value at the above prompt. Otherwise, enter a period (.) to abort the installation.


Installing the Agent Using GUI

The installation program begins with a Welcome screen. Click Next to step through the installation screens and answer the required questions.

  1. 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 Agent.

  2. 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 installation program will prompt you to specify if the new directory should be created. You can either choose to create this new directory by clicking Create Directory button or select a new directory by clicking Choose another Directory button.


  3. 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 WebLogic Server 6.1 SP2, which is selected by default.

Figure 2-1    Component Selection Screen


Note

For a given system, only one installation of Sun ONE Identity Server Policy Agent for WebLogic Server 6.1 SP2 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 installation program by clicking the Exit button and remove the old installation completely before starting the install again.


  1. In the Sun ONE Identity Server Information screen, provide the following information about the Sun ONE Identity Server and click Next.

Figure 2-2    Sun ONE Identity Server Information Screen

Sun ONE Identity Server Host: Enter the fully qualified host name of the computer 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/wlAgent/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


  1. In the Directory Server Information screen, provide the following information about the Directory Server that is associated with Sun ONE Identity Server services.

Figure 2-3    Directory Information Screen

Directory Host: Enter the fully qualified host name of the computer 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

  1. In the WebLogic Server Details screen, provide the following information about the WebLogic Server on which the Agent is installed.

Figure 2-4    WebLogic Server Details Screen

WebLogic Startup Script: Enter the full path to the location of the script used to start the WebLogic Server.The WebLogic Server Startup Script on Solaris platform is a shell script that is used to start the WebLogic Server. On Windows platform, this is a CMD script which serves the same purpose. This script is typically located under the following directory:

WebLogic_Install_Dir/bea/wlserver6.1/config/server-domain-name/

WebLogic JAVA_HOME directory: Enter the full path to the location of the JDK installation home used by the WebLogic Server. The WebLogic JAVA_HOME directory refers to the JDK installation that is used by the WebLogic Server. Typically the value of this is the full path to the following directory:

WebLogic_Install_Dir/bea/jdk131

In case you are not sure of the exact location of this directory, open the WebLogic Startup Script that is used for starting the WebLogic Server and locate the value of JAVA_HOME variable as specified in this file.


Caution

  • The installation program modifies the WebLogic Server Startup Script to include certain libraries in the WebLogic CLASSPATH, as well as adds certain required parameters to the command that loads the startup classes of WebLogic Server in the Java Virtual Machine. If you specify an incorrect value for the WebLogic Server Startup Script, the necessary classes and parameters will not get added, resulting in malfunction of the Agent, which can render the WebLogic Server unusable. To avoid this problem, ensure that the value you specify for WebLogic Server Startup Script is accurate.

  • The installation program adds certain extensions to the JDK used by the WebLogic Server, which are needed by the Agent for successful execution. These extensions are installed in the JDK directory indicated by the above mentioned WebLogic JAVA_HOME value. If the value supplied is incorrect or is not the JDK used by the WebLogic Server, it will result in malfunction of the Agent and can render the WebLogic Server unusable. To avoid this problem, ensure that the value you specify for WebLogic JAVA_HOME is accurate.


  1. In the Agent Configuration Details screen, provide the key configuration information necessary for the Agent to function correctly.


    Note Read the section "Important Tips" before performing this step.


Figure 2-5    Agent Configuration 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 to enable rotation of Audit Log files.

Enable Console Integration: Select this to enable console level integration of Sun ONE Identity Server with WebLogic Server Administration console.

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 to enable caching of Not-Enforced List evaluation results.

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

Cache Expiration Time: Specify the time (in seconds) to be used as the maximum time limit for entries that are added 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 WebLogic Server process because the Agent executes in the same process as the WebLogic Server. Providing an incorrect value for this will result in the malfunction of the Agent which can render the WebLogic Server unusable.

    • Console Integration implies that the information regarding the names of all Users, Roles, and the Users who are assigned to these Roles in Sun ONE Identity Server will be visible on the WebLogic Server Administration Console. Therefore, this feature must be enabled with caution since the User/Role information will then be accessible to administrators who access the WebLogic Server Console.

    • When a request is intercepted by the Agent without sufficient credentials, the Agent redirects the user to the Sun ONE 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 that 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.

    • The Agent maintains two caches in its memory—one for recording the URIs that were evaluated as enforced and the other for recording the URIs that were evaluated as not-enforced. The specified values of Number of Entries in Cache and Cache Expiration time is equally applicable to both of these caches. This factor must be considered when setting the values for the size and expiration time of the cache.

    • 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 otherwise avoided and serves no purpose.

  1. In the Summary of all the selections screen, review and verify the installation options that you have specified for the Agent. If you need to make changes, click Back. Otherwise, Next to proceed.

Figure 2-6    Summary of all the selections Screen

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

  2. The Install Progress screen displays the progress of the installation as the installation program 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 that may lead to a partially installed product, which may also cause problems with uninstall, and may as well render the WebLogic Server unusable. This process should be interrupted only in cases where it is absolutely necessary to do so.


  3. In the Installation Summary screen, 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 install log file by clicking the Details button to identify the unsuccessful installation task. In this situation, you may uninstall the Agent and try again after fixing the root cause of failure during this installation.


After the agent is installed, the next step is to configure the WebLogic Server and the deployed application appropriately as explained in the following sections.



WebLogic Server Configuration


Once the Sun ONE Identity Server Policy Agent for WebLogic Server 6.1 SP2 has been installed on your system, the WebLogic Server must be configured to use the Agent Realm provided as a part of the Agent.


Installing the Agent Realm

The Agent Realm is a Custom Security Realm that can be added to the WebLogic Server by using the WebLogic Server Administration Console. This section outlines the steps necessary to successfully add the Agent Realm to the WebLogic Server. It must be noted that the information provided in this section is only to facilitate the installation of Agent Realm and should not be taken as a substitute for the information provided in WebLogic Server documents. For a complete in-depth discussion on WebLogic Custom Realms, refer WebLogic Server documentation center located at http://www.bea.com.

In order to install the Agent Realm, the following steps must be performed:

  1. Create a Custom Realm for Agent

  2. Create a Caching Realm for Agent Realm

  3. Configure the File Realm


Create a Custom Realm for Agent

The following steps outline how a new Custom Realm may be created for installing the Agent Realm in WebLogic Server:

  1. Logon to the WebLogic Server Administration Console. Use the configured system username and password for logging on to the console.

  2. In the left pane of the WebLogic Server Administration Console, expand the Security Node by clicking on the "+" sign.

  3. In the left pane under Security node, click the "Realms" item to display a list of available Realms in the system on the right pane.

  4. On the right pane, click "Configure a new Custom Realm" link. This displays a form that can be used to enter the information regarding the new Custom Realm that you are trying to create.

  5. In this form, enter the following information:

    Name: Agent Realm

    Realm Class Name: com.iplanet.amagent.weblogic.realm.AgentRealm

  6. Once this information has been entered, click the Create button.

  7. After creating the new Realm, restart the WebLogic Server.

Once the WebLogic Server is restarted, using the Administration Console, go to the Security > Realms node. You should be able to see the newly created Agent Realm in the list of Realms displayed on the right hand pane.


Create a Caching Realm for Agent Realm

Follow these steps to create a new Caching Realm for installing the Agent Realm in WebLogic Server:

  1. Logon to the WebLogic Server Administration Console. Use the configured system username and password for logging on to the console.

  2. In the left pane of the WebLogic Server Administration Console, expand the Security Node by clicking on the "+" sign next to it.

  3. In the left pane under Security node, click the Caching Realms to display a list of available Caching Realms in the system on the right pane.

  4. On the right pane, click the "Configure a new Caching Realm" link. This displays a form that can be used to enter the information regarding the new Caching Realm that you are trying to create.

  5. In this form, enter the following information:

    Name: Agent Caching Realm

    Basic Realm: Select Agent Realm from the pull down menu.

  6. Click on the Create button. This refreshes the right pane and a new Caching Realm is created. The right pane now displays the configuration of this newly created Caching Realm.

  7. In the right pane, disable all the caching attributes. This can be done as follows:

    1. Click the ACL Tab. This displays the ACL caching attributes.

    2. Uncheck the check box next to Enable ACL Cache

    3. Click on the Apply button.

    4. Repeat this process for the rest of the available tabs—Authentication, Groups, Users, and Permissions. Uncheck the appropriate Enable Cache check box and click the Apply button.

  8. Restart the WebLogic Server.

Once the WebLogic Server is restarted, using the Administration Console, go to the Security > Caching Realms node. You should be able to see the newly created Agent Caching Realm in the list of Caching Realms displayed on the right pane.


Configure the File Realm

Once the Agent Caching Realm has been created, the WebLogic Server must be configured to use this new Caching Realm. This is done by configuring the File Realm. The following steps outline how the File Realm may be configured for this purpose:

  1. Logon to the WebLogic Server Administration Console.

  2. On the left pane click the Security node. This forces the console to display the Security configuration of the WebLogic Server in the right hand pane.

  3. In the right pane, click the Filerealm tab. This causes the console to display the details of the current File Realm.

  4. In the form that is displayed on the right pane, under Caching Realm, select the Agent Caching Realm from the pull down menu.

  5. Click the Apply button.

  6. Restart the WebLogic Server.

Once the File Realm is configured and the WebLogic Server is restarted, the Agent Realm has been successfully installed.


Note Once the Agent Realm has been successfully configured, it is recommended that you create a backup of the WebLogic Server's config.xml file. You may name this backup as config.xml.withAgent, so that the next time you install the Agent, you can simply copy this file on top of your existing config.xml and bypass the manual steps necessary to install the Agent Realm.



Troubleshooting the Installation

If after configuring the File Realm, the WebLogic Server does not start up correctly, the following could be the reasons:

  • The WebLogic Server Startup File was not modified successfully by the Agent Installation.

    This can happen if you have modified the WebLogic Server startup file before installing the Agent, or if the installation program did not have sufficient permissions to modify this file. In either case, refer Appendix A to manually modify the startup file in order to recover from this problem.

  • The Agent installation program was unable to install the required extensions for the JDK being used by WebLogic Server.

    To verify this, first look at the WebLogic Server startup file to determine the exact location of JDK used by the WebLogic Server. This can be inferred from the value of JAVA_HOME as set in the WebLogic Server startup file. Using this value as the JDK directory, ensure that it has the necessary extensions installed in it. Refer Appendix A to manually install the extensions if necessary in order to recover from this problem.

If the above reasons do not explain why the WebLogic Server did not startup correctly, it implies that there has been a serious installation error, which has resulted in the WebLogic Server being unusable. To recover from this problem, uninstall the Agent from your system. This should bring the WebLogic Server back to the state that it was in before the installation of the Agent.



Application Configuration


The Agent Realm component of Sun ONE Identity Server Policy Agent for WebLogic 6.1 SP2 provides runtime mapping of various principals in Identity Server. Abstract security role names are 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 an 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 WebLogic 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 WebLogic Server using the Agent. It is recommended that applications that are not protected using the Agent should not be deployed on the WebLogic 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:

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

  2. 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.

  3. 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">

  4. Once 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 WebLogic 6.1 SP2</description>
      <filter-class>com.iplanet.amagent.weblogic.filter.AgentFilter</filter-class>
      </filter>
      <filter-mapping>
      <filter-name>Agent</filter-name>
      <url-pattern>/*</url-pattern>
      </filter-mapping>
      ...
      ...
    </web-app>

  5. 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 Mappings

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.

The following are two ways to create such mappings:

  • Editing the WebLogic Server specific deployment descriptors.

    The WebLogic Server specific deployment descriptors may be edited to create the role to principal mappings. These descriptors are in weblogic.xml and weblogic-ejb-jar.xml files. Refer WebLogic Server reference documentation to learn the details of 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.

  • Using the WebLogic Server Administration Console.

    The WebLogic Server administration console allows you to create the role to principal mappings by editing the deployed application's deployment descriptors on the fly. In order to use this facility, the application must be deployed and the WebLogic Server must be up and running at that time. Refer WebLogic Server documentation on how to use the Administration console to create such mappings for deployed applications.


Application Specific Agent Configuration

Oftentimes, 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/wlAgent/amAgent/config/AMAgent.properties

This file may be edited to provide general as well as application-specific configuration for the Agent.


Note
  • 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.

  • The properties specified in the AMAgent.properties file are loaded during the WebLogic Server startup time. Any changes made to this file while the WebLogic 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 within this string should be replaced by their appropriate values as follows:

AppName: This string should be replaced by the deployed application's context path without its leading forward-slash character. 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 with context path /SomeApp:

com.iplanet.amagent.config.filter.SomeApp.notEnforcedList[0]=/SomeApp/public/*

com.iplanet.amagent.config.filter.SomeApp.notEnforcedList[1]=/SomeApp/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 /SomeApp/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 /SomeApp/public/* will match with any URI that begins with /SomeApp/public/.

Using this property, you could specify none or many 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 "Installing the Agent" for details on how this feature is configured, or refer "Agent Configuration" for details on this feature), the Agent is required to block the user's access under certain circumstances. 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 within this string should be replaced by their appropriate values as follows:

AppName: This string should be replaced by the deployed application's context path without the leading forward-slash character (/). 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 WebLogic 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

The above 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:

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

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

  2. 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 applications. However, the only difference is that the access-denied URI of the default web application as well as the not-enforced list entries cannot begin with the /DefaultWebApp/ path segment since such a path segment does not exist on the application server in reality. The AppName in this case where the actual context path is an empty string, is only provided as a convenience to specify the properties associated with the default web application and should not be used in specifying 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 protected applications that are deployed on the server. This list is specified by using the following property:

com.iplanet.amagent.config.filter.global.notEnforcedList[index]= pattern

pattern is either an exact URI or a pattern specified by using the wild card character `*' that can be substituted for zero or more characters in the request URI.

index is an integer value starting from 0 and unique for every entry.


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 accesses 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 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 not in any way cover 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 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 core configuration needed by the Sun ONE Sun ONE Identity Server Policy Agent for WebLogic Server 6.1 SP2 is provided in the AMAgent.properties file located in the following directory:

Agent_Install_Dir/wlAgent/amAgent/config

This property file provides many configuration settings that can be modified in order to customize the Agent's operation for your deployment scenario.


Note

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 it is absolutely necessary. Note that invalid data entries present in this file can lead to the malfunction of the Agent, malfunction of the deployed applications, and could render the entire system unusable.


The settings provided in this file can be classified into the following categories:

Following sections detail the settings for each of these classifications.


Common Configuration

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


Organization Name

Key: com.iplanet.amagent.config.org

Description: This property specifies the organization name to be used when searching for principals in Sun ONE Identity Server.

Valid Values: A string that represents the organization name in Sun ONE Identity Server. This property is set during Agent installation and need not be changed unless absolutely necessary.

Example: com.iplanet.amagent.config.org=iplanet.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. 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 Sun ONE Identity Server, which may be used when searching for principals. 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

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


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 at

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. The 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: A string that represents the complete path name of the file to be used by Agent to record Audit messages.


Note
  • Be sure that the WebLogic 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=/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. The 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. The default value of this property is 52428800 bytes (~ 50 MB) and should be changed as required.

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


Realm Configuration

These settings are used to configure the Agent Realm component.


Allow Console Integration Flag

Key: com.iplanet.amagent.config.weblogic.allowConsoleIntegration

Description: This property specifies if the Agent Realm should allow console level integration of Sun ONE Identity Server with WebLogic Server.

Valid Values: true/false


Note
  • When set, the result of console level integration is that the WebLogic Server Administrator will be able to see the list of Sun ONE Identity Server principals in WebLogic Server Console.

  • Since this setting enables the WebLogic Server Administrator to see Sun ONE Identity Server principals in WebLogic Server console, it should be used with caution.

  • The default value of this setting is false and should be changed as necessary.


Example: com.iplanet.amagent.config.weblogic.allowConsoleIntegration=true


Global Filter Configuration

These settings are used to configure the Agent Filter component.


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. 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. 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

where:

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.

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 using a single browser session.

Valid Values: Unsigned integer value, including 0, which indicates the number of login attempts 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. 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. 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.


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.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

where 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 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-N ame

com.iplanet.amagent.config.filter.ldapAttribute[ou]=CUSTOM-Organiza tion-Unit

com.iplanet.amagent.config.filter.ldapAttribute[o]=CUSTOM-Organizat ion

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]=CUS TOM-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, refer URL:

http://java.sun.com/j2se/1.3/docs/api/java/text/SimpleDateFormat.html

The default value of this property is set to EEE, d MMM yyyy hh:mm:ss z and should be changed as necessary.


Note 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


Authentication Session Binding Flag

Key: com.iplanet.amagent.config.filter.authSessionBinding

Description: This property specifies if the Agent will enforce session binding with authentication.

Valid Values: true/false. The default value of this property is set to false.

Example: com.iplanet.amagent.config.filter.authSessionBinding=false


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. The default value of this property is set to true.


Note Valid but inappropriate value of this property may lead to the application being unreachable by the users.


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. The default value of this property is DefaultWebApp


Note 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.

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.


Note 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

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


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.


Note
  • 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.

  • This property must specify a URI that is within the application. Failure to do so can result in runtime internal server errors.

  • The format for specifying this property is as follows:

    com.iplanet.amagent.config.filter.AppName.accessDeniedURI=URI

    where AppName is the context path name for the deployed application and URI is the URI to be used. Note that the difference between AppName and context path of the application is that the context path has a leading / character.

  • 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.

  • In case when this 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/Ac cessDenied.html

com.iplanet.amagent.config.filter.BankApp.accessDeniedURI=/BankApp/ Block.jsp

com.iplanet.amagent.config.filter.DefaultWebApp.accessDeniedURI=/UR LAccessDenied.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 forward-slash 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 AppNames 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.notEnforcedList0]=/index.html

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


Debug Engine Configuration

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


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: A string that represents the complete path name of the file to be used by Agent to record Debug messages.


Note
  • Be sure that the WebLogic 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.lo g


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. The 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. Default value of this property is 52428800 bytes (~ 50 MB) and should be changed as required.


Note 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, refer URL:

http://java.sun.com/j2se/1.3/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. The default value of this property is true and should be changed as necessary.


Note
  • 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 WebLogic 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 WebLogic 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 WebLogic Server should be launched according to the following steps for Solaris, Windows, or HP-UX platform as applicable.


Launching the Uninstallation Program on Solaris 8

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:

  1. Login as root.

  2. Go to the directory where the Agent is installed.

  3. Set your JAVA_HOME environment variable to JDK version 1.3.1 or higher. If your system does not have required version of JDK, use the JDK supplied with WebLogic 6.1 SP2 server. This JDK is located under:

    WebLogic_Install_Dir/bea/jdk131

  4. The uninstallation program 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 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_wlagent -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 next step and proceed directly to the next section, which details out the uninstallation procedure.


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

    # ./uninstall_wlagent

    The uninstallation program requires that you setup your JAVA_HOME variable correctly as pointed out in the Step 3. However, in case you have set the JAVA_HOME variable incorrectly, 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 uninstallation 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 uninstallation.


Launching the Uninstallation Program on Windows 2000

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

  1. 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.

  2. Go to the directory where Agent is installed.

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

    C:\> java -version

    java version "1.3.1_02"

    Java(TM) 2 Runtime Environment, Standard Edition (build 1.3.1_02-b02)

    Java HotSpot(TM) Client VM (build 1.3.1_02-b02, mixed mode)

    If you do not have JDK of required version in your system path, you can use the JDK supplied with WebLogic 6.1 SP2 server located at:

    WebLogic_Install_Dir\bea\jdk131

    Once this is done, the uninstall_wlagent.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_wlagent.bat

    The uninstallation program provides two types of interfaces—a graphical user interface (GUI) and a command line interface. By invoking the uninstall_wlagent.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 uninstallation program for uninstalling the Agent, the uninstallation program may be launched by executing the uninstall_wlagent.bat file and passing in a command line argument -nodisplay as follows:

    C:\Sun>uninstall_wlagent.bat -nodisplay

    This can be done by typing the above command in a command prompt window in a directory where this file is available.


    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 WebLogic 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 control 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.



Launching the Uninstallation Program on HP-UX 11

The uninstallation program for HP-UX 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:

  1. Login as root.

  2. Go to the directory where the Agent is installed.

  3. Set your JAVA_HOME environment variable to JDK version 1.3.1 or higher. If your system does not have JDK of required version, use the JDK supplied with WebLogic 6.1 SP2 server. This JDK is located under:

    WebLogic_Install_Dir/bea/jdk131

  4. The uninstallation program 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 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_wlagent -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 based uninstallation program using the -nodisplay option, you may skip the next step and proceed directly to the next section, which details out the uninstallation procedure.


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

    # ./uninstall_wlagent

    The uninstallation program requires that you setup your JAVA_HOME variable correctly as pointed out in the step number 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):

    Specify the JAVA_HOME value to the uninstallation program by typing in the full path to the JDK installation directory that should be used for launching the installer. Otherwise, enter a period (.) to abort the uninstall.

    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 uninstallation.


Uninstalling the Agent Using GUI

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

  1. 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 2-7    Uninstall Type Selection Screen

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

  2. The Uninstall Progress screen displays the progress of uninstall process.

  3. 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 2-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. See the next section for details on how to restore the system to its original state.



Troubleshooting Uninstallation Problems

During the installation, the Agent Installer performs modifications for certain existing files on your system. In order that these modifications can be backed out completely, backups of these files are created before the modifications are made. In case you encounter any failures during the uninstall, it is possible to bring the system back to its original state manually by restoring the backed up files.

The following is a list of files that are backed up during installation and restored during the uninstall of the Agent:


WebLogic Server Startup Script

The WebLogic Startup script is modified during installation and the backup is created in the same directory as the startup script. The name of the backup file is WebLogic_Startup_Script_Name-preAgent. For example, if the WebLogic startup script that you specified during installation was:

/bea/wlserver6.1/config/examples/startExamplesServer.sh

then, the backup file will be:

/bea/wlserver6.1/config/examples/startExamplesServer.sh-preAgent


WebLogic config.xml

The WebLogic Server's master configuration file, config.xml, although is not modified by the installer, is still backed up into the corresponding config.xml-preAgent file. This is done because after the Agent is installed, the WebLogic Server must be configured with the Agent Realm component, which results in modifications to the underlying config.xml file. If this file is not restored to its original state, the uninstall of Agent will leave the WebLogic Server configured to use the Agent Realm component which would no longer be available on your system. This may result in the WebLogic Server becoming unusable. Thus, when you remove the Agent, the config.xml is restored to its original state thereby bringing the WebLogic Server's configuration back to the state it was in before the installation of the Agent.


java.security file

The Agent installer installs the JCE and JSSE extensions to the JDK installation being used by WebLogic Server. These extensions require that the specific providers be entered into the JDK installations security file so that they are available at runtime. Before these providers are entered into the security file, a backup of the security file is created so that it can be restored during the uninstall of the Agent. The backup file is named java.security-preAgent, and is located in the JDK installation's jre/lib/security directory. For example, if during the install you entered the WebLogic JAVA_HOME value as /bea/jdk131, the java.security file will be:

/bea/jdk131/jre/lib/security/java.security

and the backup file will be:

/bea/jdk131/jre/lib/security/java.security-preAgent


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

Last Updated January 20, 2003