|
| Sun ONE Identity Server Policy Agent Guide |
Chapter 7 Policy Agent for WebLogic 6.1 SP2
This chapter describes how to install and configure Sun ONE Identity Server Policy Agent for WebLogic 6.1 SP2 Application Server. Topics include:
- Supported Platforms
- Guidelines
- Installing the Agent
- WebLogic Server Configuration
- Application Configuration
- Agent Configuration
- Using Agent and Sun ONE Identity Server SDK APIs
- Uninstalling the Agent
Supported Platforms
The Sun ONE Identity Server Policy Agent for WebLogic 6.1 SP2 is supported on the following platforms:
- Solaris 8
- Windows 2000 Server
- HP-UX 11
How the Policy Agent for WebLogic 6.1 SP2 Works
The Sun ONE Identity Server Policy Agent for WebLogic 6.1 SP2 consists of two main components that affect the operation of WebLogic 6.1 SP2 as well as the behavior of the protected application. These components are:
- Agent Realm. The Agent Realm component provides the ability to WebLogic 6.1 SP2 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 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 an 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
In order to use the Sun ONE Identity Server Policy Agent for WebLogic 6.1 SP2 in the most optimal manner, it is recommended that you follow the following guidelines:
- 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 such as Single Sign-On (SSO). 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 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 custom tailored to work in the security framework offered by Identity Server. For more information on how to use the Sun ONE Identity Server SDK, refer to 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 platforms—Solaris 8, Windows 2000 Server, or HP-UX 11. The installation program for 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:
- Install the WebLogic Server 6.1 SP2.
Refer to 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.
- 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 and then perform the following steps to launch the installation program:
- Login as root.
- Unzip the binary archive using the following command:
# gzip -dc j2eeagents-2.0-domestic-us.sparc-sun-solaris2.8.tar.gz | tar xvf -
- 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. The JDK is located under:
WebLogic_Install_Dir/bea/jdk131
The installation program provides two types of interfaces—a 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.
- 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:
Enter JAVA_HOME location (Enter "." to abort):
Type the full path to the JDK installation directory used 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.
Note You can also use agent_SunOS.class file to install the agent. You can find this file in the directory where you have untarred the binaries
Launching the Installation Program on Windows 2000 Server
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:
- 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.
- 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.
Note You can also use agent_WINNT.class file to install the agent. You can find this file in the directory where you have unzipped the binaries.
Using setup.bat
In order to use the setup.bat file to launch the installation program, you must have a JDK version 1.3.1 or higher available in your system path. 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 a 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 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 GUI and a command line interface. You can launch the installation program in the GUI mode by invoking setup.bat file from a command prompt window as shown above or by double clicking it in Windows Explorer. The installation program may be launched in a command line mode by passing the argument -nodisplay to the setup.bat script as follows:
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. Using setup.exe you can launch only the GUI 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. Perform the following steps to launch the installation program:
- Login as root.
- Unzip the binary archive using the following command:
# gzip -dc j2eeagents-2.0-domestic-us.hppa1.0-hp-hpux11.00.tar.gz | tar xvf -
- 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. The JDK is located under:
WebLogic_Install_Dir/bea/jdk131
- The installation program provides two types of interfaces—a 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.
- 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 used 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, answering the questions.
- Read the License Agreement. Click Yes (Accept License) to continue with the Installation.
- 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.
- 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 Identity Server Policy Agent for WebLogic Server 6.1 SP2, which is selected by default.
Figure 7-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 7-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.
- In the Directory Server Information screen, provide the following information about the Directory Server that is associated with Sun ONE Identity Server services.
Figure 7-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 WebLogic Server Details screen, provide the following information about the WebLogic Server on which the Agent is installed.
Figure 7-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 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. See Appendix A.
- 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.
- 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 7-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 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 not be left blank and should have a valid FQDN of the Agent enabled Server. For example, if the Agent is installed on a WebLogic Server that may be accessed by using the URL http://www.mycompany.com:80/, then the Host URL should be set to http://www.mycompany.com:80/ as well.
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 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 the Users, Roles, and the Users who are assigned to these Roles in 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. The Host URL is also used by the Agent to provide for the default FQDN to be used in cases where required. For example, if the user types in the URL http://mycompany/SomeApp/SomeModule and the Host URL is set to http://www.mycompany.com:80/, the Agent will first redirect the user to http://www.mycompany.com:80/SomeApp/SomeModule before taking any other action. This will ensure that the domain specific SSO Cookie that is used by the Agent to identify the user is available. Another 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. This configuration value can also be used to override the default behavior, however, an incorrect value may lead to the application becoming inaccessible. It is therefore recommended that this value be left to the default value chosen by the installer unless there is a specific need based on the deployment scenario, which calls for setting this value appropriately.
- When Specifying the Host URL in the installer screen, ensure that the protocol, fully qualified host name, and the port that are displayed by the installer are valid and match the actual deployment scenario. For instance, if you intend to use the Agent to protect a WebLogic Server in the SSL mode, you must ensure that the Host URL has "https" as its protocol.
- 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.
- The parameters entered during installation can be modified later by editing the AMAgent.properties file, see "Agent Configuration."
- 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, click Next to proceed.
Figure 7-6 Summary of all the selections Screen
- In the Ready to Install screen, click Install Now button to begin the installation.
- 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.
- 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.
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 at: http://www.bea.com.
In order to install the Agent Realm, the following steps must be performed:
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:
- Logon to the WebLogic Server Administration Console. Use the configured system username and password for logging on to the console.
- In the left pane of the WebLogic Server Administration Console, expand the Security Node by clicking the "+" sign.
- 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.
- On the right pane, click the "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.
- In this form, enter the following information and click on Create:
Name: Agent Realm
Realm Class Name: com.iplanet.amagent.weblogic.realm.AgentRealm
- After creating the new Realm, restart the WebLogic Server.
Once the WebLogic Server is restarted, using the Administration Console, navigate to Security > Realms node. You should be able to see the newly created Agent Realm in the list of Realms displayed on the right 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:
- Logon to the WebLogic Server Administration Console. Use the configured system username and password for logging on to the console.
- In the left pane of the WebLogic Server Administration Console, expand the Security Node by clicking the "+" sign next to it.
- 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.
- 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.
- In this form, enter the following information:
Name: Agent Caching Realm
Basic Realm: Select Agent Realm from the pull down menu.
- Click on the Create button. This refreshes the right pane and a new Caching Realm is created. The right pane displays the configuration of this newly created Caching Realm.
- In the right pane, disable all the caching attributes. This can be done as follows:
- Click the ACL Tab. This displays the ACL caching attributes.
- Uncheck the check box next to Enable ACL Cache.
- Click on the Apply button.
- 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.
- Restart the WebLogic Server.
Once the WebLogic Server is restarted using the Administration Console, navigate to 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:
- Logon to the WebLogic Server Administration Console.
- On the left pane click the Security node. This forces the console to display the Security configuration of the WebLogic Server in the right pane.
- In the right pane, click the Filerealm tab. This causes the console to display the details of the current File Realm.
- In the form that is displayed on the right pane, under Caching Realm, select the Agent Caching Realm from the pull down menu.
- Click the Apply button.
- Restart the WebLogic Server.
Once the File Realm is configured and the WebLogic Server is restarted, the Agent Realm has been successfully installed.
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 to the information provided in 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 before the installing 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 Sun ONE 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 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:
- 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.
- 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">
- 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>
- 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 to the information provided in Appendix B 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 to the WebLogic Server documentation on how to use the Administration console to create such mappings for deployed applications.
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/wlAgent/amAgent/config/AMAgent.properties
This file may be edited to provide general as well as application-specific configuration for the Agent.
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.sun.am.policy.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.sun.am.policy.config.filter.SomeApp.notEnforcedList[0]=/SomeApp/public/*
com.sun.am.policy.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 (see "Agent Configuration" for information on how this feature is configured), 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.sun.am.policy.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
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.sun.am.policy.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.sun.am.policy.config.filter.DefaultWebApp.notEnforcedList[0]=/index.html
com.sun.am.policy.config.filter.DefaultWebApp.notEnforcedList[1]=/about.html
com.sun.am.policy.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.sun.am.policy.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.sun.am.policy.config.filter.global.notEnforcedList[0]=*.gif
com.sun.am.policy.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 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.
The settings provided in this file can be classified into the following categories:
- Common Configuration
- Audit Configuration
- Realm Configuration
- Global Filter Configuration
- Application Filter Configuration
- Debug Engine Configuration
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.sun.am.policy.config.org
Description: This property specifies the organization name to be used when searching for principals in Sun ONE Identity Server.
Valid Values: String representing 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.sun.am.policy.config.org=iplanet.com
Root Suffix
Key: com.sun.am.policy.config.rootsuffix
Description: This property specifies the root suffix to be used when searching for principals in Sun ONE Identity Server
Valid Values: String representing 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.sun.am.policy.config.rootsuffix=o=isp
People Container Level
Key: com.sun.am.policy.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.sun.am.policy.config.realm.peopleContainerLevel=1
Audit Configuration
These settings are exclusively used to configure the Audit Engine used by the Agent.
Language Code
Key: com.sun.am.policy.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.sun.am.policy.config.audit.localeLanguageCode=en
Country Code
Key: com.sun.am.policy.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:
Example: com.sun.am.policy.config.audit.localeCountryCode=US
Audit Log File
Key: com.sun.am.policy.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
Example: com.sun.am.policy.config.audit.logfile.name=/audit/agent.log
Audit Log File Rotation Flag
Key: com.sun.am.policy.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.sun.am.policy.config.audit.logfile.rotate=false
Audit Log File Rotation Size
Key: com.sun.am.policy.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.sun.am.policy.config.audit.logfile.rotate.size=52428800
Note This property is not used when audit log file flag value is false.
Realm Configuration
These settings are used to configure the Agent Realm component.
Allow Console Integration Flag
Key: com.sun.am.policy.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
Example: com.sun.am.policy.config.weblogic.allowConsoleIntegration=true
SSO Cache Cleanup Size
Key: com.sun.am.policy.config.realm.ssoCacheCleanupSize
Description: This property specifies the maximum number of entries in the SSO Cache maintained by the Agent Realm after which a cleanup will be initiated.
Valid Values: Any positive integer value indicating the number of entries in the Agent Realm's SSO Cache which when exceeded will initiate a clean up operation to ensure minimal and appropriate use of the system's memory.
Example: com.sun.am.policy.config.realm.ssoCacheCleanupSize = 1000
SSO Cache Cleanup Lock Time
Key: com.sun.am.policy.config.realm.ssoCacheCleanupLockTime
Description: This property specifies the amount of time in seconds that the Agent Realm will wait before initiating the next cleanup process for the SSO cache if the last cleanup process did not result in freeing any memory.
Valid Values: Any positive integer value indicating the number of seconds that the cleanup process will not be restarted if the last cleanup process did not result in freeing sufficient memory.
Example: com.sun.am.policy.config.realm.ssoCacheCleanupLockTime = 1200
SSO Cache Cleanup Bound Size
Key: com.sun.am.policy.config.realm.ssoCacheCleanupBoundSize
Description: This property specifies the maximum number of entries in the Agent Realm SSO Cache that will be inspected during cleanup process. This value when set appropriately will result in overall improvement of the response time of the system when it undergoes a cache cleanup operation.
Valid Values: Any positive integer value indicating the number of entries the cleanup process will inspect in the SSO cache during the cleanup operation. This value can be set independently with respect to the value of the property com.sun.am.policy.config.realm.ssoCacheCleanupSize.
Example:
com.sun.am.policy.config.realm.ssoCacheCleanupBoundSize = 50
Global Filter Configuration
These settings are used to configure the Agent Filter component.
SSO Token Name
Key: com.sun.am.policy.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.sun.am.policy.config.filter.ssoTokenName=iPlanetDirectoryPro
FQDN Map
Key:
com.sun.am.policy.config.filter[invalid-name]
Description: The FQDN Map is a simple map that enables the Agent to take corrective action in the case where the users may have typed in an incorrect URL such as by specifying partial hostname or using an IP address to access protected resources.
Valid Values: Valid values must comply with the syntax of this property which represent invalid FQDN values mapped to their corresponding valid counterparts.
The format for specifying this property is as follows:
com.sun.am.policy.config.filter.fqdnMap[invalid-name]=valid-name
Where invalid-name is a possible invalid FQDN host name that may be used by the user, and the valid-name is the FQDN host name the filter will redirect the user to.
Example:
com.sun.am.policy.config.filter[myserver]=myserver.mydomain.com
com.sun.am.policy.config.filter[myserver.mydomain]=myserver.mydomai n.com
com.sun.am.policy.config.filter[IP]=myserver.mydomain.com
com.sun.am.policy.config.filter[invalid-name]=valid-name
Login URL
Key: com.sun.am.policy.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.sun.am.policy.config.filter.loginURL=http://myserver.mydomain.com:58080/amserver/login
Host URL
Key: com.sun.am.policy.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.
If left unspecified, the Agent will try to reconstruct the host URL from the request.
Example: com.sun.am.policy.config.filter.hostURL=http://www.iplanet.com:80
Goto Parameter
Key: com.sun.am.policy.config.filter.gotoParameter
Description: This property specifies the goto parameter name to be used by the Agent when redirecting the user to the appropriate authentication service. The value of this parameter is used by the authentication service to redirect the user to the original requested destination.
Valid Values: A string value that represents the goto parameter name as expected by the authentication service.
Example: com.sun.am.policy.config.filter.gotoParameter=goto
Login Attempt Limit
Key: com.sun.am.policy.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
Example: com.sun.am.policy.config.filter.loginAttemptLimit=5
Login Counter Cookie Name
Key: com.sun.am.policy.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.sun.am.policy.config.filter.loginCounterCookieName=iPlanetLoginAttemptID
Not-Enforced-List Cache Enable Flag
Key: com.sun.am.policy.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.sun.am.policy.config.filter.notEnforcedList.cache=true
Not-Enforced-List Cache Size
Key: com.sun.am.policy.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.
Example: com.sun.am.policy.config.filter.notEnforcedList.cacheSize=1000
Not-Enforced-List Cache Expiration Time
Key: com.sun.am.policy.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.
Example: com.sun.am.policy.config.filter.notEnforcedList.cacheTime=60
LDAP Attribute Header Enable Flag
Key: com.sun.am.policy.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.sun.am.policy.config.filter.enableLDAPAttributeHeaders=true
LDAP Attribute Header Map
Key: com.sun.am.policy.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.sun.am.policy.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
Example:
com.sun.am.policy.config.filter.ldapAttribute[cn]=CUSTOM-Common-Nam e
com.sun.am.policy.config.filter.ldapAttribute[ou]=CUSTOM-Organizati on-Unit
com.sun.am.policy.config.filter.ldapAttribute[o]=CUSTOM-Organizatio n
com.sun.am.policy.config.filter.ldapAttribute[c]=CUSTOM-Country
com.sun.am.policy.config.filter.ldapAttribute[mail]=CUSTOM-Email
com.sun.am.policy.config.filter.ldapAttribute[employeenumber]=CUSTO M-Employee-Number
LDAP Date Header Attribute Format String
Key: com.sun.am.policy.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: 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.sun.am.policy.config.filter.ldapAttributeDateHeaderFormat=
EEE, d MMM yyyy hh:mm:ss zAuthentication Session Binding Flag
Key: com.sun.am.policy.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.sun.am.policy.config.filter.authSessionBinding=false
SSO Token URL Decode Flag
Key: com.sun.am.policy.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.sun.am.policy.config.filter.urlDecodeSSOToken=true
Default Web Application Name
Key: com.sun.am.policy.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.sun.am.policy.config.filter.defaultWebAppName=DefaultWebApp
Global Not-Enforced List
Key: com.sun.am.policy.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.sun.am.policy.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.sun.am.policy.config.filter.global.notEnforcedList[0]=*.gif
com.sun.am.policy.config.filter.global.notEnforcedList[1]= public/*
com.sun.am.policy.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.sun.am.policy.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.
Example:
com.sun.am.policy.config.filter.Portal.accessDeniedURI=/Portal/Acce ssDenied.html
com.sun.am.policy.config.filter.BankApp.accessDeniedURI=/BankApp/Bl ock.jsp
com.sun.am.policy.config.filter.DefaultWebApp.accessDeniedURI=/URLA ccessDenied.htm
Application Not-Enforced-List
Key: com.sun.am.policy.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.sun.am.policy.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.
Example:
com.sun.am.policy.config.filter.Portal.notEnforcedList[0]= /Portal/GuestPages/*
com.sun.am.policy.config.filter.Portal.notEnforcedList[1]= /Portal/Registration/*
com.sun.am.policy.config.filter.Portal.notEnforcedList[2]= /Portal/WebServices/PollServlet
com.sun.am.policy.config.filter.BankApp.notEnforcedList[0]= /BankApp/ModuleGuestTour/*
com.sun.am.policy.config.filter.BankApp.notEnforcedList[1]= /BankApp/index.html
com.sun.am.policy.config.filter.DefaultWebApp.notEnforcedList0]=/index.html
com.sun.am.policy.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.sun.am.policy.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
Example: com.sun.am.policy.config.debug.level=7
Debug Log File
Key: com.sun.am.policy.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
Example:
com.sun.am.policy.config.debug.logfile.name=/debug/agent_debug.log
Debug Log File Rotation Flag
Key: com.sun.am.policy.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.sun.am.policy.config.debug.logfile.rotate=false
Debug Log File Rotation Size
Key: com.sun.am.policy.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.sun.am.policy.config.debug.logfile.rotate.size=52428800
Debug Time/Date Format String
Key: com.sun.am.policy.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 to:
http://java.sun.com/j2se/1.3/docs/api/java/text/SimpleDateFormat.html
Example:
com.sun.am.policy.config.debug.date.format=[yyyy/MM/dd HH:mm:ss zzz]
Debug Print STDOUT Flag
Key: com.sun.am.policy.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.
Example: com.sun.am.policy.config.debug.print.stdout=true
Using Agent and Sun ONE Identity Server SDK APIs
You can use the Sun ONE Identity Server SDK APIs to create security and identity aware applications. Such applications can perform custom security and identity related tasks such as application level policy enforcement by exploiting the rich security and policy infrastructure offered by the Sun ONE Identity Server. When you install the Sun ONE Identity Server Policy Agent for WebLogic Server, the Sun ONE Identity Server SDK becomes available for your application to use.
While the availability of the SDK in itself is sufficient for the developers of the application to make it security aware, the Policy Agent for WebLogic further facilitates this by ensuring that the Single Sign-On (SSO) Token is available for the logged on user who at any given point in time may be using the deployed system.
When the logged on user accesses a protected resource, the Agent Filter ensures that the user be appropriately authenticated and that the corresponding Principal be available throughout the system. The Principal instance may be accessed by the J2EE programmatic security calls such as HttpServletRequest.getUserPrincipal() and EJBContext.getCallerPrincipal(). The Principal instance returned by these methods represent the user as authenticated by the Sun ONE Identity Server's authentication service. This Principal instance can then be used to access the user's SSO Token from anywhere within the application in the following two simple steps:
- Downcast the Principal to the class of type: com.iplanet.amagent.weblogic.realm.AgentUser
For example:
....
import java.security.Principal;
import com.iplanet.amagent.weblogic.realm.AgentUser;
....
Principal principal = getEJBContext().getCallerPrincipal();
AgentUser user = null;
if (principal instanceof AgentUser) {
user = (AgentUser) principal;
}
...
- Use the AgentUser API to retrieve the SSO Token associated with this principal. For example:
...
String ssoTokenId = null;
if (user != null) {
ssoTokenId = user.getSSOTokenID();
}
...
Once the SSO Token string is acquired, it can be used for subsequent calls into the Identity Server SDK APIs.
Note The Agent uses these configuration settings which ensure the availability of the SSO token associated with the user in the Agent Realm. If the values for these settings is not appropriate for your deployment scenario, it may result in the degradation of the overall system performance. See "Agent Configuration."
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.
Pre-Uninstallation Tasks
Before using the uninstaller, you must complete the following tasks in the order they are listed here. Failing to perform all or any of these tasks may result in the application becoming unusable or may result in the entire system becoming unstable and unusable.
- Agent Filter removal: Remove all the protected applications from the WebLogic server and edit their deployment descriptors to remove any references to the Agent Filter that were added during Agent installation. Also, you may remove any role-to-principal mappings that were done for these applications. Once the deployment descriptors have been edited, you may redeploy the application to the WebLogic Server. Refer WebLogic Server documentation for information on how to remove and redeploy applications that are already deployed on your system.
- Agent Realm removal: The next step in order to successfully uninstall the Agent is to remove the Agent Realm configuration. This can be done by the following steps given below:
- Logon to the WebLogic Server Administration Console. Use the configured system username and password for logging on to the console.
- On the left pane click the Security node. This forces the console to display the Security configuration of the WebLogic Server in the right pane.
- In the right pane, click on the Filerealm tab. This causes the console to display the details of the current File Realm.
- In the form that is displayed on the right pane, under Caching Realm, select the appropriate Caching Realm other than the Agent Caching Realm that you would like to use. If no other Caching Realms are configured, you can safely choose the defaultCachingRealm entry.
- Click the Apply button.
- Restart the WebLogic Server.
Once the File Realm is configured and the WebLogic Server is restarted, the WebLogic Server will no longer use the Agent Realm. At this point, it is safe to uninstall the Agent using the supplied uninstaller. You may skip to the next section that details the steps necessary to use the supplied uninstaller. However, we recommend that you follow the remaining steps in this section to remove the Custom Realm and the Caching Realm that was created during the installation of the Agent.
- Agent Caching Realm removal: After the File Realm has been configured not to use the Agent Caching Realm, the Agent Caching Realm can be safely removed from you system. This can be done by the following steps:
- Logon to the WebLogic Server Administration Console. Use the configured system username and password for logging on to the console.
- In the left pane of the WebLogic Server Administration Console, expand the Security Node by clicking on the "+" sign next to it.
- In the left pane under Security node, click the Caching Realms. This forces the console to display a list of available Caching Realms in the system on the right pane.
- On the right pane, locate the row corresponding to the Agent Caching Realm. In the last column of this row, click on the delete icon image. A message is displayed to confirm the deletion of Agent Caching Realm. Read this message carefully to ensure that the Caching Realm that will be deleted will be Agent Caching Realm. Click on the yes button to confirm your decision. The console displays a confirmation message. Click on the Continue link located below this message.
- On the right pane, an updated list of Caching Realms will be displayed. Verify that there is no mention of Agent Caching Realm in this list.
- Restart the WebLogic Server.
Once the WebLogic Server has been restarted, you can remove the Agent Realm that was configured during the Agent installation.
- Agent Realm removal: After the removal of Agent Caching Realm, the associated Custom Realm - Agent Realm can be removed. This can be done by the following steps:
- Logon to the WebLogic Server Administration Console. Use the configured system username and password for logging on to the console.
- In the left pane of the WebLogic Server Administration Console, expand the Security Node by clicking on the "+" sign next to it.
- In the left pane under Security node, click the Realms. This forces the console to display a list of available Realms in the system on the right pane.
- On the right pane, locate the row corresponding to the Agent Realm. In the last column of this row, click on the delete icon image. A message is displayed to confirm the deletion of Agent Realm. Read this message carefully to ensure that the Realm that will be deleted will be Agent Realm. Click on the yes button to confirm your decision. The console displays a confirmation message. Click on the Continue link located below this message.
- On the right pane, an updated list of Realms will be displayed. Verify that there is no mention of Agent Realm in this list.
- Restart the WebLogic Server.
Once the WebLogic Server is restarted, all the configuration settings that were made to the system during the installation of Agent have been removed. You can now proceed to the next section that describes how to use the Agent uninstaller to remove the Agent libraries from your system.
Launching the Uninstallation Program
Before launching the uninstaller program, make sure that the WebLogic Server is not running. Failing to do so can result in corruption of WebLogic startup which in turn can result in the system becoming unusable. When you are certain that the WebLogic Server is not running, you can launch the uninstallation program to remove Agent libraries and other files from your system.
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 uninstall the Agent:
- Login as root.
- Go to the directory where the Agent is installed.
- 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
- The uninstallation program provides two types of interfaces—a 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 it is recommended that you use the command line uninstallation program for uninstalling the Agent. You can launch this by executing the following command:
#./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.
- 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, if 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 that should be used 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.
Note You can also use uninstall_Sun_ONE_Identity_Server_Policy_Agent.class file to uninstall the agent. You can find this file in the directory where you have installed the Agent.
Launching the Uninstallation Program on Windows 2000 Server
The uninstallation program for the Windows 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.
- Go to the directory where Agent is installed.
- 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 the 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 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 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.
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:
- Login as root.
- Go to the directory where the Agent is installed.
- Set your JAVA_HOME environment variable to a 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
- The uninstallation program provides two types of interfaces— a 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, 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.
- 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):
Type the full path to the JDK installation directory that should be used 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 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.
- In the Uninstall Type Selection Screen select Full and click Next.
- 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
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
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