Sun Java System Access Manager Policy Agent 2.2 Release Notes

Known Issues and Limitations

The known issues concerning Policy Agent 2.2 are separated into subsections as follows:

All Agents in Policy Agent 2.2

The following known issue exists that affects all agents (both J2EE agents and web agents) in the Policy Agent 2.2 software set.

Individual Policy Agent 2.2 Guides Do Not Describe Precautions Against Cookie Hijacking

Precautions you can take against cookie hijacking in an Access Manager deployment are documented in a separate technical note. Though such a deployment includes the configuration of agents from the Policy Agent 2.2 software set, the information is not currently documented in individual agent guides. The following technical note covers this issue: Technical Note: Precautions Against Cookie Hijacking in an Access Manager Deployment.

Web Agents in Policy Agent 2.2

Important known issues concerning web agents are separated in this document into the following categories:

All Web Agents in Policy Agent 2.2

The following known issues exist that affect all web agents in Policy Agent 2.2.

On UNIX-based machines, all web agents require that the X11 DISPLAY variable be set properly.

To set the X11 DISPLAY variable properly, set the variable to a valid X server before installing or uninstalling the web agent. This condition applies even when the install or uninstall command is performed from the command line using the -nodisplay argument.

A harmless error message appears in the web agent log files (6334519)

An error message appears when many concurrent users access the web agent. The error message is as follows: LogService::process() logRecWrite SAXParseException. This exception occurs in the Access Manager log in the following directory: /var/opt/SUNWam/debug. This problem is due to a bug in the multi-threaded logging mechanism of the web agent. However, no known effect to the web agent or the respective Access Manager instance occurs with this error message.

Workaround: You can ignore this message.

Web agent log entries are written to the wrong files (6301676)

When a large number of logging entries are recorded, log rotation fails and the log entries are redirected from the web agent log files to the error log files of the web container. These redirected log entries get written as stderr. The log files then accumulate on the web container without being automatically deleted.

Workaround: During production, do not use fine-grained logging levels, such as levels 4 or 5. These logging levels are only appropriate for short periods of time, such as for debugging.

Besides Agent for Apache HTTP Server 2.0.54, web agents do not support the 64-bit version of a deployment container (6474344)

For example, Agent for Sun Java System Web Server 6.1 does not support the 64-bit release of Sun Java System Web Server 6.1.

Workaround:Except when using Agent for Apache HTTP Server 2.0.54, do not use a web agent with a 64-bit version of the supported web container.

Web Servers often cannot interpret hyphens used in header names

When you set the following property in the web agent AMAgent.properties configuration file, be aware of the web server behavior that typically applies:

com.sun.am.policy.agents.config.profile.attribute.map

Most web servers demonstrate the following behavior:

Therefore, use underscores “_” rather than hyphens “-” in the header name mapped to the LDAP attribute name to avoid problems. For example, the following property setting could be problematic:

com.sun.am.policy.agents.config.profile.attribute.map = cn|common-name

Web servers search for the header HTTP_COMMON_NAME, and would not find HTTP_COMMON-NAME.


Note –

You can use the following property to customize the “HTTP_” prefix:


com.sun.am.policy.agents.config.profile.attribute.cookie.prefix

The following example demonstrates how this property can be set:


com.sun.am.policy.agents.config.profile.attribute.cookie.prefix = EXAMPLE_

Error message issued during installation of Policy Agent 2.2 on Linux systems

When the Linux operating system is installed, specific components can be selected. Occasionally the specific components of the operating system selected lack the libraries necessary for Policy Agent 2.2 to function. When the complete Linux operating system is installed, all the required libraries are available. The libraries that are required for the agent to function are as follows: NSPR, NSS, and libxml2.

Workaround: If the Linux operating system you are using is not complete, install the latest versions of these libraries as described in the steps that follow:

At the time this note was added, the latest version of the NSPR library packages was NSPR 4.6.x , while the latest version of the NSS library package was NSS 3.11.x.

To Install Missing Libraries for Policy Agent 2.2 on Linux Systems

Web agents do not function properly when a load balancer exists in front of an Access Manager 6.3 host (6674827)

Since the com.sun.am.ignore.naming_service property is not documented in the individual web agent guides, it is explained in this release note.

Starting with Access Manager 7.0, if a load balancer is deployed in front of an Access Manager host, by default the naming response (for all services) uses the protocol, host, and port number of the load balancer.

However, for Access Manager 6.3, the naming response by default uses the protocol, host and port number of the individual Access Manager Server instances. The web agents must then replace the protocol, host, and port number of the individual Access Manager Server instances with the protocol, host, and port number of the of the load balancer. In this scenario, for Policy Agent 2.2, configure the web agent to use the correct server information by setting the com.sun.am.ignore.naming_service property as shown in the workaround that follows.

Workaround: Add the following property to the web agent AMAgent.properties configuration file and set the value to true as indicated:

com.sun.am.ignore.naming_service = true

While the com.sun.am.ignore.naming_service property is not visible in the web agent AMAgent.properties configuration file, it exists in the web agent and is by default set to false. Therefore, you must add both the property and the value.

The web agent property com.sun.am.receive_timeout is not documented in any of the web agent guides (6523846)

The value for this property is the number of milliseconds the agent waits to receive responses from Access Manager. Once the amount of time that has passed matches the value set for this property, any incomplete transactions are dropped and an error is issued indicating that one of the connections has failed.

The default value is 0. When set to 0, the socket remains open indefinitely. In most cases, the value should remain at 0.

Workaround: Not applicable.

Policy Agent 2.2 for Microsoft Internet Information Services 6.0 (Microsoft IIS 6.0)

The following known problem exists that affects Agent for Microsoft IIS 6.0.

When a specific environment variable is not properly set, the system might fail (6433790)

This problem involves the following global environment variable:

NSPR_NATIVE_THREADS_ONLY

Workaround: Before you install this agent, set this environment variable as shown:

NSPR_NATIVE_THREADS_ONLY = 1

J2EE Agents in Policy Agent 2.2

Important known issues concerning J2EE agents are separated in this document into the following categories:

All J2EE Agents in Policy Agent 2.2

The following known issues exist that affect all J2EE agents in Policy Agent 2.2.

A harmless error message appears in the J2EE agent log files (6301668)

This error message, which appears in certain situations, is as follows: ERROR: RemoteHandler.getLogHostURL(): 'null' is malformed. null.

Workaround: You can ignore this message.

The agentadmin --install command displays an error message after being issued a second time (6268136)

The error message displayed in this situation is as follows:


*** ERROR: Another instance of agentadmin is already running. Please stop
that instance and try again.

This message appears when the first installation operation is aborted with the CTRL-z keystroke combination. This keystroke combination suspends the process, but does not actually stop the process. If other methods are used to abort the operation, such as the CTRL-c keystroke combination, this problem does not occur.

Workaround: When this problem is encountered, close the terminal window and open a new terminal window.

Resources accessed with Internet Explorer 6.0 SP1 can result in 404 Not Found Error (6362249)

This problem occurs when the following conditions apply:

This specific configuration results in an error message primarily because of a bug in Internet Explorer 6.0 SP1, which cannot properly handle redirection when the HTTP request contains a port number. More specifically, this browser does not update the host header to reflect the new port number when you redirect HTTP requests that contain a port number.

Workaround: If the browser used to access content protected by a J2EE agent is Internet Explorer, at a minimum, the version must be Internet Explorer 6.0 SP2.

Harmless error messages related to JAX-RPC appear in the J2EE agent debug files (6325238)

In the J2EE agent debug files, you might see exceptions related to Java API for XML-based remote procedure calls (JAX-RPC). Such messages are not an indication of any known problem.

Workaround: You can safely ignore these error messages.

Exceptions thrown when Access Manager uses polling with a J2EE agent (6452320)

Errors can occur when you perform both of the following:

  1. Deploy amclientsdk.jar file on a client machine, such as when deploying a J2EE agent.

  2. Enable polling in Access Manager.

The errors that appear are similar to the following:

ERROR: Send Polling Error:
com.iplanet.am.util.ThreadPoolException: amSessionPoller thread pool's task queue 
is full.

Workaround: This workaround is specific to J2EE agents. If you deployed Access Manager Client SDK in another manner, such as by deploying the Distributed Authentication UI, the two properties mentioned subsequently would be added to the Access Manager AMConfig.properties configuration file instead of to the J2EE agent AMAgents.properties configuration file.

If you have only a few hundred concurrent sessions, you can create the following properties in the J2EE agent AMAgents.properties configuration file by adding the two following lines to the bottom of the file:

com.sun.identity.session.polling.threadpool.size=10
com.sun.identity.session.polling.threadpool.threshold=10000

For thousands or tens of thousands of sessions, the values should be set the same as those for notification in the Access Manager AMConfig.properties file after running amtune-identity.

For example, for a machine with 4GB of RAM, the Access Manager amtune-identity will set the following:

com.sun.identity.session.notification.threadpool.size=28
com.sun.identity.session.notification.threadpool.threshold=76288

You can set similar values in the J2EE agent AMAgents.properties configuration file when the machine for the J2EE agent has 4GB of RAM:

com.sun.identity.session.polling.threadpool.size=28
com.sun.identity.session.polling.threadpool.threshold=76288

Policy Agent 2.2 guides do not explain configuration of J2EE Agents and Access Manager SDK on the Same Deployment Container

Currently, no information is provided in Policy Agent 2.2 documentation for J2EE agents regarding this issue. Therefore, the required task for this scenario is presented at this time in this document.

If you install a J2EE agent instance on the same deployment container (such as an application server) as an Access Manager SDK instance, you must edit a property in the AMConfig.properties file of the Access Manager SDK instance.

This task is necessary to ensure proper evaluation of policies. The configuration task described in this section applies to J2EE agents, not web agents, in the Policy Agent 2.2 software set. Therefore, no additional configuration steps are required when an Access Manager SDK instance and a web agent instance are installed on the same deployment container (such as a web server).


Note –

The configuration task described in this section applies to situations where Access Manager SDK was installed as a separate component using the Sun Java Enterprise System installer. The configuration task described in this section is not required for the following versions of the SDK:


ProcedureTo Install a J2EE Agent Instance With an Access Manager SDK Instance

This task is performed on the deployment container on which the Access Manager SDK is installed. This same deployment container is protected by the J2EE agent.

  1. Using an editor of your choice access the Access Manager SDK AMConfig.properties file.

  2. Edit the following property as shown

    com.sun.identity.agents.config.location = PolicyAgent-base/AgentInstance-Dir/config/AMAgent.properties
  3. Save and close the AMConfig.properties file.

  4. Restart the deployment container.

J2EE agent installation prompts do not allow responses with leading or trailing spaces (6452708)

The installer for J2EE agents does not ignore leading and trailing spaces when you provide answers to prompts. This situation can cause a variety of problems. For example, if you include a leading or trailing space when pointing to a resource, the resource would not be recognized and an error message such as the following would be issued:

ERROR: Invalid Server Instance directory.

The preceding error message is one example. Any one of several messages could be issued depending upon the specific scenario.

Workaround: None. However, be aware of the situation and be sure not to include leading or trailing spaces when providing responses to installation prompts.

The agentadmin --install command fails to install the J2EE agent because of a previous unsuccessful installation (6443460)

An agent instance directory, for example agent_001, is created early in a J2EE agent installation. If that installation is unsuccessful, then the actual agent “agent_001” is not created, but the directory agent_001 might have been created. If the agent instance directory was created, the installer does not remove it in cases where the installation fails. In such a scenario, a subsequent installation attempt of a J2EE agent would fail unless the directory agent_001 is manually removed first.

In this scenario, the installer does not detect the previously unsuccessful installation of agent_001. and, therefore, attempts to create it. At first, the installer only searches for the agent instance, not the agent instance directory. As the installation begins, the installer attempts to create the agent_001 directory, but at that point the installer finds that this directory already exists. The installer then aborts the installation. In such a scenario, an error message such as the following is issued:

ERROR: Installation failed due to the following error - (Failed to
create directory /export/j2ee_agents/am_websphere_agent/agent_001.)

Workaround: Manually remove the agent instance directory of the unsuccessful agent installation before attempting to install the agent again.

The first use of a resource protected by a declarative constraint results in a misdirect

At this time, this behavior affects all J2EE agents except for the various agents for BEA WebLogic and Apache Tomcat.

This situation occurs prior to the user being authenticated by Access Manager and only when web-tier declarative security is set for the specific resource the user is attempting to access. Under these circumstances, when the user attempts to access the resource, she (after authentication) is directed to the welcome page of the application instead of to the exact location requested.

While the user might not expect to be directed to the welcome page, the result does not constitute an access problem. From the welcome page, the user can still access the desired resource based on the policies defined.

Workaround: This behavior is expected. No workaround exists.

The agentadmin --getUuid command fails for amadmin user on Access Manager 7 with various agents (6452713)

When you issue the agentadmin --getUuid command to retrieve the universal ID of the amadmin user, you might see an error message such as the following:


agentadmin --getUuid amadmin user example
Failed to create debug directory
Failed to create debug directory
Failed to create debug directory
Failed to create debug directory
Failed to create debug directory
10/25/2006 02:22:39:834 PM PDT: Thread[main,5,main]
DataLayer: number of retry = 3

The problem occurs under these conditions:

Workaround: None at this time.

Policy Agent 2.2 for Sun Java System Application Server 8.1

The following known problems exist that affect Agent for Sun Java System Application Server 8.1.

When interacting with Application Server 8.1, the Access Manager SDK cannot initialize admin data and displays an exception message (6284280)

The exception message displayed in this situation is as follows: javax.cryptoBadPaddingException.

Workaround: None at this time.

Policy Agent 2.2 for Apache Tomcat 5.5 Servlet/JSP Container

The following known problems exist that affect Agent for Apache Tomcat 5.5 Servlet/JSP Container. This agent also supports Agent for Apache Tomcat 5.0.28 Servlet/JSP Container.

Apache Tomcat Servlet/JSP Container bits with the .exe extension do not allow the agent to perform properly (6371980)

The Apache Tomcat Servlet/JSP Container bits with the .exe extension do not contain the Catalina scripts required to plug in the agent realm and filter. Therefore, Apache Tomcat Servlet/JSP Container bits with the .exe extension are not supported by the agent.

Workaround: When installing Apache Tomcat Servlet/JSP Container bits use the .zip extension. For example, for version 5.5.9, the correct compressed file supported by the agent is as follows:

jakarta-tomcat-5.5.9.zip

Compressed files for Apache Tomcat Servlet/JSP Container are available at the Apache web site. For example, you can attempt to retrieve the compressed file specifically for version 5.5.9 using the following link: http://archive.apache.org/dist/tomcat/tomcat-5/archive/v5.5.9/bin/jakarta-tomcat-5.5.9.zip.

Error message issued with certain versions of the deployment container starting with Apache Tomcat 5.5.23 Servlet/JSP Container

This is a classpath issue. After installing Agent for Apache Tomcat 5.5 Servlet/JSP Container on Apache Tomcat 5.5.23, the Apache server does not start. The server log might show an error that includes the following line:

java.lang.NoClassDefFoundError: org/apache/commons/modeler/BaseModelMBean

This error occurs because a jar file that was named commons-modeler.jar prior to Apache Tomcat 5.5.23 Servlet/JSP Container changed names to commons-modeler-2.0.jar in Apache Tomcat 5.5.23 Servlet/JSP Container.

Workaround: After installing Agent for Apache Tomcat 5.5 Servlet/JSP Container on Apache Tomcat 5.5.23, follow these steps:

  1. Open the following platform specific file:

    Unix-based systems (includes Linux)

    Tomcat-base/bin/setAgentclasspath.sh

    Windows Systems

    Tomcat-base\bin\setAgentclasspath.bat

  2. Change the name of commons-modeler.jar file to commons-modeler-2.0.jar.

  3. Save the file.

  4. Restart Apache Tomcat 5.5 Servlet/JSP Container.

Policy Agent 2.2 for IBM WebSphere Application Server

The following known problems exist that can affect the following agents: Agent for IBM WebSphere Application Server 5.1.1, Agent for IBM WebSphere Application Server 6.0, Agent for IBM WebSphere Application Server 6.1.

The agentadmin --install command fails on Agent for IBM WebSphere Application Server (6385085)

This issue applies to both Agent for IBM WebSphere Application Server 5.1.1 and Agent for IBM WebSphere Application Server 6.0.

The --install option of the agentadmin command can fail because of an issue with the IBM Java Development Kit (JDK). The IBM JDK comes with IBM WebSphere Application Server.

To run the --install option, the agentadmin script searches for a JDK with a Sun Microsystems JCE provider. However, the IBM JDK does not come with this JCE provider.

Therefore, to allow the agent installer to work with the IBM JDK, implement the steps described in the following workaround.

Workaround: The following task involving the editing of the agentadmin file makes available a JCE implementation that allows the agent installer to function properly.

ProcedureTo Enable the agentadmin Script to Locate the Respective JCE Implementation

  1. Change to the directory containing the agentadmin file:

    PolicyAgent-base/bin
  2. Create a backup copy of agentadmin file.

    This file is either the agentadmin script or, for Windows systems, the agentadmin.bat file.

  3. Edit the agentadmin file accordingly.

    1. Locate the last line of the agentadmin script.

      This line starts with the following string: $JAVA_VM -classpath ...

    2. Add the following two properties between the string $JAVA_VM and the string -classpath:

      -DamCryptoDescriptor.provider=IBMJCE -DamKeyGenDescriptor.provider=IBMJCE

      For example, after editing the final line of the script, it appears as follows:

      $JAVA_VM -DamCryptoDescriptor.provider=IBMJCE
      -DamKeyGenDescriptor.provider=IBMJCE -classpath $AGENT_CLASSPATH
      com.sun.identity.agents.tools.launch.AgentAdminLauncher $*

Harmless error message related to the DirectoryManager class appears in the debug files of agents for IBM WebSphere Application Server (6403913)

This issue applies to both Agent for IBM WebSphere Application Server 5.1.1 and Agent for IBM WebSphere Application Server 6.0.

An exception message appears in the debug logs for the message mode. The exception message states that the DirectoryManager class cannot be found. The message is issued by the software development kit (SDK) as it searches for an indication of the mode in which it is running: remote or server.

Workaround: You can safely ignore this message.

Using the agentadmin command fails under specific conditions when Agent for IBM WebSphere Application Server is used with Access Manager 6.3 (6443463)

The problem occurs when spaces are used in the common name (cn) in specific scenarios. The following conditions can cause the problem:

The following agentadmin command illustrates the problem. Notice that the cn contains spaces: was admin role. The spaces before and after the string admin are not allowed:

/agentadmin --setGroup administrator "cn=was admin role,dc=example,dc=com"
/opt/WebSphere/AppServer/config/cells/

Workaround: Use a text editor of your choice to directly map the groups in the admin-authz.xml file.

The sample application of Agent for IBM WebSphere Application Server provides incorrect information about the role required (6452733)

This issue applies to both Agent for IBM WebSphere Application Server 5.1.1 and Agent for IBM WebSphere Application Server 6.0.

The sample application issues a message that erroneously states that you must be logged in with the role “employee” in order to be granted access.

The following specific conditions apply:

Workaround: None. However, be aware of the situation and be sure to log in as a user who belongs to the “manager” role.

The agentadmin --install command fails to install a second instance of Agent for IBM WebSphere Application Server when using the same bits on the same host (6452719)

This issue applies to both Agent for IBM WebSphere Application Server 5.1.1 and Agent for IBM WebSphere Application Server 6.0.

If two instances of Agent for IBM WebSphere Application Server are required on the same host, you cannot use the same agent bits to install each instance.

Workaround: Download a second set of bits to install the second instance of Agent for IBM WebSphere Application Server.

During the installation of Agent for IBM WebSphere Application Server on a Windows system, the IBM JVM returns an empty encryption key (6461210)

This issue applies to both Agent for IBM WebSphere Application Server 5.1.1 and Agent for IBM WebSphere Application Server 6.0.

Be aware that this issue only occurs on Windows systems. During the installation of the agent, you are prompted for the encryption key, as such:

Enter a valid Encryption Key.
[ ? : Help, < : Back, ! : Exit ]
Enter the Encryption Key []:

Usually, a default encryption key is provided in the prompt. However, depending upon the configuration of the IBM WebSphere Application Server instance, the IBM Java Virtual Machine (JVM) might return an empty encryption key. In such a case, the agent installer presents the prompt without a default encryption key included, as illustrated by the preceding example prompt.

Workaround: Manually enter a random value in response to this prompt.

Settings for CLASPATH variable are lost after agentadmin command is issued (6653936)

This behavior has been observed with Agent for IBM WebSphere Application Server 6.0. Though rare, CLASPATH variable settings can be cleared after the agentadmin command is executed.

Workaround: Manually add the following entries to the CLASPATH variable of the IBM WebSphere Application Server 6.0 instance (where agent_001 is an example of the agent instance. It might be another instance, such as a agent_002or agent_003):

Policy Agent 2.2 for Oracle Application Server 10g

The following known problem exists that affects Agent for Oracle Application Server 10g.

The sample application requires editing to work properly (6486895)

The sample application of Agent for Oracle Application Server 10g requires minor editing of XML files to work properly. The following task explains the editing required.

ProcedureTo Configure XML Files of the Sample Application

  1. Using a text editor of your choice, access the PolicyAgent-base/sampleapp/build.xml file.

  2. Change line 69 as shown:

    Change From

    <pathelement location="${appserv.lib.dir}/ebj.jar"/>

    Change To

    <pathelement location="${appserv.lib.dir}/ejb.jar"/>

  3. At line 95, add the following snippet:

    <pathelement location="${appserv.lib.dir}/servlet.jar"/>
    <pathelement location="${appserv.lib.dir}/ejb.jar"/>
  4. Save and close the build.xml file.

  5. Using a text editor of your choice, access the META-INF/orion-application.xml file.

  6. Add the following attribute as indicated:

    "location="./jazn-data.xml"

    The following shows how the element appears before and after you have added the required attribute:

    Change From

    <jazn provider="XML">

    Change To

    <jazn provider="XML" "location="./jazn-data.xml">

  7. (Conditional) If the jazn-data.xml file does not exist in the META-INF directory, create one as demonstrated in the following example:

    <?xml version="1.0" encoding="UTF-8" standalone='yes'?>
    <!DOCTYPE jazn-data PUBLIC "JAZN-XML Data" 
        "http://xmlns.oracle.com/ias/dtds/jazn-data.dtd">
    <jazn-data>
    <!-- JAZN Realm Data -->
    <jazn-realm>
    <realm>
    <name>jazn.com</name>
    <users>
    </users>
    <roles>
    </roles>
    </realm>
    </jazn-realm>
    
    <!-- JAZN Policy Data -->
    <jazn-policy>
    </jazn-policy>
    <!-- Permission Class Data -->
    <jazn-permission-classes>
    </jazn-permission-classes>
    <!-- Principal Class Data -->
    <jazn-principal-classes>
    </jazn-principal-classes>
    <!-- Login Module Data -->
    <jazn-loginconfig>
    </jazn-loginconfig>
    </jazn-data>
Next Steps

After you have performed the preceding steps, rebuild the sample application as described in the sample application readme.txt file, which is in the following location:

PolicyAgent-base/sampleapp/readme.txt