|
| Sun ONE Identity Server Policy Agent Guide |
Chapter 9 Policy Agent for Sun ONE Application Server 7.0
This chapter describes how to install and configure Sun ONE Identity Server Policy Agent for Sun ONE Application Server 7.0. Topics include:
- Supported Platforms
- Guidelines
- Installing the Agent
- Application Configuration
- Agent Configuration
- Uninstalling the Agent
Supported Platforms
The Sun ONE Identity Server Policy Agent for Sun ONE Application Server 7.0 is supported on the following platforms:
- Solaris 8
- Solaris 9
- Windows 2000 Server
Guidelines
In order to use the Sun ONE Identity Server Policy Agent for Sun ONE Application Server 7.0 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 Agent for Sun ONE Application Server 7.0 can be installed on these platforms—Solaris 8, Solaris 9, or Windows 2000 Server. The following sections provide the detailed steps necessary for installing the Agent on each of these platforms.
Pre-installation Tasks
The following tasks must be completed before the Agent can be installed:
- Install Sun ONE Application Server 7.0
Refer Sun ONE Application Server documentation for the necessary details. When the server is installed, test the installation by using the provided sample Applications to ensure that the server is installed correctly.
- Test the deployment of application that you intend to protect
Before installing the Agent, it is important that the application that must be protected be deployed and tested for simple functionality. Once it is established the application can be deployed successfully, you are ready to install the Agent.
- Stop the Application Server instance on which you want to install the Agent.
Stop the Application Server instance using the following command: /S1AS_Install_Dir/SUNWappserver7/domains/domain-instance/server-instance/bin/stopserv
Launching the Installer on Solaris Platform
The binaries for Sun ONE Identity Server Policy Agent for Sun ONE Application Server 7.0 for Solaris 8 and Solaris 9 platform is provided as a tar-gzip archive. Copy this archive on the machine where Sun ONE Application Server is installed. Perform the following steps to launch the installation program:
- Login as root.
- Unzip the binary archive in a convenient location using the following command:
# gzip -dc AS70_agent_2.0_sparc-sun-solaris2.8.tar.gz | tar xvf -
- Set your JAVA_HOME environment variable to JDK version 1.4.0 or higher. If your system does not have the required version of JDK, use the JDK supplied with Sun ONE Application Server 7.0. This JDK is located under:
S1AS_Install_Dir/jdk
The installation 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 installing the Agent. However, in cases when you are installing the Agent over a telnet session on a remote server and do not have windowing capabilities, then the GUI program cannot be used. In such a case, it is recommended that you use the command line installation program. This can be launched by executing the setup script and passing a command line argument -nodisplay as follows:
# ./setup -nodisplay
However, if you choose to use the GUI program, then it is required that you set your DISPLAY environment variable to ensure that the GUI installation screens appear on the correct console.
.
Note If you choose to use the command-line program using the -nodisplay option, you may skip the following step and proceed directly to the next section, which details out the installation procedure.
- Launch the GUI installer by invoking the setup script as follows:
# ./setup
The 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 supplying the correct JAVA_HOME value:
Enter JAVA_HOME location (Enter "." to abort):
Type the full path to the Sun ONE Application Server JDK installation directory for launching the installation program. Otherwise, enter a period (.) to abort the installation.
In order that the GUI installer be displayed on your console, the DISPLAY environment variable of your shell must be set correctly. If your DISPLAY environment variable is not set at the time of invoking the setup script, the installer will prompt you for the DISPLAY environment variable value as follows:
Please enter the value of DISPLAY variable (Enter "." to abort):
Provide the DISPLAY value by typing the exact value at the above prompt. Otherwise, enter a period (.) to abort the installation.
Note You can also use agent_SunOS.class file to install the agent. You can find this file in the directory where you have untarred the binaries.
Launching the Installer on Windows 2000 Server
The binaries for Sun ONE Identity Server Policy Agent for Sun ONE Application Server 7.0 for Windows platform are provided as a zip archive. Copy this archive on to the machine where Application Server server is installed. Perform the following steps to launch the installation program:
- You must have administrative privileges when you run the installation program. If you do not have administrative privileges, either log on as the "Administrator" user or request such privileges to be granted to your account by the system administrator of the machine or domain as applicable.
- Unzip the Agent binaries in a convenient location. This may be done by using any Zip utility available on your system.
The above operation results in two executable files setup.bat and setup.exe, which may be used to launch the installer. Each of these two files provide different features for launching the installer. You can choose either of these two files depending upon your installation requirements.
Using setup.bat
In order to use the setup.bat file to launch the installer, you must have JDK version 1.4.0 or higher. This can be verified by typing the following command in a command prompt window:
C:\> java -version
java version 1.4.0_02
Java(TM) 2 Runtime Environment, Standard Edition (build 1.4.0_02-b03)
Java HotSpot(TM) Client VM (build 1.4.0_02-b03, mixed mode)
If you do not have JDK of required version in your system path, you can use the JDK supplied with Application Server 7.0 located at:
S1AS_Install_Dir\jdk
The setup.bat can be executed by typing the file name at the command prompt window in a directory where it is present, or by double clicking the file in Windows Explorer. For example:
C:\>setup.bat
The installation program provides two types of interfaces—a GUI and a command line interface. By invoking the setup.bat file from a command prompt window or by double clicking the file in Windows Explorer, the installation program is launched in the GUI mode. To launch the installation program with the command line argument -nodisplay, type the following:
C:\>setup.bat -nodisplay
Using setup.exe
You can invoke setup.exe either from the command prompt window or by double clicking the file from Windows Explorer. Unlike setup.bat, setup.exe does not take the -nodisplay command line argument and can launch only the GUI program.
Installing the Agent Using GUI
The installation program begins with a Welcome screen. Click Next to step through the installation screens, answering the questions.
- Read the License Agreement. Click Yes (Accept License) to continue with the installation.
If you do not accept all the terms of the Software License Agreement, click No to end the Installation program without installing the product.
- In the Select Installation Directory screen, enter the path where you want to install the Agent.
Figure 9-1 Select Installation Directory screen
If you wish to install the Agent in a directory different from the default installation 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 Sun ONE Identity Server Information screen, provide the following information about the Sun ONE Identity Server and click Next.
Figure 9-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. For example, nila.eng.siroe.com.
Sun ONE Identity Server Port: Enter the port number for the Web Server that runs Sun ONE Identity Server Services. The default port number is 58080.
Sun ONE Identity Server Protocol: Select the protocol that will be used by the Agent to communicate with Sun ONE Identity Server services. If the web server has been configured for SSL, select HTTPS; otherwise select HTTP.
Sun ONE Identity Server Deployment URI: Enter the URI that should be used for accessing Sun ONE Identity Server Services. The default URI is amserver.
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 9-3 Directory Server Information Screen
Directory Host: Enter the fully qualified host name of the system where the Directory Server is installed.
Directory Port: Enter the port number used by the Directory Server.
Root Suffix: Enter the root suffix to be used with this Directory Server.
Installation Organization: Enter the name of the installation organization as used when installing the Sun ONE Identity Server.
- In the Sun ONE Application Server Details screen provide the following information about the Sun ONE Application Server on which the Agent is installed.
Figure 9-4 Sun ONE Application Server Details Screen
Sun ONE Application Server config Directory: Enter the full path to the location of the config directory of the Application Server instance.
Sun ONE Application Server JAVA_HOME directory: Enter the full path to the location of the JDK installation home used by the Sun ONE Application Server.
Name of the Agent Realm: Enter the name of the Realm that will be configured as the default realm to be used by Sun ONE Application Server.
The Sun ONE Application Server config directory is used to modify server.xml, login.conf and server.policy under this directory. Default location is the following directory:
S1AS_Install_Dir/SUNWappserver7/domains/domain-instance/server-instance/config
The Sun ONE Application Server JAVA_HOME directory refers to the JDK installation that is used by the Sun ONE Application Server. Typically the value of this is the full path to the following directory:
S1AS_Install_Dir/usr/j2se
In case the value supplied is incorrect or is not the JDK used by the Application Server, it will result in malfunction of the Agent. To avoid this problem, ensure that the value you specify for Sun ONE Application Server JAVA_HOME is accurate.
- In the Agent Configuration Details screen provide the key configuration information necessary for the Agent to function correctly.
Figure 9-5 Agent Configuration Details Screen
Audit Log File: Enter the complete path to the log file to be used by the agent to record Audit messages.
Enable Audit log file Rotation: Select this item to enable rotation of Audit Log files.
Host URL: Enter a valid URL to be used as the base URL by the Agent to redirect users as necessary. This value may 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 item to enable caching of Not-Enforced List evaluation results.
Number of Entries in Cache: Specify the number of entries that cache can hold at a given instance.
Cache Expiration Time: Specify the time in seconds to be used as the limit for entries that can exist in the Not-Enforced List cache.
Enable LDAP Attribute Headers: Select this item to enable the passing LDAP attributes associated with the current user as HTTP Headers.
Agent Configuration Details
- The Audit Log file is a necessary requirement for the Agent. You may provide the name of a non-existing file on the system to be used as the Audit file. In which case, the Agent creates this file and the necessary directories in its path on first use. Alternatively, you can provide the file name of an existing file, which can be used by the Agent as well. However, in either case, it is required that the specified file has write permissions for the Application Server process. This is because the Agent executes in the same process as the Sun ONE Application Server. Providing an incorrect value for this will result in the malfunction of the Agent, which can render the Application Server unusable.
- When a request is intercepted by the Agent without sufficient credentials, the Agent redirects the user to the 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 installation program screen, ensure that the protocol, fully qualified host name, and the port that are displayed by the installation program are valid and match the actual deployment scenario. For instance, if you intend to use the Agent to protect a Sun ONE Application 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 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 are 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 and hence can be easily avoided.
- The parameters entered during installation can be modified later by editing the AMAgent.properties file. For detailed information, see the section "Agent Configuration" later in this chapter.
- In the Summary screen review and verify the installation options that you have specified for the Agent. In case you find that certain values are in error, you may navigate back and correct them before proceeding further. Click the Next button to proceed with the installation.
- In the Ready to Install screen, click the Install Now button to begin the installation.
- The Install Progress screen displays the progress of the installation as the installer makes changes to your system. If necessary, you may interrupt this process by clicking the Stop button.
- In the Installation Summary window, click Details for a detailed summary of the configuration information that was processed during installation. Click Exit to end the program.
The Agent installation program modifies the Application Server's server.xml file to include certain libraries in the Application Server CLASSPATH, as well as adds certain required parameters to the JVM options. For the changes to take effect you must configure application server, which can be done by following either of these methods:
- To apply changes to the application server instance using the Administration interface, perform the following steps:
- Access the Administration interface and click the name of the application server interface you want to reconfigure.
- Click the General tab.
- Click Apply Changes.
When the changes are applied, the screen displays the message "Changes applied to instance."
- To configure an application server instance using the command-line interface, execute the following command:
Installing the Agent Using Command-Line
You must have root permissions when you run the agent installation program.
- Run the setup program with the command line argument -nodisplay. You'll find the program in the directory where you untarred the binaries.
# ./setup -nodisplay
- When prompted provide the following information:
Have you read, and do you accept, all of the terms of the preceding Software License Agreement? Type Yes.
Install Sun(TM) ONE Identity Server Agent in this directory: Enter the full path to the directory in which you want to install the Policy Agent.
- Provide the following information about the Web Server that runs Identity Server:
Sun(TM) ONE Identity Server Services Details.
Sun(TM) ONE Identity Server Host [nila.Eng.Siroe.COM] {"<" goes back, "!" exits}:
Sun(TM) ONE Identity Server Port [58080] {"<" goes back, "!" exits}:
Sun(TM) ONE Identity Server Protocol [http] {"<" goes back, "!" exits}:
Sun(TM) ONE Identity Server Deployment URI [/amserver] {"<" goes back, "!" exits}:
amAdmin Password [] {"<" goes back, "!" exits}:
Re-enter Password [] {"<" goes back, "!" exits}:
- Sun ONE Identity Server Host
- Sun ONE Identity Server Port
- Sun ONE Identity Server Protocol
- Sun ONE Identity Server Deployment URI
- amAdmin Password
- Re-enter Password
For details on each of these items, see "Installing the Agent Using GUI."
- Provide the following information about the Web Server that runs Identity Server Directory.
Sun(TM) ONE Identity Server Directory Details
Directory Host [nila.Eng.Siroe.COM] {"<" goes back, "!" exits}:
Directory Port [389] {"<" goes back, "!" exits}:
Root Suffix [dc=Siroe,dc=COM] {"<" goes back, "!" exits}:
Installation Organization [dc=Siroe,dc=COM] {"<" goes back, "!" exits}:
- Directory Host
- Directory Port
- Root Suffix
- Installation Organization
For details on each of these items, see "Installing the Agent Using GUI."
- Provide the following information about the Sun ONE Application Server.
Sun ONE Application Server config directory.
[/var/opt/SUNWappserver7/domains/domain1/server1/config] {"<" goes back, "!" exits}
Sun ONE Application Server JAVA_HOME directory [/usr/j2se] {"<" goes back,"!" exits}
Name of the Agent Realm. [agentRealm] {"<" goes back, "!" exits}
- Sun ONE Application Server config Directory
- Sun ONE Application Server JAVA_HOME directory
- Name of the Agent Realm
For details on each of these items, see "Installing the Agent Using GUI."
- Provide the configuration details for the installation of Sun ONE Identity Server Agent for Sun ONE Application Server.
Agent Audit Log File [/var/opt/SUNWam/asAgent/audit/agent.log] {"<" goes back, "!" exits}
Enable Audit log file Rotation [false] {"<" goes back, "!" exits}
Host URL [http://nila.Eng.Siroe.COM:80/] {"<" goes back, "!" exits}
Login Attempt Limit [5] {"<" goes back, "!" exits}
Enable Not-Enforced List Cache [false] {"<" goes back, "!" exits}
Enable LDAP Attribute Headers [false] {"<" goes back, "!" exits}
- Agent Audit Log File
- Enable Audit log file Rotation
- Host URL
- Login Attempt Limit
- Enable Not-Enforced List Cache
- Enable LDAP Attribute Headers
For details on each of these items, see "Installing the Agent Using GUI."
- When displayed, review the summary of the installation information you have specified. Press Enter to continue.
The following text is displayed:
Ready to Install
1. Install Now
2. Start Over
3. Exit Installation
- When prompted, What would you like to do? type 1 to start the installation.
The following text is displayed:
Installation details:
Product Result More Info
1.Sun_TM_ONE Identity Server Policy Agent Installed Available
2.Done
Enter the number corresponding to the desired selection for more information, or enter 2 to continue [2] {"!" exits}:
- To see log information, type 1. To exit the Installation program, type 2.
Silent Installation
Silent installation provides a means for scripting the installation of Sun ONE Identity Server Policy Agent. When you perform a silent installation, you use a StateFile, to predefine all the answers that you would normally supply to the setup program interactively. This saves time and is useful when you want to install multiple instances of Sun ONE Identity Server Policy Agents using the same parameters in each instance.
Silent installation is a two-step process. First you generate a StateFile that contains all the parameter information the installation program needs. Then you run the silent installation program that automatically reads the parameters you've defined in the StateFile.
Silent Installation on Solaris
To Generate a StateFile
- Run the installation program in the directory where the setup script is located. Enter the following command:
# ./setup -saveState StateFile
- Proceed through the installation program, keeping in mind that your answers to the prompts are being recorded in the StateFile.
Follow the instructions given in the section "Installing the Agent Using GUI".
When installation is complete, the file StateFile is created in the same directory as setup.
To Run the Silent Installation
Enter the following command to run the silent installation:
# ./setup -nodisplay -noconsole -state StateFile
Silent Installation on Windows 2000
To Generate a StateFile
- Run the installation program in the directory where the setup program is located. Open a DOS command prompt window and enter the following command:
setup.bat -saveState StateFile
Note As an alternative, you can use the following command:
java -classpath . agent_WINNT -saveState StateFile
- Proceed through the installation program, keeping in mind that your answers to the prompts are being recorded in the StateFile.
Follow the instructions given in the section "Installing the Agent Using GUI".
When installation is complete, the file StateFile is created in the same directory as setup.exe.
To Run the Silent Installation
Type the following command:
setup.bat -nodisplay -noconsole -state StateFile
Note As an alternative, you can use the following command:
java -classpath . agent_WINNT -nodisplay -noconsole -state StateFile
Application Configuration
The Agent Realm component of Agent for Application Server 7.0 provides runtime mapping of various principals in Sun ONE Identity Server with abstract security role names used by the hosted application in order to determine if the currently authenticated user is authorized to access a particular resource or is otherwise a member of a given role. This runtime evaluation can occur only if the user is authenticated as a Sun ONE Identity Server principal by the means of Identity Server's authentication service. Without the user being authenticated appropriately, the results of such evaluations done by the Agent Realm will always be negative, resulting in access being denied to the user for the requested resource.
It is the Agent Filter component that enforces authentication for users who try to access particular application resources, thereby enabling the Agent Realm component to correctly evaluate the principal mappings as desired.
Unlike the Agent Realm component which is installed in the core of Application Server, the Agent Filter is installed in the deployed application, which must be protected by Identity Server. This is true for every application that must be protected on the Application Server using the Agent. It is also recommended that applications that are not protected using the Agent should not deployed on the Application Server on which the Agent Realm has been installed. This is to ensure that such applications can independently enforce their own security requirements as necessary. The presence of Agent Realm will interfere with the security evaluations done by such applications resulting in their malfunction.
Installing the Agent Filter Component in an Application
The Agent Filter can be installed by simply modifying the deployment descriptor of the application that needs to be protected. The following steps outline the process to install the Agent Filter component for a given application:
- If the application is currently deployed on the Application Server, it must be removed using the Application Server's Administration Console or by the use of Application Server's deployment tools.
- It is recommended that you create a backup of the deployment descriptor that will be edited in order to install the Agent Filter in this application.
- Edit the application's web.xml deployment descriptor. Since the Filters were introduced in Servlet Specification 2.3, the web.xml's DOCTYPE element must be changed to reflect that the deployment descriptor is a Servlet 2.3 compliant deployment descriptor. This can be done by setting the DOCTYPE element as:
<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN" "http://java.sun.com/dtd/web-app_2_3.dtd">
- After the DOCTYPE element has been changed, add the Filter elements in the deployment descriptor. This can be done by specifying the Filter element and the Filter-mapping element in the web.xml deployment descriptor immediately following the description element of the web-app element. The following is a sample web.xml with the Filter and Filter-mapping elements.
<web-app>
<display-name>...</display-name>
<description>...</description>
<filter>
<filter-name>Agent</filter-name>
<display-name>Agent</display-name>
<description>SunTM ONE Idenitity Server Policy Agent for SunTM ONE Application Server 7.0</description>
<filter-class>com.sun.amagent.as.filter.AgentFilter</filter-class>
</filter>
<filter-mapping>
<filter-name>Agent</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>
...
...
</web-app>
- Once the web.xml deployment descriptor has been modified to reflect the new DOCTYPE and filter elements, the Agent Filter has been added to the application.
Creating Role-to-Principal Mapping
Once the application has been configured to have the Agent Filter component in it, the Agent Filter will enforce authentication, thereby enabling the Agent Realm to successfully resolve the role-to-principal mappings. However, these mappings must first be created in order that the hosted application may use them during runtime.
To Create Role-to-Principal Mapping
- Edit the Application Server specific deployment descriptors.
The Application Server specific deployment descriptors should be edited to create the role-to-principal mappings. These descriptors are in the files sun-application.xml and sun-ejb-jar.xml files. Refer Application Server reference documentation to learn the details on how these descriptors may be edited to create the role-to-principal mappings. Alternatively, you can refer Appendix B for sample descriptors which create such mappings.
Application-Specific Agent Configuration
Often the deployed applications are partitioned into public and protected parts, which have varying access restrictions. In most cases, the public portions of the application are accessible to anonymous users, whereas the protected portions of the application are accessible only to the registered users. The Agent can be configured to allow this type of access by letting anonymous users access the public portions of the application without requiring that they authenticate using Identity Server's authentication service. This information is provided as a part of the Agent's configuration properties file that is present in the following location:
Agent_Install_Dir/SUNWam/asAgent/amAgent/config/AMAgent.properties
This file may be edited to provide general as well as application-specific configuration for the Agent.
The properties specified in the AMAgent.properties file are required for the Agent to function properly. Invalid values specified in this file can lead to malfunction of the Agent, application becoming inaccessible, or the entire system to become unusable. It is recommended that you use extreme caution when modifying the values in this file and always create backups before such modifications to ensure that you can back out your changes to restore the system to its original state.
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 should be replaced by their appropriate values as follows:
AppName: This string should be replaced by the deployed application's context path. The context path is the first URI segment that is used to identify which application the user is trying to access. For example, if the user accesses your application by typing the URL:
http://myserver.mydomain.com/SomeApp/index.html or http://myserver.mydomain.com/SomeApp/SomeModule/doSometing.jsp
then, in both these cases, the AppName is SomeApp.
index: This is an integer value starting from 0 for every deployed application and is unique for every entry in the application not-enforced list. For example, the following are two entries of application not-enforced list for an application called with context path SomeApp:
com.sun.am.policy.config.filter.SomeApp.notEnforcedList[0]=/public/*
com.sun.am.policy.config.filter.SomeApp.notEnforcedList[1]=/images/*
pattern: This is a pattern string that will be matched with the incoming request to evaluate if the request should be allowed to pass without enforcing authentication or not. The pattern string could be a specific URI, for example /public/RegistrationServlet, or could be a generic pattern using the wild card character '*' that can be used for denoting 0 or more characters in the request URI; for example /public/* will match with any URI that begins with /public/.
Using this property, you could specify pattern strings and URIs that the Agent will treat as not-enforced. In other words, user requests that match these particular patterns will be allowed to pass through without enforcing authentication.
Providing Application-Specific Access Denied URI
In cases when the Login Attempt Limit is enabled (refer to section "Installing the Agent" for details on how this feature can be configured, or refer "Agent Configuration" for details on this feature), the Agent is required to block the user's access. The default behavior of the Agent in this situation is to send an HTTP Status Code 403 Forbidden. In such a situation, the web container can display its preconfigured Forbidden page or simply send the status code in which case the user's browser displays the details of the error message in its own manner. While this is the default behavior of the Agent, it can be changed to suit the needs of the application by allowing the Agent to use an application-specific URI that will be used as the access denied error page.
This can be done by setting the following property in AMAgent.properties file:
com.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 should be replaced by their appropriate values as follows:
AppName: This string should be replaced by the deployed application's context path. The context path is the first URI segment that is used to identify which application the user is trying to access. For example, if the user accesses your application by typing the URL:
http://myserver.mydomain.com/SomeApp/index.html or
http://myserver.mydomain.com/SomeApp/SomeModule/doSometing.jsp then, in both these cases, the AppName is SomeApp.
URI to use: is an application specific URI that the Agent will use to locate the display page for blocking the user request. This URI can be a static HTML page, or a JSP or even a Servlet. However, this URI must be a part of the application itself. In other words, this URI must begin with /AppName/rest of the URI.
Special Case: Default Web Application
A default web application in Application Server is accessible without providing any context path in the request URI. For example, the following URL is that of a default web application:
http://myserver.mydomain.com/index.html
Clearly, this URL does not have an associated context path.
For such applications, the Agent provides a convenient means of identifying that an entry is specific to the default web application. This is done in two steps as follows:
- The following property is set to a name that represents the default web application:
com.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 application. However, the only difference is that the access-denied URI of the default web application as well as the not-enforced list entries do not begin with the /DefaultWebApp/ path segment since such a path segment does not exist on the application server in reality. It is only provided as a convenience to specify the properties associated with the default web application and not their values.
Global Agent Configuration
The AMAgent.properties file provides a way to specify a global not-enforced list, which will be applicable to all the deployed applications on the server. This list is specified by using the following property:
com.sun.am.policy.config.filter.global.notEnforcedList[0]=pattern
where pattern is either an exact URI or a pattern specified by using the wild card character '*', which can be substituted for zero or more characters in the request URI.
Not-Enforced List Usage Considerations
Although the use of Not-Enforced List can be extremely helpful in partitioning your application for public and protected domains, it can also lead to undesirable effects if not used appropriately.
For example, if a request URI that represents a Servlet is matched by some not-enforced list pattern, then the Agent Filter will not enforce authentication for users who try to access that particular Servlet. However, consider the case where this Servlet access an Enterprise JavaBeans component that is protected by the Agent using role-to-principal mapping. In such a case, since the user is not authenticated, the access to the protected component will result in a an security violation exception being generated by the application server.
Therefore, before an entry is added to the not-enforced list, it must be ensured that it does in any way covers a resource that may be protected or may try to access a protected resource.
Another interesting aspect of the use of non-enforced list are the images. Typically, in a web page there are many images for various purposes like buttons, place holders, banners and logos. Every time the user accesses this page, the browser issues a request to the application server to get the images contained in this page. Each of such requests are treated as individual requests coming from the client and goes through the same evaluation mechanism for authentication and not-enforced list check as does any other request. This results in one client generating multiple calls to the server for displaying of a single page. Considering the overhead involved in enforcing authentication for every such request, it can impact the overall performance of the system. A solution to this problem is to have a global not-enforced list entry or entries that match all images. For example:
com.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 file AMAgent.properites located at: Agent_Install_Dir/SUNWam/asAgent/amAgent/config directory provides the core configuration needed by the Sun ONE Identity Server Policy Agent for Sun ONE Application Server 7.0 to function correctly. This property file provides many configuration settings that can be modified in order to customize the Agent's operation for your deployment scenario. This section provides a brief explanation of all the properties that are listed in the properties file.
Before proceeding, it is important to note that this file and the information within it are critical for the operation of the Agent. It is strongly recommended that you always create backup of this file before modifying it. Also it is strongly recommended that you do not modify this file unless you it is absolutely necessary. Please note that invalid data entries present in this file can lead to the malfunction of the Agent, the malfunction of the deployed applications, and could render the entire system unusable.
The settings provided in this file can be classified as follows:
- Common Configuration: Settings in this section are general settings that affect the behavior of the Agent as a whole.
- Audit Configuration: These settings are exclusively used to configure the Audit Engine used by the Agent.
- Global Filter Configuration: These settings are used to configure the Agent Filter component.
- Application Filter Configuration: These settings are used to configure the Agent Filter for a particular application.
- Debug Engine Configuration: These settings are used to configure the Debug Engine to generate diagnostic information.
Common Configuration
Organization Name
Key: com.sun.am.policy.config.org
Description: This property specifies the organization name to be used when searching for principals in Identity Server.
Valid Values: A string that represents the organization name in Sun ONE Identity Server
Note This property is set during Agent installation and need not be changed unless absolutely necessary.
Example: com.sun.am.policy.config.org=sun.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: A string that represents the root suffix in Sun ONE Identity Server
Note This property is set during Agent installation and need not be changed unless absolutely necessary.
Example: com.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 Identity Server, which may be used when searching for principals.
Note This property is set during Agent installation and need not be changed unless absolutely necessary.
Example: com.sun.am.policy.config.realm.peopleContainerLevel=1
Audit Configuration
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:
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. 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 Be sure the Application Server process has sufficient permissions to write to this file. Invalid value specified for this property may result in the failure of the system to start up correctly.
Example: com.sun.am.policy.config.audit.logfile.name=/var/opt/SUNWam/asAgent/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
Note 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.
Note Audit Log file rotation size is effective only when rotation flag is true.
Default value of this property is 52428800 bytes (~ 50 MB) and should be changed as necessary.
Example: com.sun.am.policy.config.audit.logfile.rotate.size=52428800
Realm Configuration
These settings are used to configure the Agent Realm component.
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
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.
Note 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.
Note 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/UI/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 without success using a single browser session, which will trigger the blocking of the user request.
Valid Values: Unsigned integer value, including 0, which indicates the number of unsuccessful login attempts that are allowed for any user trying to gain access to protected resources.
Note This option can be disabled by setting the value to 0. The default value of this property is 5.
Example: com.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.
Note 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
Note 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.
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.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.
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.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
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-Name
com.sun.am.policy.config.filter.ldapAttribute[ou]=CUSTOM-Organization-Unit
com.sun.am.policy.config.filter.ldapAttribute[o]=CUSTOM-Organization
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]=CUSTOM-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: documentation at
http://java.sun.com/j2se/1.4/docs/api/java/text/SimpleDateFormat.html
Note The default value of this property is set to EEE, d MMM yyyy hh:mm:ss z and should be changed as necessary.
Invalid value of this property may result in runtime exceptions in the application.
Example:
com.sun.am.policy.config.filter.ldapAttributeDateHeaderFormat=EEE, d MMM yyyy hh:mm:ss z
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
Note The default value of this property is set to true
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.
Note
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.
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
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.
This property is specific to the protected application. Therefore if there are more than one protected applications deployed on the system, there should be one property for each such application.
Note: This property must specify a URI that is within the application. Failing to do so can result in runtime internal server errors.
Note: The format for specifying this property is as follows:
com.sun.am.policy.config.filter.AppName.accessDeniedURI=URI
AppName is the context path name for the deployed application and URI is the URI to be used.
Example:
com.sun.am.policy.config.filter.Portal.accessDeniedURI=/Portal/AccessDenied.html
com.sun.am.policy.config.filter.BankApp.accessDeniedURI=/BankApp/Block.jsp
com.sun.am.policy.config.filter.DefaultWebApp.accessDeniedURI=/URLAccessDenied.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 `/' 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.notEnforcedList[0]=/index.html
com.sun.am.policy.config.filter.DefaultWebApp.notEnforcedList[1]=/about.html
Debug Engine Configuration
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
Note 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.
Note
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, see URL:
http://java.sun.com/j2se/1.4/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
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 Policy Agent for Sun ONE Application 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 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.sun.am.policy.as.realm.AgentUser
For example:
....
import java.security.Principal;
import com.sun.am.policy.as.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 Sun ONE Application Server software, an uninstallation program is created in the installation directory. Using this uninstallation program the Agent can be removed completely from your system. While the uninstallation program deletes all the installed files from your system, certain files such as audit log messages are not deleted. You can delete them manually.
The uninstallation program for Sun ONE Identity Server Policy Agent for Application Server should be launched according to the following steps for Solaris or Windows platform as applicable.
Launching the Uninstallation Program on Solaris
The uninstallation program for Solaris platform may be launched by executing the generated uninstall script located in the installation directory. The following steps provide details on how to achieve this:
- Login as root.
- Stop the Application Server instance using the following command:
/S1AS_Install_Dir/appserv/domains/domain-instance/server-instance/bin/stopserv
- Set your JAVA_HOME environment variable to JDK version 1.4.0 or higher. If your system does not have JDK of required version, use the JDK supplied with Sun ONE Application Server. This JDK is located under:
S1AS_Install_Dir/usr/j2se
- The uninstallation program provides two types of interfaces—a graphical user interface (GUI) and a command-line. In most cases, the GUI installer can be used for uninstalling the Agent. However, in cases when you are uninstalling the Agent over a telnet session on a remote server and do not have windowing capabilities, then the GUI uninstallation program cannot be used. In such a case it is recommended that you use the command line uninstallation program for uninstalling the Agent. This can be launched by executing the uninstall script and passing in a command line argument -nodisplay as follows:
#./uninstall_asagent -nodisplay
However, if you choose to use the GUI uninstallation program, then it is required that you set your DISPLAY environment variable to ensure that the GUI uninstallation program window appears on the correct console.
- Launch the GUI uninstallation program by invoking the uninstall script as follows:
# ./uninstall_asagent
The uninstallation program requires that you setup your JAVA_HOME variable correctly as pointed out in the Step 3. However, in case you have incorrectly set the JAVA_HOME variable, the uninstall script will prompt you for supplying the correct JAVA_HOME value:
Enter JAVA_HOME location (Enter "." to abort):
Type the full path to the JDK installation directory for launching the installation program. Otherwise, enter a period (.) to abort the uninstallation.
In order that the GUI uninstallation program be displayed on your console, the DISPLAY environment variable of your shell must be set correctly. In case your DISPLAY environment variable is not set at the time of invoking the uninstall script, the uninstallation program will prompt you for the DISPLAY environment variable value as follows:
Please enter the value of DISPLAY variable (Enter "." to abort):
Provide the DISPLAY value to the installer by typing in the exact value at the above prompt. Otherwise, enter a period (.) to abort the installation.
Launching the Uninstallation Program on Windows 2000 Server
The uninstallation program for the Windows 2000 Server platform may be launched by executing the generated uninstallation script located in the installation directory.
- You must have administrative privileges when you run the uninstallation program. If you do not have administrative privileges, either login as "Administrator" or request such privileges to be granted to your account by the system administrator of the machine or domain as applicable.
- Stop the Application Server instance using the following command:
S1AS_Install_Dir\appserv\domains\domain-instance\server-instance\bin\stopserv
- Go to the directory where Agent is installed.
- The uninstall script uninstall_asagent.bat is located in this directory. In order to use the uninstall_asagent.bat script to launch the uninstallation program, you must have JDK version 1.4.0 or higher. This can be verified by typing the following command in a command prompt window:
C:\> java -version
java version "1.4.0_02"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.4.0_02-b03)
Java HotSpot(TM) Client VM (build 1.4.0_02-b03, mixed mode)
If you do not have JDK of required version in your system path, you can use the JDK supplied with Application Server located at:
S1AS_Install_Dir\jdk
The uninstall_asagent.bat may be executed by typing the file name at the command prompt window in a directory where it is present, or by double clicking the file in Windows Explorer. For example:
C:\Sun\uninstall_asagent.bat
The uninstallation program provides two types of interfaces—a graphical user interface (GUI) and a command line interface. By invoking the uninstall_asagent.bat file from a command prompt window as shown above or by double clicking it in Windows Explorer, the uninstallation program is launched in the GUI mode. However, in a case where it is it is required that you use the command line based uninstallation program for uninstalling the Agent, the uninstallation program may be launched by executing the uninstall_asagent.bat file and passing in a command line argument -nodisplay as follows:
Agent_Install_Dir\uninstall_asagent.bat -nodisplay
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 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.
Uninstalling the Agent Using Command-Line
You must have root permissions when you run the agent installation program.
- Run the uninstall program with the command line argument -nodisplay. You'll find the program in the directory where you have installed the agent.
# ./uninstall_asagent -nodisplay
- The following text is displayed:
Sun(TM) ONE Identity Server Policy Agent for Sun(TM) ONE Application Server 7.0
Ready to Uninstall
1. Uninstall Now
2. Start Over
3. Exit
Choose one option from above [1] {"<" goes back, "!" exits}
- Enter 1 to uninstall.
The following text is displayed:
Uninstallation Summary
Installation summary Summary Result More Details
1. Sun_TM_ONE Identity Server Policy Full Enter 1 to view the log
Done
- To see log information, enter 1. To exit the Uninstallation program, press Enter.