|
| Sun ONE Identity Server Policy Agent Guide |
Chapter 8 Policy Agent 2.0 for IBM WebSphere 4.0.4 AE
This document provides a brief overview of Sun ONE Identity Server Policy Agent for IBM WebSphere Application Server 4.0.4 and describes how to install and configure the Policy Agent for WebSphere 4.0.4 running on Solaris 8 platform.
Topics include:
- Overview
- Guidelines
- Limitations
- Software Requirements
- Installing the Agent
- Configuring WebSphere Application Server
- Uninstalling the Agent
- Troubleshooting Information
Overview
The Identity Server Policy Agent for WebSphere Application Server 4.0.4 enforces authentication and authorization for clients that interact with the application through the application server's web container. The resources deployed on the WebSphere are protected by a combination of a Web Agent and a J2EE Agent.
The Identity Server Web Agent is used as a Reverse Proxy Security Server (RPSS) to perform the authentication. The RPSS authenticates the HTTP clients and passes authenticated requests to the WebSphere Application Server. The Identity Server Policy Agent is installed on the Web server (IBM HTTP, iWS, or Apache) that authenticates clients for the WebSphere Application Server. The Web Agent is used to perform authentication by redirecting the request for protected resources to the Identity Server Authentication service. The Web Agent also performs coarse grained authorization based on the Allow or Deny URL Policies defined in the Identity Server.
The J2EE authorization model is based on the concept of security roles. A security role is a logical grouping of users defined by an Application Component Provider or Assembler. Application deployer maps roles to security identities (for example, principals and groups) in the user registry. Security roles are used with declarative security (through deployment descriptor) and programmatic security. The WebSphere policy Agent enables the mapping of Identity Server security identities such as Identity Server users and Identity Server roles, to the security roles used within the J2EE Application using the Custom User Registry implementation for WebSphere 4.0.4.
The J2EE role-based authorization is performed by the WebSphere application server. The WebSphere server must trust the RPSS before accepting the authentication credentials. For WebSphere to trust the RPSS, a Web Trust Association (WTA) between WebSphere and RPSS needs to be established. This can be achieved by implementing the Web Trust Association Interceptor (WTAI) for the RPSS. The WTAI implementation establishes the trust by validating SSO Token in the request. On a successful trust validation, the WebSphere runtime uses the WTAI to retrieve principal from the request. The WebSphere runtime uses the identity information obtained from the WTAI to communicate with the user registry. The user registry is the custom registry that communicates with the Identity Server. WebSphere runtime invokes the methods of the user registry to get the set of security identities applicable for the current user. The security identities are used to determine the security roles applicable for the user. This information is used by WebSphere to implement both declarative and programmatic security.
Figure 8-1 Policy Agent for WebSphere 4.0.4 AE Architecture
Guidelines
The following guidelines will help you use the Identity Server Policy Agent for WebSphere most optimally:
Agent-based Authentication and Authorization
After the agent is installed and the application has been secured, the web agent enforces authentication for all web based access to the protected application's enforced portions. Working in tandem with the Agent Realm (Custom Registry) component, the Agent Interceptor 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. Therefore, it is recommended that protected applications do not use their own authentication mechanism or any container-based authentication mechanisms such as Basic and Form Authentication.
Coarse Grained and Fine Grained Access-control
The resources deployed on WebSphere are protected by a combination of a Web Agent and a J2EE Agent. The Web Agent is primarily used to perform authentication by redirecting the request for protected resources to the Identity Server Authentication service. It also performs coarse grained authorization based on the Allow or Deny URL Policies defined in Identity Server.
The J2EE Agent assists the WebSphere Application server to perform more fine grained access-control for individual servlets, EJBs, or EJB methods based on the security constraints and EJB method permissions defined in the deployment descriptors. The J2EE Agent maps the application-defined security roles to the principals defined in Identity Server.
The resources deployed on WebSphere Application server can be protected using either coarse grained, or fine grained access control, or a combination of both. For example, an employee portal wants to provide read access to any authenticated (regular) employee to its payroll web application, and modification or write access to only certain people. The first requirement can be achieved by defining a Allow URL Policy in the Identity Server for the application URL, applicable for the entire organization. This is coarse grained access-control. The second requirement can be met by defining the security constraint for the servlet or EJB method that performs the update or modification. The security role associated with the constraint is then mapped to privileged users and roles in the Identity Server. Access to the EJBs or servlets is then restricted only to these users. This is fine grained access-control.
The roles in the security constraint (mentioned as J2EE roles) can be mapped to either Identity Server users, or Identity Server roles. This helps achieve role-user mapping dynamically or at runtime. A user added to the Role in the Identity Server will get access to the resources protected by the J2EE role, which is mapped to this Identity Server role, immediately without having to restart the Websphere Application Server. Similarly once the user is removed from the role, the user is automatically denied the access to those resources; the Application or WAS need not be restarted.
However, the mapping of the J2EE roles to the Identity Server principals (Users and Roles) itself is static. This mapping is initially specified during the Application Deployment. However, the mapping can also be changed for the already deployed application through the WebSphere 4.0 Administrative Console.
But for these changes to take effect, the application (individual application only, and not the Application Server) needs to be restarted from the WebSphere Administrative Console.
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 customized to work in the security framework offered by Identity Server. For more information on how to use the Identity Server SDK, refer to the Sun ONE Identity Server Programmer's Guide.
Limitations
- The Policy Agent for WebSphere Application Server 4.0.4 is designed to enforce authentication and authorization for clients that interact with the application through the application server's web container. Typically, such clients are thin clients like web browsers that communicate with the application server's web container using HTTP or HTTPS protocols. If however, the client does not access the application through the HTTP or HTTPS protocols, thereby bypassing the web container of the application server, the Agent Interceptor component will not be in a position to intercept the request. This is a likely case when the application is being accessed by a rich client using other protocols such as RMI over IIOP. Since the Agent Interceptor component is bypassed in such cases, the authentication cannot be enforced. Clients that do not get authenticated by the Agent Interceptor do not possess sufficient credentials for the Agent Realm component to evaluate the necessary J2EE security policies. Therefore, such clients will be denied access to all protected resources. Alternatively, for security aware applications that use the programmatic J2EE security APIs provided in the application server will be given negative results by such APIs.
- When trust association is configured between a WebSphere Application Server and a Reverse Proxy Security Server, access to all protected resources will go through trust association. The Trust Association is bypassed for access to unprotected resources. The WebSphere Application Server does not invoke the Trust Association Interceptor when access is made to unprotected resources. If an unprotected resource accesses a protected resource, the access will always fail, even if the resource was accessed from an authenticated session, which has the roles for accessing the protected resource.
Workaround
All unprotected resources, which access protected resources must be protected with a dummy security constraint. Access to these resources should be limited to any Authenticated User, by mapping the role associated with the dummy security constraint to the special subject "All Authenticated Users." This will ensure that the Trust association is not bypassed when these resources are accessed. However, with this workaround the unprotected resource no longer remains truly unprotected.
Supported Platform
Solaris 8
Software Requirements
- Sun ONE Identity Server 6.0
- One of the following Web Servers with an appropriate Identity Server Policy Agent 2.0 installed
- Apache Server 1.3.26
- IBM HTTP Server 1.3.19
- iPlanet Web Server, Enterprise Edition 4.1 SP8
- WebSphere Application Server 4.0.4 Advanced Edition
Installing the Agent
The Identity Server Policy Agent for WebSphere 4.0.4 AE is supported on Solaris 8 platform.
Pre-Installation Tasks
The following tasks must be completed before you install the Identity Server Policy Agent for WebSphere:
- Install the database for the WebSphere Application Server. For information on installing the database, see the documentation at:
http://www-3.ibm.com/software/webservers/appserv/doc/v40/ae/infocenter/was/nav_solaris.html
- Install one of the following Web Servers:
- iPlanet Web Server 4.1 SP8
- Apache 1.3.26
- IBM HTTP Server 1.3.19 (bundled with WebSphere)
- Install WebSphere Application Server. See installation details at:
http://www-3.ibm.com/software/webservers/appserv/doc/v40/ae/infocenter/was/nav_solaris.html
- Install Fixpacks for WebSphere and IBM HTTP Server.
Version upgrade to 4.0.4
- Install Fixpack4 for WebSphere Application Server, to upgrade the version from 4.0.1 to 4.0.4. Download Fixpack4 from:
ftp://ftp.software.ibm.com/software/websphere/appserv/support/fixpacks/was40/fixpack4/Sun/
- When you apply the Fixpack, choose to apply the changes to all the components (IBM HTTP Server, bundled JDK, and WebSphere Application Server.)
- Test your installation and configuration of WebSphere Application Server. Follow the instructions at:
http://www-3.ibm.com/software/webservers/appserv/doc/v40/ae/infocenter/was/022soltestgen.html
- Install the appropriate Identity Server Policy Agent for the Web Server.
If only fine grained authorization is performed based on the deployment descriptors, then install the Identity Server Policy agent with the Single Sign On (SSO) Only option. With this option, the Web Server Policy Agent performs SSO only, and doesn't perform authorization based on URL policies defined in the Identity Server. For more details, refer the chapter "Read This First".
- Add Unprotected resources to the Not-Enforced List of the Web Agent.
The Web Agent intercepts the request to the web server. It checks for the presence of valid a SSO Token in the request. If a valid SSOToken is not found in the request, the user is redirected to the Identity Server for authentication. Requests to the resources deployed on WebSphere go through the Web Server and are intercepted by the Web Agent. Some applications deployed on the WebSphere may not be protected and may be accessed by unauthenticated users. For such applications, the entries need to be created in the Not-Enforced List property of the Web agent configuration file. With this configuration, the web agent no longer forces authentication to the unprotected resources specified and access to these resources is allowed unconditionally. See the chapter "Read This First" for more details.
- Enable Cookie Reset Feature in the Web Agent
The LTPA authentication framework in WebSphere sets LtpaToken cookie in the browser session on successful authentication. This identifies the authenticated user to the WebSphere Application Server for the requests in that session. When Web Agent is installed, the authentication is managed by Identity Server. When a user session ends in Identity Server, the LtpaToken cookie in the request no longer identifies the authenticated user. Due to the continued presence of LtpaToken, WebSphere continues the execution in the context of the authenticated user represented by the LtpaToken. To clear the information in the LtpaToken cookie, enable the cookie reset feature. This can be done from the web agent by setting the following configuration parameters in the Web Agent's configuration file AMAgent.properties as shown below.
Enable Cookie Reset if it is not already enabled.
com.sun.am.policy.agents.cookie_reset_enabled=true
Append LtpaToken to the list of cookies to be reset
com.sun.am.policy.agents.cookie_reset_list=LtpaToken
- Create URL Policies for the resources in Identity Server.
This step is required only if you choose to perform coarse grained access-control based on the Allow/Deny URL policies in the Identity Server. If you have chosen to use the Sun ONE Identity Server Policy agent to perform only the single sign on in step 4 then this step can be skipped.
Create Allow Policies for resources, for which you don't want to perform any coarse grained access control, but only fine grained access control through security constraints and EJB method permissions in deployment descriptor. You can also create the Deny policies to Deny certain resources to subjects based on conditions. By default if no policy is created, access to all resources is blocked by the Web Agent.
For example, an Allow policy for URL http://webserverhost.domain:port/* assigned to subject organization will cause the Web Agent to allow all the requests to pass through.
- Test the deployment of the application that you intend to protect.
Before installing the WebSphere Agent, it is important that you deploy and test the application that must be protected for simple functionality. Once it is established that the application can be deployed successfully, you are ready to install the Agent.
- Disable Security for the WebSphere Application Server, if already enabled.
This can be done from the WebSphere Administrative Console as follows.
- Start the WebSphere Application Server and then start the WebSphere Administrative Console.
# WAS_root_dir/bin/adminclient.sh
- Choose Console > Security Center.
- In the Security Center Window, click on General tab.
- Ensure that the check box Enable Security is not selected.
- Click Apply.
- Click OK.
- Restart the WebSphere Administration Server.
Launching the Installation Program
The binaries for Identity Server Policy Agent for WebSphere 4.0.4 AE for Solaris platform are provided as a tar-gzip archive. Copy this archive to the machine where WebSphere Application Server is installed. Perform the following steps to launch the installation program.
- Login as root.
- Unzip the binary archive using the following command:
# /bin/gzcat IBM_WebSphere_4.0.4_agent_2.0_Solaris2.8.tar.gz | /bin/tar xvf -
- Set your JAVA_HOME environment variable to the JDK supplied with WebSphere Server 4.0.4 server. This JDK is typically located at:
WAS_root_dir/java
The installation program provides two types of interfaces: a graphical user interface (GUI) and a command-line interface. In most cases, the GUI installation program can be used for installing the Agent. However, in cases when you are installing the Agent over a telnet session on a remote server, and do not have windowing capabilities, 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, if you have set the JAVA_HOME variable incorrectly, 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 WebSphere JDK installation directory for launching the installation program. This typically is WAS_root_dir/java. 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.
Installing the Agent Using GUI
The installation program begins with a Welcome screen.
- Click Next to step through the installation screens, and answer the required questions.
- 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. The default installation directory is /opt.
Figure 8-2 Select Installation Directory screen
- Click Next and in the Sun ONE Identity Server Information screen, provide the following information about the Identity Server.
Figure 8-3 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 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 Identity Server Services. The default URI is amserver.
amAdmin Password: Enter the password for the amAdmin user.
Re-enter Password: Re-enter the password for the amAdmin user for confirmation.
amldapuser Password: Enter the password for the amldapuser. This is the Bind DN user for LDAP/Membership/Policy service. This user will have read and search access to Directory Server entries.
Re-enter Password: Re-enter the password for the amldapuser for confirmation.
- Click Next and in the Directory Server Information screen, provide the following information about the Directory Server that is associated with Identity Server services.
Figure 8-4 Directory Information Screen
Directory Host: Enter the fully qualified host name of the system where the Directory Server is installed. For example, nila.eng.siroe.com.
Directory Port: Enter the port number used by the Directory Server. The default port is 389.
SSL Enabled: Select this, if the Directory Server instance used by the Identity Server is configured for LDAPS.
Root Suffix: Enter the root suffix to be used with this Directory Server.
Installation Organization: Enter the name of the installation organization as specified when installing the Sun ONE Identity Server.
- In the WebSphere Application Server Details screen, provide the following information about the WebSphere Server on which the Agent is installed.
Figure 8-5 WebSphere Application Server Details Screen
WebSphere Application Server Root Directory: Enter the full path to the location of the WebSphere root directory. For example, agent_install_dir/WebSphere/AppServer
WebSphere Application Server JAVA_HOME Directory: Enter the full path to the JDK installation directory used by the WebSphere Server. The WebSphere JAVA_HOME directory refers to the JDK installation that is used by the WebSphere Server. By default, this is WAS_root_dir/java
Name of the Agent Realm: Enter the name of the Realm that will be configured as the default realm to be used by the WebSphere Application Server.
- Click Next and in the Agent Configuration Details screen, provide the key configuration information necessary for the Agent to function correctly.
Figure 8-6 Agent Configuration Details Screen
Agent Audit Log File: Enter the complete path to the log file to be used by the agent to record Audit messages. The agent logs key events such as user authentication in this log file.
Enable Audit log file rotation: Select this to enable rotation of Audit Log files. Selecting this ensures that after the log file reaches a specified size, the agent creates a new file for logging audit messages. The audit log file rotation size is controlled by the property Audit Log File Rotation Size in the AMAgent.properties file.
UnAuthenticated User: Enter the User id of the unauthenticated user. This user will be used when protected resources are included in the Not-Enforced List. The Agent Interceptor returns this as the user to be used for accessing the protected resources included in the Not Enforced List.
Enable Console Integration: Select this option to enable console level integration of Sun ONE Identity Server with WebSphere Administrative Console.
Enable Not-Enforced List Cache: Select this option 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.
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 filename of an existing file which can be used by the Agent. However, in either case, it is required that the specified file has write permissions for the WebSphere Server process because the Agent executes in the same process as the WebSphere Server. Providing an incorrect value for this will result in the malfunction of the Agent which can render the WebSphere Server unusable.
Console Integration implies that the information regarding the names of all Users, Roles, and the Users who are assigned to these Roles in Identity Server will be visible on the WebSphere Server Administrative Console. Therefore, this feature must be enabled with caution since the User or Role information will then be accessible to administrators who access the WebSphere Server Console.
The Agent Interceptor is bypassed for access to unprotected resources. The unprotected resources are the resources which are not protected by security constraints in the deployment descriptor. Since the Not-Enforced List is processed by the Agent Interceptor, this will not impact the unprotected resources. Therefore, it is not necessary to add any unprotected resources to the Not-Enforced List. The resources in the Not-Enforced List will always be accessed as the unauthenticated user—for example, anonymous, independent of the identity of the logged in user.
The Application Server authorization enforcement takes precedence over the Not-Enforced List configuration specified in AMAgentConfiguration.properties. The access to the protected resource specified in Not-Enforced List will be successful, only if the unauthenticated user, has the appropriate roles to access the application based on the application's deployment descriptors.
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. 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 the Cache and Cache Expiration time are not set up appropriately. In cases 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 system performance. 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 the 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.
- 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.
- In the Ready to Install screen, click Install Now 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 on Details for a detailed summary of the configuration information that was processed during installation. Click on Exit to end the program.
- Start WebSphere Application Server using the following command:
# WAS_root_dir/bin/startupServer.sh
After the agent is installed, the next step is to configure the WebSphere Server as explained in the later sections.
Installing the Agent Using Command-Line
You must have root permissions when you run the agent installation program.
- Unzip the Solaris tar file using the following command:
# gzcat IBM_WebSphere_4.0.4_agent_2.0_Solaris2.8.tar.gz | tar -xvf -
- Run the setup program. You'll find the program in the directory where you untarred the binaries. At the command-line, enter the following:
# ./setup -nodisplay
- When prompted to enter path to pick up java, type the full path where the WebSphere JDK is located. This is typically WAS_root_dir/java
- 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.
- At the following prompt, specify an installation directory for the agent.
The Sun(TM) ONE Identity Server Policy Agent components will be installed inthe following directory, which is referred to as the "Installation Directory". To use this directory, press only the Enter key. To use a different directory, type in the full path of the directory to use followed by pressing the Enter key.
Install Sun(TM) ONE Identity Server Policy Agent in this directory [/opt]{"<" goes back, "!" exits}:
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.
- At the following prompts, provide details about your Identity Server installation.
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}:
amldapuser Password [] {"<" goes back, "!" exits}:
Re-enter Password [] {"<" goes back, "!" exits}:
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 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 Identity Server Services. The default URI is amserver.
amAdmin Password: Enter the password for the amAdmin user.
Re-enter Password: Re-enter the password for the amAdmin user for confirmation.
amldapuser Password: Enter the password for the amldapuser. This is the Bind DN user for LDAP/Membership/Policy service. This user will have read and search access to Directory Server entries.
Re-enter Password: Re-enter the password for the amldapuser for confirmation.
- At the following prompts, provide information about the Directory Server used by the Identity Server.
Sun(TM) ONE Identity Server Directory Details
Directory Host [nila.eng.Siroe.COM] {"<" goes back, "!" exits}:
Directory Port [389] {"<" goes back, "!" exits}:
SSL Enabled [false] {"<" goes back, "!" exits}:
Root Suffix [dc=siroe,dc=com] {"<" goes back, "!" exits}:
Installation Organization [dc=siroe,dc=com] {"<" goes back, "!" exits}:
Directory Host: Enter the fully qualified host name of the system where the Directory Server is installed. For example, nila.eng.siroe.com.
Directory Port: Enter the port number used by the Directory Server. The default port is 389.
SSL Enabled: Select this, if the Directory Server instance used by the Identity Server is configured for LDAPS.
Root Suffix: Enter the root suffix to be used with this Directory Server.
Installation Organization: Enter the name of the installation organization as specified when installing the Sun ONE Identity Server.
- At the following prompts, enter the details of WebSphere Application Server.
Enter the details of WebSphere Application Server installation on which this Agent will be installed.
WebSphere Application Server Root Directory. [/opt/WebSphere/AppServer] {"<"goes back, "!" exits}
WebSphere Application Server JAVA_HOME directory
[/opt/WebSphere/AppServer/java] {"<" goes back, "!" exits}
Name of the Agent Realm. [AgentRealm] {"<" goes back, "!" exits}
WebSphere Application Server Root Directory: Enter the full path to the location of the WebSphere root directory. For example, agent_install_dir/WebSphere/AppServer
WebSphere Application Server JAVA_HOME Directory: Enter the full path to the JDK installation directory used by the WebSphere Server. The WebSphere JAVA_HOME directory refers to the JDK installation that is used by the WebSphere Server. By default, this is WAS_root_dir/java
Name of the Agent Realm: Enter the name of the Realm that will be configured as the default realm to be used by the WebSphere Application Server.
- Enter the configuration details for the installation of Sun ONE Identity Server Agent for WebSphere Application Server.
Agent Audit Log File [/var/opt/SUNWam/audit/agent.log] {"<" goes back, "!" exits}
Enable Audit log file Rotation [false] {"<" goes back, "!" exits}
Enable Console Integration [false] {"<" goes back, "!" exits}
Enable Not-Enforced List Cache [false] {"<" goes back, "!" exits}
UnAuthenticated User [anonymous] {"<" goes back, "!" exits}
Agent Audit Log File: Enter the complete path to the log file to be used by the agent to record Audit messages. The agent logs key events such as user authentication in this log file.
Enable Audit log file rotation: Select this to enable rotation of Audit Log files. Selecting this ensures that after the log file reaches a specified size, the agent creates a new file for logging audit messages. The audit log file rotation size is controlled by the property Audit Log File Rotation Size in the AMAgent.properties file.
UnAuthenticated User: Enter the User id of the unauthenticated user. This user will be used when protected resources are included in the Not-Enforced List. The Agent Interceptor returns this as the user to be used for accessing the protected resources included in the Not Enforced List.
Enable Console Integration: Select this to enable console level integration of Sun ONE Identity Server with WebSphere Administrative Console.
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.
For more details on each of these items, see "Agent Configuration Details"."
- 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
- Type 1 to start the installation. At then end of 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.
- Start WebSphere Application Server using the following command:
# WAS_root_dir/bin/startupServer.sh
Configuring WebSphere Application Server
After the Sun ONE Identity Server Policy Agent for WebSphere has been installed on your system, Web Trust Association must be enabled for the Agent Interceptor to work appropriately. This can be done from the WebSphere Administrative Console.
- Start the WebSphere Administrative console using the following command:
# WAS_root_dir/bin/adminclient.sh
- In the Administrative Console, choose Console > Security Center.
- In the Security Center window, click on Authentication Tab.
- Select the check box Enable Web trust association.
Figure 8-7 Enabling Web Trust Association
- Click Apply. A message "Changes will take effect only after Administration Server is restarted" will be displayed.
- In the Security Center window, click on Apply and then OK to apply the changes made.
- Stop all the Application Server instances and also the Administration Server.
- Restart Administration Server and Application Server instances for changes to take effect.
Application Configuration
The Agent Realm (Custom Registry) component of Identity Server Policy Agent for WebSphere provides runtime mapping of various principals in Identity Server.
Abstract security role names are used by the hosted application in order to determine if the currently authenticated user is authorized to access a particular resource, or is otherwise a member of a given role. This runtime evaluation can occur only if the user is authenticated as an Identity Server principal using 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.
Creating Role-to-Principal Mappings
Once the application has been secured and the Web Trust Association has been enabled, the Trust Association Interceptor intercepts the requests for the application, validates SSOToken, and authenticates to the Security Service of the Application Server, 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 WebSphere Server specific deployment descriptors
The WebSphere Server specific deployment descriptors may be edited to create the role to principal mappings. These descriptors are in ibm-application-bnd.xmi file. Refer to the WebSphere Server reference documentation for details on how these descriptors may be edited to create the role to principal mappings. Alternatively, you can refer the information provided in Appendix C for sample descriptors, to create such mappings.
Using the WebSphere Server Administrative Console
The WebSphere Server Administrative console allows you to create the role to principal mappings by editing the deployed application's deployment descriptors. In order to use this facility, the application must be deployed and the WebSphere Server must be up and running at that time. Refer to the WebSphere Server documentation on how to use the Administrative Console to create such mappings for deployed applications.
Application-Specific Agent Configuration
Oftentimes, the deployed applications are partitioned into public and protected parts, which have varying access restrictions. In most cases, the public portions of the application are accessible to unauthenticated users, whereas the protected portions of the application are accessible only to registered users. The Agent can be configured to allow this type of access by letting unauthenticated 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/wasAgent/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 unauthenticated users to access portions of the protected application, the AMAgent.properties file must include an entry for the specific application. Access to these entry points will be made as the unauthenticated user. The entry that specifies this property is called the application-specific 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 the 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 can specify none or many pattern strings and URIs that the Agent will treat as not-enforced. The user requests that match these particular patterns will be allowed to pass through without requiring a valid SSO token in the request.
Special Case: Default Web Application
A default web application on WebSphere Server is accessible without providing any context path in the request URI. For example, the following URL is that of a default web application:
http://myserver.mydomain.com/index.html
The above URL does not have an associated context path.
For such applications, the Agent provides a convenient means of identifying that an entry is specific to the default web application. This is done in two steps as follows:
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 used to specify the application not-enforced list.
com.sun.am.policy.config.filter.DefaultWebApp.notEnforcedList[0]=/index.html
com.sun.am.policy.config.filter.DefaultWebApp.notEnforcedList[1]=/about.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 as applicable to the rest of the application. However, the only difference is that 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 using the following property:
com.sun.am.policy.config.filter.global.notEnforcedList[index]= pattern
index is an integer value starting from 0 and unique for every entry.
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.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 Interceptor will not perform authentication to the Application Server, 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 unauthenticated, 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 the entry does not in any way cover a resource to which the Unauthenticated user has no access, or may try to access such a resource.
Agent Configuration
The core configuration needed by the Sun ONE Identity Server Policy Agent for WebSphere is provided in the AMAgent.properties file located in the following directory:
Agent_Install_Dir/wasAgent/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 Interceptor Configuration
- Application Interceptor Configuration
- Debug Engine Configuration
The 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 must not be changed unless absolutely necessary.
Example: com.sun.am.policy.config.org=dc=sun,dc=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 must not be changed unless absolutely necessary.
Example: com.sun.am.policy.config.rootsuffix=dc=sun,dc=com
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. This property is set during Agent installation and must 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. The default value of this property is en.
Example: com.sun.am.policy.config.audit.localeLanguageCode=en
Note For more information, refer to ISO 639 specification at http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt
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.
Example: com.sun.am.policy.config.audit.localeCountryCode=US
Note For more information, refer to the ISO 3166 specification:
http://www.chemie.fu-berlin.de/diverse/doc/ISO_3166.html
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 the Agent to record Audit messages.
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
Realm Configuration
These settings are used to configure the Agent Realm component.
The Agent caches the SSOToken for the logged in user and makes it available for the application through the AgentUser APIs. The cache behavior is controlled by the Realm Configuration properties in the AMAgent.properties file.
Realm Name
Key: com.sun.am.policy.config.realm.name
Description: Used by the Realm implementation to identify itself to the WebSphere Application Server. Any changes to this should be accompanied by the appropriate change in WebSphere Administrative Console, Security Center and property file sas.client.props.
Allow Console Integration Flag
Key: com.sun.amagent.config.websphere.allowConsoleIntegration
Description: This property specifies if the Agent Realm should allow console level integration of Identity Server with WebSphere Server.
Valid Values: true/false
Example: com.sun.amagent.config.websphere.allowConsoleIntegration=true
When set, the result of console level integration is that the WebSphere Server Administrator will be able to see the list of Identity Server principals in WebSphere Server console.
This setting enables the WebSphere Server Administrator to see the Identity Server principals in WebSphere Server console, it should be used with caution.
The default value of this setting is false and should be changed as necessary.
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 Interceptor Configuration
These settings are used to configure the Agent Interceptor component.
IsOnly Interceptor Flag
Key: com.sun.am.policy.config.filter.isOnlyInterceptor
Description: This property indicates if this is the lone interceptor configured in the system. By default, this is set to true. If additional interceptors need to be added to WebSphere, then this should be set to false and appropriate changes should be made in the file trustedServers.properties.
Valid Values: true/false. The default value is true.
If set to true, the absence of SSOToken in the request will cause the request to get denied. If set to false, the absence of SSOToken will result in control being passed on to the next interceptor that is installed.
UnAuthenticated User
Key: com.sun.am.policy.config.filter.notEnforcedList.nonAuthUser
Description: This unauthenticated user is used to access the resources specified in the Not-Enforced List. Access to the resources in the Not-Enforced List will be successful, only if the user has the required roles for accessing them.
Valid Values: Any valid user in the Identity Server.
SSO Token Name
Key: com.sun.am.policy.config.filter.ssoTokenName
Description: This property specifies the name of the cookie that represents the SSO Token.
Valid Values: A string that represents the name of SSO Token cookie issued by the 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
Not-Enforced-List Cache Enable Flag
Key: com.sun.am.policy.config.filter.notEnforcedList.cache
Description: This property specifies if the requested URIs that are evaluated as enforced or not-enforced may be cached to increase the 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 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 a cleanup operation.
Example: com.sun.am.policy.config.filter.notEnforcedList.cacheTime=60
SSO Token URL Decode Flag
Key: com.sun.am.policy.config.filter.urlDecodeSSOToken
Description: This property indicates if the SSOToken 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 the 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 an 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 Interceptor Configuration
These settings are used to configure the Agent Interceptor for a particular application.
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. All the URIs that match any of these patterns will be accessed as Unauthenticated User.
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.htmlDebug 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 generated by the Agent's Debug Engine. This property works only when a Debug Log File location is specified.
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 the Agent to record Debug messages.
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 WebSphere 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 for WebSphere Application Server 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 Interceptor 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. The AgentUser API provided by the Policy Agent can be used to access the user's SSO Token from anywhere within the application in the following simple steps:
- Create an instance of the AgentUser
- From HttpServletRequest
import com.sun.amagent.websphere.realm.AgentUser;
import com.iplanet.amagent.arch.AgentException;.....................
..............AgentUser user=null;
HttpServletRequest request = getHttpRequest();try {
user = new AgentUser(request);
}
catch (AgentException ex) {
throw new RuntimeException("Error in creating the instance of AgentUser !!!");
}
- From EJBContext
import com.sun.amagent.websphere.realm.AgentUser;
import com.iplanet.amagent.arch.AgentException;
.....................
..............
AgentUser user=null;EJBContext context = getEJBContext( )
try {
user = new AgentUser(context);
}
catch (AgentException ex) {
throw new RuntimeException("Error in creating the instance of AgentUser !!!");
}
- Use the AgentUser API to retrieve the SSO Token associated with the current 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 "Realm Configuration."
SSL Configuration
The SSL Configuration involves the following tasks:
- Configuring SSL for the Web Server
Configuring SSL for the Web server depends on the Web server used. Refer to the appropriate Web Server documentation.
- Configuring SSL for WebSphere plug-ins for Web servers.
See the WebSphere documentation at: http://www-3.ibm.com/software/webservers/appserv/doc/v40/ae/infocenter/was/06061801a07.html#pi
- Configuring SSL for WebSphere Application Server.
See the documentation at http://www-3.ibm.com/software/webservers/appserv/doc/v40/ae/infocenter/was/06061801a07.html#was
Configuration Changes in AmConfig.properties
This is the additional step to be performed when the Identity Server is running in SSL Mode. The AmConfig.properties file is located at Agent_Install_Dir/SUNWam/wasAgent/amSDK/lib.
com.iplanet.am.server.protocol=https
com.iplanet.am.console.protocol=https
com.iplanet.am.naming.url=https://<IS_HOST>:<IS_PORT>/amserver/nami ngservice
com.iplanet.am.notification.url=https://<IS_HOST>:<IS_PORT>/amserve r/notificationservice
Additionally make the following changes if the Directory Server is configured for LDAPS.
com.iplanet.am.directory.ssl.enabled=true
com.iplanet.am.directory.port=<LDAPS Port>
Configuration Changes in serverconfig.xml
If the Directory Server is configured for LDAPS update the port and type information in serverconfig.xml. This file is located at Agent_Install_Dir/SUNWam/wasAgent/amSDK/config/ums.
<iPlanetDataAccessLayer>
<ServerGroup name="default" minConnPool="1" maxConnPool="10">
<Server name="Server1" host="sleeper.india.sun.com" port="<LDAPS Port>" type="SSL" />
......
......
.....
.....
</ServerGroup>
</iPlanetDataAccessLayer>
Importing the root CA cert into Application Server JVM Keystore
Export the root CA certificate for the CA (who signed the certificate used by the Identity Server) into a Base64-encoded ASCII data file /tmp/cacert.txt
Import this cert into AppServer JVM Keystore as follows:
# WAS_root_dir/java/bin/keytool -import -trustcacerts -alias cmscacert -keystore ../jre/lib/security/cacerts -file /tmp/cacert.txt
Enter keystore password: changeit
Trust this certificate? [no]: yes
keystore: all cert installed
Verify that Cert is added
# WAS_root_dir/java/bin/keytool -list -keystore WAS_root_dir/java/jre/lib/security/cacerts
Enter keystore password: changeit
Uninstalling the Agent
When you install the Identity Server Policy Agent for WebSphere 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.
Launching the Uninstallation Program
The uninstallation program for Solaris platform may be launched by executing the generated uninstall_wasagent script located in the installation directory. The following steps provide details on how to achieve this:
- Login as root.
- Go to Agent_Install_Dir.
- Set your JAVA_HOME environment variable to the JDK supplied with WebSphere Server 4.0.4:
WAS_root_dir/java
The uninstallation program provides two types of interfaces, a graphical user interface (GUI) and a command-line interface. In most cases, the GUI installation program can be used for 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_wasagent -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_wasagent
The uninstallation program requires that you setup your JAVA_HOME variable correctly as pointed out in the Step 3. However, in case you have set the JAVA_HOME variable incorrectly, the uninstall script will prompt you for supplying the correct JAVA_HOME value.
Enter JAVA_HOME location (Enter "." to abort):
- Type the full path to the JDK installation directory for launching the installation program. Otherwise, enter a period (.) to abort the installation
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 installation program by typing in the exact value at the above prompt. Otherwise, enter a period (.) to abort the installation at this time.
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
- Remove the Realm Administrator from the AdminRole.
Uninstalling the Agent Using Command Line
- From the directory where the agent is installed, enter the following command at the command line:
# ./uninstall_wasagent -nodisplay
- When prompted, Please enter path to pick up java: Type the full path where WebSphere JDK is located.
- At the following prompt, type 1 to begin uninstallation.
Ready to Uninstall
1. Uninstall Now
2. Start Over
3. Exit Uninstallation
- At the following prompt, to see log information on the agent, enter 1. To exit the Uninstallation program, enter 2.
Product Result More Info
1. Sun_TM_ONE Identity Server Policy Agent Details Available
2. Done
Troubleshooting Information
Installation/Uninstallation Problems
Server Startup Error due to Agent Realm (Custom Registry) initialization failure, after the Agent installation
The realm initialization fails when the Realm is unable to authenticate to the Identity Server. This may be due to one of the following reasons.
Incorrect values were given for amldapuser password. You can try giving the correct values in the Administrative Console Security Center. Apply the changes and restart WebSphere.
Installation Program fails to add System Property for Application Server Instances, for the Identity Server SDK config directory (com.iplanet.coreservices.config). You can add this property com.iplanet.coreservices.config=Agent_Install_Dir/SUNWam/wasAgent/amSDK/config/ums to each Application Server instance, under JVM Settings in the Administrative Console. Again save the changes and restart WebSphere.
If the Identity Server is running in SSL Mode, then verify the following.
The certificate for the CA that issued the Certificate for the Identity Server, is imported into the KeyStore of the JVM used by the WebSphere. See "SSL Configuration."
The System property java.protocol.handler.pkgs was added by the Agent installation program to each Application Server instances. This can be found under JVM Settings for each Application server instance, in the WebSphere Administrative console. This property must be set to the value: com.ibm.net.ssl.internal.www.protocol
Verify the Identity Server configuration parameters in the AMConfig.properties file.
Access to the resource fails even after Authenticating to the Identity Server.
If you are accessing a protected resource from an unprotected resource, make sure that you have security constraint (dummy) defined for the unprotected resource with the role mapped to any principal other than the special subject EveryOne.
Make sure that the Web trust association is enabled, and WebSphere was restarted after enabling Web Trust Association.
Make sure that the following lines are present in the trusted WAS_root_dir/properties/trustedservers.properties
com.ibm.websphere.security.trustassociation.enabled=true
com.ibm.websphere.security.trustassociation.types=amagent
com.ibm.websphere.security.trustassociation.amagent.interceptor=com.sun.amagent.websphere.interceptor.AgentInterceptor
com.ibm.websphere.security.trustassociation.amagent.config=AMAgent
Fixing the Problems Manually
During the installation, the Agent installation program performs modifications for certain existing files on your system. These modifications are undone by the uninstallation program. The backups of these files are created before the modifications are made. In case you encounter any failures during the install it is possible to bring the system back to its original state manually by restoring the backed up files. These backed up files are copied under Agent_Install_Dir/SUNWam/wasAgent/backup directory. This directory is deleted if the uninstallation was completed successfully.
The following files are modified during installation and the modifications are undone during the uninstallation of the Agent:
Admin Server Configuration file:
WAS_root_dir/bin/admin.config
Trusted Servers file:
WAS_root_dir/properties/trustedservers.properties
Client Configuration file:
WAS_root_dir/properties/sas.client.props
Agent uninstallation also creates a backup of the version of the above files, just before the uninstallation under the directory WAS_root_dir/amAgentBackup. In case of any errors during uninstallation these can be used to manually reapply those changes to the current copy of these files.