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



Chapter 3   Policy Agent for IBM WebSphere 4.0.3 AE


This chapter provides a brief overview of Sun ONE Identity Server Policy Agent for IBM WebSphere Application Server 4.0.3 and describes how to install and configure the Policy Agent for WebSphere 4.0.3 running on Solaris 8 platform.

Topics include:



Overview

The Identity Server Policy Agent for WebSphere Application Server 4.0.3 is designed to enforce 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.3.

The J2EE role-based authorization is performed by the WebSphere application server. The WebSphere must trust the RPSS before accepting the authentication credentials. For the 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 3-1    Identity Server Policy Agent for WebSphere 4.0.3 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.

  • Coarse Grained and Fine Grained access-control

    The resources deployed on WebSphere are protected by a combination of Web Agent and 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 in the Identity Server. Access to the EJBs or servlets is then restricted only to these users. This is fine grained access-control.

  • 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 Sun ONE Identity Server Programmer's Guide.



Limitations

  • The Policy Agent for WebSphere Application Server 4.0.3 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.

  • The resources deployed on the WebSphere are protected by a combination of Web agent and J2EE Agent. The agent functionality does not work properly (access to protected resources always get declined) when the resources are accessed directly using the web container's internal HTTP transports, thus bypassing the web server.

  • WebSphere Server does not start properly when the Directory Server used by the Identity Server is configured for LDAPS.

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



Software Requirements

  • Sun ONE Identity Server 5.1

  • Web Server with an appropriate Identity Server Policy Agent installed

    • Apache Server 1.3.26

    • IBM HTTP Server 1.3.19

    • iPlanet Web Server, Enterprise Edition 4.1 SP8



Installing the Agent

The Identity Server Policy Agent for WebSphere 4.0.3 AE is supported on Solaris 8 platform.


Pre-Installation Tasks

The following tasks must be completed before the Identity Server Policy Agent for WebSphere can be installed:

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

  2. Install one of the following Web Servers:

    • iPlanet Web Server

    • Apache

    • IBM HTTP Server (Bundled with WebSphere)

  3. Install WebSphere Application Server. See installation details at: http://www-3.ibm.com/software/webservers/appserv/doc/v40/ae/infocenter/was/nav_solaris.html

  4. Install Fixpacks for WebSphere and IBM HTTP Server.

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

  6. Install the appropriate Identity Server Policy Agent for the Web Server. Refer Sun ONE Identity Server Policy Agent Pack Guide.


    Note It is recommended to use IBM HTTP Server Agent, as you may encounter session synchronization problems with Apache and iPlanet Web Server Policy Agent. For more details see Step 8.


  7. Add the 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 Sun ONE Identity Server Policy Agent Pack Guide.

  8. 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.iplanet.am.policy.agents.cookie.reset.enable=true

    • Append LtpaToken to the list of cookies to be reset com.iplanet.am.policy.agents.cookie.reset.list=LtpaToken


      Note This feature is available only in IBM HTTP Server Agent.


    If Apache or iPlanet Web Server Agent is used, you may encounter session synchronization problem. To overcome this problem, follow the steps given below:

    1. Start the WebSphere Administrative console using the following command:

      # WAS_root_dir/bin/adminclient.sh

    2. In the Administrative Console interface, choose Console > Security Center.

    3. Click on Authentication tab.

    4. Uncheck the check box "Enable Single Sign-On" and click OK.

    5. Restart the WebSphere Server for changes to take effect.

  9. Create URL Policies for the resources in Identity Server.

    To perform coarse grained access-control, define the Allow/Deny URL policies for them in the Identity Server. 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. Assign these policies to the organization. For example, an Allow policy for URL http://webserverhost.domain:port/* will cause the Web Agent to allow all the requests to pass through. By default if no policy is created, access to all resources is blocked by the Web Agent.

  10. 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 then the application can be deployed successfully, you are ready to install the Agent.

  11. Disable Security for the WebSphere Application Server, if already enabled.

    This can be done from the WebSphere Administrative Console as follows.

    1. Start the WebSphere Administrative Console.

      # WAS_root_dir/bin/adminclient.sh

    2. Choose Console > Security Center.

    3. In the Security Center Window, click on General tab.

    4. Ensure that the check box Enable Security is not selected.

    5. Click Apply.

    6. Click OK.

    Restart the WebSphere Administration Server using the following command:

    # WAS_root_dir/bin/startupServers.sh


    Note The Agent Installer updates the Security Configuration, and installs the Agent Realm as the User Registry. If the WebSphere is configured to use the OS realm, LDAP realm, or any other custom registry, the WebSphere will not be able to authenticate to the current realm, subsequently the Agent Realm installation and Security Configuration will fail during the agent installation.



Launching the Installation Program

The binaries for Identity Server Policy Agent for WebSphere 4.0.3 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.

  1. Login as root.

  2. Unzip the binary archive using the following command:

    # /bin/gzcat WebSphere_4.0.3_agent_1.0_Solaris2.8.tar.gz | /bin/tar xvf -

  3. Set your JAVA_HOME environment variable to the JDK supplied with WebSphere Server 4.0.3 server. This JDK is 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.

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

    # ./setup

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

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

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

  3. In the Select an Agent screen, select the component you wish to install by selecting the check box against the component name. The only component available for installation is the Identity Server Policy Agent for WebSphere Server 4.0.3, which is selected by default.

Figure 3-2    Component Selection Screen


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


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

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

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

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

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

amAdmin Password: Enter the password for the amAdmin user.

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


Note The password supplied during installation is recorded by the Agent in a secure manner. However, if in the future you change this password in Identity Server, you will have to update the password in the Agent as well. This can be done by using the agentadmin tool provided with the Agent. Once the Agent has been installed on the system, the agentadmin tool can be invoked from the location:

Agent_Install_Dir/SUNWam/wasAgent/bin/agentadmin

To change the password, invoke this tool as follows:

#./agentadmin -password oldpassword newpassword

If the user amAdmin is used as the Realm Administrator (Security Server Password) perform the following steps:

  1. Change the Security Server Password through WebSphere Administrative Console.

  2. Change the Security Server Password by setting the property com.ibm.CORBA.loginPassword=newpassword in sas.client.props file. For more information refer WebSphere documentation.

  3. Restart WebSphere for changes to take effect.


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

Figure 3-4    Directory Information Screen

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

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

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

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

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

Figure 3-5    WebSphere Application Server Details Screen

WebSphere Application Server Root Directory: Enter the full path to the location of the WebSphere root directory.

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.

Realm Administrator: Enter the userid of the Administrative user for the installed organization. The WebSphere Application Server requires administrative user credentials (userid and password) for configuring the Realm/User Registry. This is typically the user who does the top level user management functions such as Creating and Deleting new roles and users. This user is used to check the validity of the realm by authenticating to the realm during the realm installation. This user is also used to call the Realm methods to get the list of all users and roles in the installed organization.

Realm Admin Password: Enter the password. This is used to perform initial authentication to the realm during the realm installation. This is also used to authenticate to the realm while getting the list of all users and roles in the installed organization.


Note It is very important that the Realm Administrator user is a valid user, and authentication credentials are accurate. Once the Realm is configured and security is enabled, this user is used to authenticate to the realm. If the user doesn't exist in Identity Server, or if the password is incorrect, then the realm initialization will fail, and may render the Application Server unusable.

Before entering these values in the installer, make sure you can login to the Identity Server console with this user and corresponding Password.

If you want to change the Realm Administrator (Security Server Password) perform the following steps:

  1. Change the Security Server Password through WebSphere Administrative Console.

  2. Change the Security Server Password by setting the property com.ibm.CORBA.loginPassword=newpassword in sas.client.props file. For more information refer WebSphere documentation.

  3. Restart WebSphere for changes to take effect.


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

Figure 3-6    Agent Configuration Details Screen

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

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

Unauthenticated User Name: 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.


Important Tips

  • The Audit Log file is a necessary requirement for the Agent. You may provide the name of a non-existing file on the system to be used as the Audit file. In which case, the Agent creates this file and the necessary directories in its path on first use. Alternatively, you can provide the 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.

Figure 3-7    Summary of All the Selections Screen

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

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


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


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


    Note It is recommended that you check the install log file by clicking the Details button to identify errors. If you find errors, uninstall the Agent and try again after fixing the root cause of failure during this installation.


  4. Restart WebSphere Application Server using the following command:

    # WAS_root_dir/bin/startupServers.sh

After the agent is installed, the next step is to configure the WebSphere Server as explained in the following sections.


Installing the Agent Using Command-Line

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

  1. Unzip the Solaris tar file using the following command:

    # gzcat WebSphere_4.0.3_agent_1.0_Solaris2.8.tar.gz | tar -xvf -

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

  3. When prompted, Please enter path to pick up java: Type the full path where the WebSphere JDK is located.

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

  5. The following text is displayed:
    Specified directory is valid
    1. Accept
    2. Choose another Directory
    Enter the number corresponding to your choice:

    Type 1 to accept the specified directory. Otherwise, type 2 to choose another directory.

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

    • Sun(TM) ONE Identity Server Host

    • Sun(TM) ONE Identity Server Port

    • Sun(TM) ONE Identity Server Protocol

    • Sun(TM) ONE Identity Server Deployment URI

    • amAdmin Password

    • Re-enter Password

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

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

    • Directory Host

    • Directory Port

    • Root Suffix

    • Installation Organization

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

  8. Provide the following information about the WebSphere Application Server:

    • WebSphere Application Server Root Directory.

    • WebSphere Application Server JAVA_HOME directory

    • Name of the Agent Realm

    • Realm Administrator

    • Realm Admin Password

    • Re-enter Password

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

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

    • Agent Audit Log File

    • Enable Audit log file Rotation

    • Unauthenticated User

    • Enable Console Integration

    • Enable Not-Enforced List Cache

    • Number of Entries in Cache

    • Cache Expiration Time in Seconds

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

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

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

  12. Restart WebSphere Application Server using the following command:

    # WAS_root_dir/bin/startupServers.sh



WebSphere Application Server Configuration

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.

  1. Start the WebSphere Administrative console using the following command:

    # WAS_root_dir/bin/adminclient.sh

  2. In the Administrative Console, choose Console > Security Center.

  3. In the Security Center window, click on Authentication Tab.

  4. Select the check box Enable Web trust association.

Figure 3-8    Enabling Web Trust Association

  1. Click Apply. A message "Changes will take effect only after Administration Server is restarted" will be displayed.

  2. Click the Administrative Role tab and select AdminRole. Click Select.

Figure 3-9    Modifying Admin Role in Security Center

  1. In the Select Users/Groups - AdminRole window, add the Realm Administrator User that was specified during installation for AdminRole. Click OK.

Figure 3-10    Adding the Realm Administrator to the Admin Role

  1. In the Security Center window, click on Apply and then OK to apply the changes made.

  2. Stop all the Application Server instances and also the Administration Server.

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


Note
  • The properties specified in the AMAgent.properties file are required for the Agent to function properly. Invalid values specified in this file can lead to malfunction of the Agent, application becoming inaccessible, or the entire system becomes unusable. It is recommended that you use extreme caution when modifying the values in this file. Always create backups before such modifications to ensure that you can back-out your changes to restore the system to its original state.

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



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.iplanet.amagent.config.filter.AppName.notEnforcedList[index]=patter n

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.iplanet.amagent.config.filter.SomeApp.notEnforcedList[0]=/SomeApp/public/*

com.iplanet.amagent.config.filter.SomeApp.notEnforcedList[1]=/SomeApp/images/*

pattern: This is a pattern string that will be matched with the incoming request to evaluate if the request should be allowed to pass without enforcing authentication or not. The pattern string could be a specific URI, for example /SomeApp/public/RegistrationServlet, or could be a generic pattern using the wild-card character `*' that can be used for denoting 0 or more characters in the request URI, for example /SomeApp/public/* will match with any URI that begins with /SomeApp/public/.

Using this property, you 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:

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

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

  2. This name is used to specify the application not-enforced list.

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

    com.iplanet.amagent.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.iplanet.amagent.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.


Note Before proceeding, you must note that this file and the information within the file are critical for the operation of the Agent. It is strongly recommended that you always create a backup of this file before modifying it. Also, it is strongly recommended that you do not modify this file unless it is absolutely necessary. Any invalid data entries present in this file can lead to the malfunction of the Agent, malfunction of the deployed applications, and could render the entire system unusable.


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

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.iplanet.amagent.config.org

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

Valid Values: 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.iplanet.amagent.config.org=sun.com


Root Suffix

Key: com.iplanet.amagent.config.rootsuffix

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

Valid Values: 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.iplanet.amagent.config.rootsuffix=o=isp


People Container Level

Key: com.iplanet.amagent.config.realm.peopleContainerLevel

Description: This property specifies the people container level to be used when searching for principals in Sun ONE Identity Server.

Valid Values: Non-zero unsigned integer representing the People Container Level in Identity Server, which may be used when searching for principals. This property is set during Agent installation and must not be changed unless absolutely necessary.

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


Audit Configuration

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


Language Code

Key: com.iplanet.amagent.config.audit.localeLanguageCode

Description: This property specifies the Locale for Audit log messages.

Valid Values: The localeLanguageCode must be a valid ISO Language Code. The default value of this property is en.

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


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



Country Code

Key: com.iplanet.amagent.config.audit.localeCountryCode

Description: This property specifies the Locale for Audit log messages.

Valid Values: The localeCountryCode must be a valid ISO Country Code. The default value of this property is US.

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


Note For more information, refer ISO 3166 specification:

http://www.chemie.fu-berlin.de/diverse/doc/ISO_3166.html



Audit Log File

Key: com.iplanet.amagent.config.audit.logfile.name

Description: This property specifies the Audit log file to be used for recording Audit messages.

Valid Values: String representing the complete path name of the file to be used by the Agent to record Audit messages.

Example: com.iplanet.amagent.config.audit.logfile.name=/audit/agent.log


Note
  • Ensure that the WebSphere Server process has sufficient permissions to write to this file.

  • Specifying an invalid value specified for this property may result in the failure of the system to start up correctly.



Audit Log File Rotation Flag

Key: com.iplanet.amagent.config.audit.logfile.rotate

Description: This property specifies if the Audit log file should be rotated by the Agent.

Valid Values: true/false. The default value of this property is false and should be changed as necessary.

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


Audit Log File Rotation Size

Key: com.iplanet.amagent.config.audit.logfile.rotate.size

Description: This property specifies the approximate size of the Audit log file in bytes, which should be used to evaluate when the log file needs to be rotated.

Valid Values: Non-zero unsigned integer indicating the size in bytes to be used to evaluate when the log file needs to be rotated. The default value of this property is 52428800 bytes (~ 50 MB) and should be changed as required.

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


Realm Configuration

These settings are used to configure the Agent Realm component.


Realm Name

Key: com.sun.amagent.config.websphere.realmName

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 property files sas.server.props and 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.


Global Interceptor Configuration

These settings are used to configure the Agent Filter component.


Is Alone Interceptor flag

Key: com.sun.amagent.websphere.interceptor.isAlone

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.


Default User

Key: com.sun.amagent.websphere.interceptor.defaultUser

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.iplanet.amagent.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.iplanet.amagent.config.filter.ssoTokenName=iPlanetDirectoryPro


Not-Enforced-List Cache Enable Flag

Key: com.iplanet.amagent.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.iplanet.amagent.config.filter.notEnforcedList.cache=true


Not-Enforced-List Cache Size

Key: com.iplanet.amagent.config.filter.notEnforcedList.cacheSize

Description: This property specifies the number of entries that will be kept in the cache of not-enforced URIs and enforced URIs by the Agent.

Valid Values: Non-zero unsigned integer indicating the number of enforced as not enforced request URIs to be cached during runtime.


Note
  • Values that are valid but not suited for the deployment scenario may result in degradation of system performance.

  • The value for optimal system performance will depend on the type of application deployed, the number of possible request URIs in the deployed application, the user load on the system, the expiration time set for cache entries and a host of other deployment specific factors.

  • To determine the most optimal value of this property, the application should be load tested in a controlled test environment before being deployed for production.


Example: com.iplanet.amagent.config.filter.notEnforcedList.cacheSize=1000


Not-Enforced-List Cache Expiration Time

Key: com.iplanet.amagent.config.filter.notEnforcedList.cacheTime

Description: This property specifies the amount of time in seconds that will be used to evaluate if a cached entry can be removed from the cache to free up resources for new cache entries.

Valid Values: Non-zero unsigned integer indicating the time in seconds that will be used as the cache expiration time for entries in the cache during a cleanup operation.


Note
  • Values that are valid but not suited for the deployment scenario may result in degradation of system performance.

  • The value for optimal system performance will depend on the type of application deployed, the number of possible request URIs in the deployed application, the user load on the system, the expiration time set for cache entries, and a host of other deployment specific factors.

  • To determine the most optimal value of this property, the application should be load tested in a controlled test environment before being deployed for production.


Example: com.iplanet.amagent.config.filter.notEnforcedList.cacheTime=60


SSO Token URL Decode Flag

Key: com.iplanet.amagent.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.iplanet.amagent.config.filter.urlDecodeSSOToken=true


Default Web Application Name

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

Description: This property specifies a name for the Default Web Application deployed on the application server.

Valid Values: A string consisting of lower case and or upper case letters that can be used as the name for 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.iplanet.amagent.config.filter.defaultWebAppName=DefaultWebApp


Global Not-Enforced List

Key: com.iplanet.amagent.config.filter.global.notEnforcedList[index]

Description: This property specifies a list of patterns that can be used to evaluate if the requested URI does not require the protection enforced by the Agent.

Valid Values: Valid values must comply with the syntax of this property. The valid values can be exact URIs or patterns consisting of wild-card character '*' to indicate zero or more characters. The syntax of this property is as follows:

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

index is an integer that starts from 0 and increments for every entry in this property list

pattern is a string that represents request URIs that are not enforced by Agent.

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

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


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


Example:

com.iplanet.amagent.config.filter.global.notEnforcedList[0]=*.gif

com.iplanet.amagent.config.filter.global.notEnforcedList[1]= public/*

com.iplanet.amagent.config.filter.global.notEnforcedList[2]= /images/*


Application Interceptor Configuration

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


Application Not-Enforced-List

Key: com.iplanet.amagent.config.filter.AppName.notEnforcedList[index]

Description: This property specifies a list of patterns that can be used to evaluate if the requested URI does not require the protection enforced by the Agent for a particular application. 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.iplanet.amagent.config.filter.AppName.notEnforcedList[index]= pattern

AppName is the context path name without the leading forward-slash character (/) for the deployed application.

index is an integer that starts from 0 and increments for every specified property for the particular application.

pattern is a string that represents the URIs that are not enforced by the Agent.


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

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

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

  • No value for this property indicates an empty not enforced list.


Example:

com.iplanet.amagent.config.filter.Portal.notEnforcedList[0]= /Portal/GuestPages/*

com.iplanet.amagent.config.filter.Portal.notEnforcedList[1]= /Portal/Registration/*

com.iplanet.amagent.config.filter.Portal.notEnforcedList[2]= /Portal/WebServices/PollServlet

com.iplanet.amagent.config.filter.BankApp.notEnforcedList[0]= /BankApp/ModuleGuestTour/*

com.iplanet.amagent.config.filter.BankApp.notEnforcedList[1]= /BankApp/index.html

com.iplanet.amagent.config.filter.DefaultWebApp.notEnforcedList0]=/ index.html

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


Debug Engine Configuration

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


Debug Level

Key: com.iplanet.amagent.config.debug.level

Description: This property specifies the amount of debug messages that will be generated by the Agent's Debug Engine.

Valid Values: Any of 0, 1, 3, 7, 15, and 31. These values indicate the following:

0 = No debugging

1 = Only Error messages

3 = Error and Warning messages

7 = Error, Warning and Brief Informational messages

15= Error, Warning and Verbose Informational messages

31= Error, Warning and Very Verbose Informational messages


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

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


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


Debug Log File

Key: com.iplanet.amagent.config.debug.logfile.name

Description: This property specifies the Debug log file to be used for recording Debug messages.

Valid Values: String representing the complete path name of the file to be used by the Agent to record Debug messages.


Note
  • Ensure that the WebSphere Application Server process has sufficient permissions to write to this file.

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


Example:

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


Debug Log File Rotation Flag

Key: com.iplanet.amagent.config.debug.logfile.rotate

Description: This property specifies if the Debug log file should be rotated by the Agent.

Valid Values: true/false. The default value of this property is false and should be changed as necessary.

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


Debug Log File Rotation Size

Key: com.iplanet.amagent.config.debug.logfile.rotate.size

Description: This property specifies the approximate size of the Debug log file in bytes, which should be used to evaluate when the log file needs to be rotated.

Valid Values: Non-zero unsigned integer indicating the size in bytes to be used to evaluate when the log file needs to be rotated. Default value of this property is 52428800 bytes (~ 50 MB) and should be changed as required.


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


Example:

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


Debug Time/Date Format String

Key: com.iplanet.amagent.config.debug.date.format

Description: This property specifies the format of time stamp that is used to mark the exact time when the Debug message was recorded.

Valid Values: Valid java.text.SimpleDateFormat Time Format Syntax string. For more information, refer URL:

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


Note The default value of this property is set to <MMM d, yyyy h:mm:ss a z> 'Agent' and should be changed as necessary.

Invalid value of this property will result in loss of time stamp data with debug messages.


Example:

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



SSL Configuration


The SSL Configuration involves the following tasks:

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

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

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

  4. Configuration Changes in AmConfig.properties

    This is the additional step to be performed when the Identity Server is running in SSL Mode.

    com.iplanet.am.server.protocol=https

    com.iplanet.am.naming.url=https://silver.india.sun.com:8080/amserver/namingservice

    com.iplanet.am.notification.url=https://silver.india.sun.com:8080/amserver/notificationservice

    com.iplanet.am.session.server.protocol=https

  5. Importing the root CA cert into Application Server JVM Keystore

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

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

      cmscacert: just a cert name

      keystore: all cert installed

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

  1. Login as root.

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

  3. Set your JAVA_HOME environment variable to the JDK supplied with WebSphere Server 4.0.3 server:

    WAS_root_dir/java

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

    #./uninstall_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.


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


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

    # ./uninstall_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 installer 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

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

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

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

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

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

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

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


    Note It is recommended that you check the log file by clicking the Details button to identify errors. If you find errors, try to uninstall the Agent manually by removing the package SUNWamwas using the pkgrm command.


  6. Remove the Realm Administrator from the AdminRole.


Uninstalling the Agent Using Command Line

  1. From the directory where the agent is installed, enter the following command at the command line:

    # ./uninstall_wasagent -nodisplay

  2. When prompted, Please enter path to pick up java: Type the full path where WebSphere JDK is located.

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

    To remove the product and all of the components from your system, type1 for Full. To remove some, but not all product components, type2 for Partial.

  4. The following text displays:
    Ready to Uninstall

    1. Uninstall Now
    2. Start Over
    3. Exit Uninstallation

    When prompted, What would you like to do? type 1 to begin uninstallation.

  5. The following text displays:

    Product                                     Result     More Info
    1. Sun_TM_ONE Identity Server Policy Agent  Full       Available
    2. Done

    To see log information on the agent, enter 1. To exit the Uninstallation program, enter 2.

  6. Remove the Realm Administrator from the AdminRole.


Removing Realm Administrator From AdminRole

  1. Start the WebSphere Administrative Console using the following command:

    # WAS_root_dir/bin/adminclient.sh

  2. In the WebSphere Advanced Administrative Console, choose Console > Security Center.

  3. In the Security Center Window, click on the Administrative Role tab.

  4. Select the AdminRole and click on Select.

  5. In the Select Users/Groups - AdminRole screen, select the Realm Administrator and click on Remove. Click OK.

  6. In the Security Centre window, click on Apply and then OK to apply the changes made.

  7. Restart WebSphere for changes to take effect.



Troubleshooting Information


Installation 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 Realm Admin User (Security Server Id) and Realm Admin User Password (Security Server Password).You can try giving the correct values in the Administrative Console Security Center. Apply the changes and restart the WebSphere.

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

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

    2. The System property java.protocol.handler.pkgs was added by the Agent installer 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

    3. Verify the Identity Server configuration parameters in the AmAgent.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


Uninstallation Problems

During the installation, the Agent Installer performs modifications for certain existing files on your system. In order that these modifications can be backed out completely, backups of these files are created before the modifications are made. In case you encounter any failures during the uninstall, it is possible to bring the system back to its original state manually by restoring the backed up files. 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 backed up during installation and restored during the uninstallation of the Agent, along with their original location.

  • WebSphere Server Startup Script file:

    WAS_root_dir/bin/startupServers.sh

  • Command-Line Setup Script file:

    WAS_root_dir/bin/setupCmdLine.sh

  • 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

Also, some of the files such as admin.config may have undergone changes after the Agent Installation. These changes could be unrelated to the Agent. For this reason, the Agent uninstallation also creates a backup of the version of the above files, just before the uninstallation under the directory WAS_root_dir/amAgentBackup. These can be used to manually reapply those changes to the current copy of these files.



Known Problems


  • Silent installation is not supported.

  • Expanding the installer panels does not resize the screen.

  • Command-line installation does not allow user to go back to previous step.

  • When a request is passed from Identity Server to Web Agent the LDAP Attribute header name containing the lower case characters change to upper case, the header is prefixed with "HTTP" key, and hyphen (-) is changed to underscore (_). These changes are undone when the request is passed from Web Server to WebSphere Application Server.

  • The uninstaller does not remove the package SUNWamwas if the WebSphere is configured manually.


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

Last Updated January 20, 2003