Sun Java System Access Manager Policy Agent 2.2 Release Notes

Policy Agent 2.2–01 Update Release

Policy Agent 2.2 has had a variety of minor updates since its initial release. These updates have been referred to as hot patches. These hot patches include a variety of fixes and enhancements. The changes made in a hot patch can apply to a single agent, several agents, or all agents in an agent type: web agents or J2EE agents. Furthermore, the changes made in hot patches are cumulative, therefore, the changes are carried forward to the next hot patch.

The various agent hot patches have been combined into a single update release called Policy Agent 2.2-01. By combining all the Policy Agent 2.2 hot patches in one release, Policy Agent 2.2-01 addresses a range of issues, from relatively minor to significant.

Consider updating Policy Agent 2.2 to Policy Agent 2.2-01, especially if you have not as of yet updated Policy Agent 2.2 with any of the available hot patches.

As with all Policy Agent releases, the 2.2-01 release is divided into a J2EE agent version and a web agent version. Accordingly, this section has been divided into a web agent subsection and a J2EE agent subsection. Refer to the applicable subsection as follows:

Furthermore, as with Policy Agent 2.2, Policy Agent 2.2-01 is compatible with the following Access Manager versions: 6.3 (backward compatible), 7.0, and 7.1.

As you will notice in the J2EE agent and web agent subsections that follow, the 2.2-01 update is more comprehensive for web agents than for J2EE agents. Therefore, more fixes and enhancements were made to web agents for the 2.2-01 update.

Policy Agent 2.2-01 Web Agents

This section on 2.2-01 web agents consists of the following subsections:

The first subsection that follows explains how to determine the version of a Policy Agent 2.2 web agent. For example, you could determine if a hot patch has been applied or not.

Subsequently in this section is a subsection that describes the important fixes and enhancements introduced during the various Policy Agent 2.2 web agent hot patches and a subsection explaining the important new properties introduced.

For the complete list of known problems fixed and enhancements made, see the README provided in the web agent download. Some of the fixes, enhancements, and properties described in the sections that follow only apply to a single agent. For example, many of the changes are specific to Agent for Microsoft Internet Information Services 6.0.

Determining the Version of a Policy Agent 2.2 Web Agent

The method for determining the specific version of an installed Policy Agent 2.2 web agent is different depending upon if the web agent was developed through the OpenSSO project or not. The documentation specific to each web agent states if it was developed through the OpenSSO project. Most Policy Agent 2.2 agents were not developed through the OpenSSO project.

The following information explains how to determine the version of a web agent; therefore, you can determine if a hot patch has been applied to the web agent using the appropriate method, as follows:

OpenSSO Project Web Agents

For most OpenSSO project web agents, you can use the command line, in the PolicyAgent-base/bin directory, to issue the agentadmin --version command.

Where the agentadmin --version command does not apply, check the amAgent log file as described in the Other Web Agents section that follows.

Other Web Agents

See the amAgent log file. If you are uncertain of the location of the amAgent log file, you can find it in the web agent AMAgent.properties configuration file as the value assigned to the following property:

com.sun.am.policy.agents.config.local.log.file

Key Fixes and Enhancements in Policy Agent 2.2-01 Web Agents

This section lists the key fixes and enhancements introduced in the various Policy Agent 2.2 web agent hot patches, which are now rolled into the 2.2-01 update release. The initial issue is described with its associated change request (bug) number. Furthermore, a short summary is provided about how the fix or enhancement resolved the issue.

Policy Agent 2.2 for Microsoft IIS 6.0 does not function properly when Basic Authentication is set (6415948)

This enhancement involved a behavior modification to the Basic Authentication filter. This fix corresponds to specific versions of Access Manager, as follows:

Access Manager 7.0 series from patch 5 forward
Access Manager 7.1 series from patch 1 forward

Support is now provided for using Policy Agent and Access Manager in conjunction with Microsoft IIS 6.0 Basic Authentication. For more information on Agent for Microsoft IIS 6.0 see Sun Java System Access Manager Policy Agent 2.2 Guide for Microsoft Internet Information Services 6.0.

Request for specific session attributes to be populated in HTTP headers (6409146)

This enhancement allows the following session attributes to be set as headers:

maxSessionTime
maxIdleTime

In Policy Agent 2.2 for Microsoft IIS 6.0, Replay Password Encryption is lacking for Basic Authentication (6475899)

This enhancement improved the security around how user passwords are handled. Furthermore, this enhancement involved adding a new property to the web agent AMAgent.properties configuration file as described in Property Made Available: com.sun.am.replaypasswd.key.

Web agents in the Policy Agent 2.2 release fail with Access Manager 6.3 (6490037)

This fix enabled Policy Agent 2.2 to work properly with Access Manager 6.3.

Disabling Internet Explorer pop up when protocol changes from HTTP to HTTPS (6532260)

This problem only applied to Agent for Microsoft Internet Information Services 6.0 when the agent was deployed to provide protection for Microsoft Outlook Web Access.

While one was able to configure a local redirection page to automatically redirect incoming HTTP connection to HTTPS, when configured with Access Manager, this local redirection invoked a security pop up window in Internet Explorer browsers in certain deployment scenarios.

To fix this issue, a property was made available to convert the HTTP connection to HTTPS automatically, without a local redirection page. See Properties Made Available for Microsoft Office SharePoint and Outlook Web Access for info on the following property:

com.sun.am.policy.agents.config.iis.owa_enabled_change_protocol

Web Distributing Authoring and Versioning (WebDAV) support is necessary to allow for a wider range of HTTP methods (6567164)

WebDAV support has been implemented for web agents. Using the WebDAV protocol with web agents requires additional configuration as described in these release notes. For more information, see Access Manager and Policy Agent 2.2–01 Web Agents: Allowing Requests Using Non-Standard HTTP Methods.

Program Database (.pdb) files should be part of agent binaries to help in debugging issues (6581272)

For Windows systems, the 2.2–01 web agents come with .pdb files as part of the agent binaries. These .pdb files, which are in the same location as .dll files, can be of assistance in debugging.

Other Additions to Policy Agent 2.2-01 Web Agents

Windows Systems: For web agents on Windows systems, Policy Agent 2.2-01 is compiled with Microsoft Visual Studio 2003. As a result, the Microsoft libraries msvcr71.dll and msvcp71.dll are bundled with web agents since they are required for the agents to run successfully.

The Key New Properties Added for Policy Agent 2.2-01 Web Agents

This section describes the key properties that were added to the web agent AMAgent.properties configuration file in conjunction with the hot patches bundled in the 2.2-01 web agent release. For each property listed in this section, the following information is provided:

The associated bug (change request) number
A description of why the property was added

Property Added: `com.sun.am.tcp_nodelay.enable`

Change Request:: 6425354

This property was added to allow you to disable the Nagle algorithm. When the agent and an associated load balancer both use the Nagle algorithm, buffering of small packets can take place, causing network delays and performance problems.

Property Added: `com.sun.am.cookie.secure`

Change Request:: 6432320

This property was added to Policy Agent to allow all cookies set by the agents to be marked as secure. A cookie marked as secure is only transmitted if the communications channel with the host is secure. Therefore, only secure cookies are sent to HTTPS servers.

Property Made Available: `com.sun.am.replaypasswd.key`

Change Request:: 6475899

This property was made available to both Access Manager and Agent for Microsoft IIS 6.0 to allow Access Manager to send an encrypted password to Agent for Microsoft IIS 6.0.

This property was not specifically added to the configuration file of Access Manager or Policy Agent but simply made available. Therefore, if you want to set this property, you must add both the property name and the corresponding value. For more information, see Sun Java System Access Manager Policy Agent 2.2 Guide for Microsoft Internet Information Services 6.0.

Property Added: `com.sun.am.policy.agents.config.encode_url_special_chars.enable`

Change Request:: 6481331

When set to true, this property enables encoding of special characters, such as Chinese characters in the URL before the request is sent for policy evaluation. Otherwise, the use of special characters in the URL can cause unreliable results, even causing the web server to crash. The default setting is false. Enable this property by setting it as follows:

com.sun.am.policy.agents.config.encode_url_special_chars.enable = true

Property Made Available: `com.sun.am.policy.agents.config.no_child_thread_activation_delay`

Change Request:: 6570155

This property is specific to Apache-HTTP-Server related web agents in the Policy Agent 2.2 software set. The default for this property is false.

This property was made available to address a delay that occurs when Apache HTTP Server spawns a new process. The parent process goes to sleep for up to one second to allow the child process to get into commission. This one second delay applies to every process that the Apache HTTP Server spawns.

Setting this property to true, as shown in the following example, reduces the delay down to a range from ten microseconds to one millisecond.

com.sun.am.policy.agents.config.no_child_thread_activation_delay = true

This property was not specifically added to the web agent AMAgent.properties configuration file, but simply made available. Therefore, to set this property to true, you must add both the property name and the value.

Properties Made Available for Microsoft Office SharePoint and Outlook Web Access

Properties Made Available:

Microsoft Office SharePoint: com.sun.am.sharepoint_login_attr_name = login

Microsoft Outlook Web Access:com.sun.am.iis_owa_enabled = true

Change Request:

6532260

These new properties were added to indicate whether or not Microsoft Office SharePoint or Outlook Web Access is configured.

These properties were not specifically added to the web agent AMAgent.properties configuration file, but simply made available. Therefore, to configure these properties, you must add the applicable property name and its corresponding value.

Access Manager and Policy Agent 2.2–01 Web Agents: Allowing Requests Using Non-Standard HTTP Methods

The sections that follow are applicable to web agents starting with Policy Agent 2.2–01 used with Access Manager starting with the 7.0 release.

Supported HTTP Methods of Web Agents in Policy Agent 2.2–01

Prior to Policy Agent 2.2–01, the only HTTP methods supported by web agents were GET, HEAD, PUT, POST, DELETE, TRACE, OPTIONS. Any request received by the agent with a method other than one of these was marked as UNKNOWN and access to the resource was denied.

Policy Agent 2.2–01 Web Agents: Newly Supported HTTP Methods

With Policy Agent 2.2–01, web agents also support the following methods: CONNECT, COPY, INVALID, LOCK, UNLOCK, MOVE, MKCOL, PATCH, PROPFIND, PROPPATCH.

By default, policies in Access Manager only allow control of GET and POST actions. To extend Access Manager control to other actions, see the corresponding Access Manager document. For example, for Access Manager 7.1, see Adding a Policy Enabled Service in Sun Java System Access Manager 7.1 Administration Guide.

Policy Agent 2.2–01 Web Agents: Support for `INVALID` Methods

Typically, a web server marks a request as an INVALID method and denies access to the resource when the request uses a method other than any of the methods listed in the preceding section.

However, in cases where the web server is configured to forward requests to an application that can handle non-standard HTTP methods, the web server does not deny access, but forwards the request to the requested application. You can configure Access Manager to allow or deny such INVALID requests. A typical example is when a web agent is installed on Apache HTTP Server that is configured as a proxy for Microsoft Exchange Server. In this scenario, requests can use methods such as SEARCH or SUBSCRIBE, which are not recognized by Apache HTTP Server and, therefore, marked as INVALID.

To decide if such requests should be allowed or denied, the INVALID method must be loaded in the iPlanetAMWebAgentService service.

Policy Agent 2.2-01 J2EE Agents

This section on 2.2-01 J2EE agents consists of the following subsections:

The first subsection that follows explains how to determine the version of a Policy Agent 2.2 J2EE agent. For example, you could determine if a hot patch has been applied or not.

Subsequently in this section is a subsection that describes the important fixes and enhancements introduced during the various Policy Agent 2.2 J2EE agent hot patches and a subsection explaining the important new properties introduced.

For the complete list of known problems fixed and enhancements made, see the README provided in the J2EE agent download.

Determining the Version of a Policy Agent 2.2 J2EE Agent

The method for determining the specific version of an installed Policy Agent 2.2 J2EE agent is by using the command line. With this method, you can find the version info, such as the hot patch version, if applicable.

In the PolicyAgent-base/bin directory, issue the agentadmin --version command, where PolicyAgent-base represents the directory where the J2EE agent is installed.

Key Fixes and Enhancements in Policy Agent 2.2-01 J2EE Agents

This section lists the key fixes and enhancements introduced in the Policy Agent 2.2 J2EE agent hot patches, which are now rolled into the 2.2-01 update release. The initial issue is described with its associated change request (bug) number. Furthermore, a short summary is provided about the fix.

If you restart Access Manager but not the J2EE agent, future attempts to access an agent protected page from a browser result in a 403 Forbidden message (6636155)

This problem was fixed in Access Manager 7.0 patch 7 (CR 6496155), but the problem still exists in Access Manager 7.1.

Workaround: Two workarounds exist:

Add the following new property to the J2EE agent AMAgent.properites configuration:
com.sun.identity.enableUniqueSSOTokenCookie=false
For more about setting the value for the preceding property, see Property Made Available: com.sun.identity.enableUniqueSSOTokenCookie.

or
Always restart agent after restarting Access Manager.

IBM WebSphere Administration Console can not be used to access the users, roles and group identities in the Access Manager identity repository (6462779)

This problem stems from the custom registry that Policy Agent adds for IBM WebSphere Application Server and applies to the following agents:

Agent for IBM WebSphere Application Server 5.1.1
Agent for IBM WebSphere Application Server 6.0

In terms of Agent for IBM WebSphere Application Server 6.1, the fix was integrated into the original version of the agent.

In terms of Agent for IBM WebSphere Application Server 5.1.1 and Agent for IBM WebSphere Application Server 6.0, this fix enables you to use the WebSphere Administration Console to map the Access Manager roles, groups, and user identities to local J2EE roles that are specific to IBM WebSphere Application Server for authorization purposes. Furthermore, being able to use the WebSphere Administration Console in this manner eliminates the necessity of manually editing the admin-authz.xml file or using the Policy Agent agentadmin --setGroup command.

For the fix to work, you must also implement specific tasks as described in these Release Notes. The instructions apply to Agent for IBM WebSphere Application Server 5.1.1 and Agent for IBM WebSphere Application Server 6.0. See Policy Agent 2.2–01: Enabling Access Manager Identities to Access the IBM WebSphere Administration Console.

The Key New Properties Added for Policy Agent 2.2-01 J2EE Agents

Property Made Available: `com.sun.identity.enableUniqueSSOTokenCookie`

Change Request:: 6636155

The default setting for this property is true. This property was not specifically added to the J2EE agent AMAgent.properties configuration file, but simply made available. Therefore, to set this property to false, which is required to solve the issue described in If you restart Access Manager but not the J2EE agent, future attempts to access an agent protected page from a browser result in a 403 Forbidden message (6636155), you must add both the property name and the value as follows:

com.sun.identity.enableUniqueSSOTokenCookie = false

Policy Agent 2.2–01: Enabling Access Manager Identities to Access the IBM WebSphere Administration Console

This section includes instructions necessary to take advantage of a fix implemented in Policy Agent 2.2–01 specific to agents for IBM WebSphere Application Server.

The instructions in this section apply to the following agents:

Agent for IBM WebSphere Application Server 5.1.1
Agent for IBM WebSphere Application Server 6.0

The instructions in this section do not apply to Agent for IBM WebSphere Application Server 6.1 since the instructions for that agent are integrated into the following guide: Sun Java System Access Manager Policy Agent 2.2 Guide for IBM WebSphere Application Server 6.1.

Policy Agent 2.2: Problem Accessing Identities With IBM WebSphere Administration Console

In Policy Agent 2.2, the custom registry added by the agents for IBM WebSphere Application Server did not allow the IBM WebSphere Administration Console to access the users, roles and group identities in the Access Manager identity repository.

The respective guides, Sun Java System Access Manager Policy Agent 2.2 Guide for IBM WebSphere Application Server 5.1.1 and Sun Java System Access Manager Policy Agent 2.2 Guide for IBM WebSphere Application Server 6.0 provide tasks that allow you to add J2EE roles for authorization: manually editing admin-authz.xml or executing agentadmin --setGroup option. However, those tasks do not work in an IBM WebSphere cluster deployment. Furthermore, those tasks are error prone and should be avoided.

After you implement the instructions in To Install and Configure Policy Agent 2.2–01 for IBM WebSphere Application Server, you can solely use IBM WebSphere Administration Console to map the local users and groups to Access Manager roles, groups and users.

Policy Agent 2.2–01: Overview of Fix for IBM WebSphere Administration Console Access Problem

After you upgrade Agent for IBM WebSphere Application Server Policy Agent 2.2 to Policy Agent 2.2–01, you must implement the instructions,To Install and Configure Policy Agent 2.2–01 for IBM WebSphere Application Server, to fix the console problem. For more information about the problem this fix addresses, see IBM WebSphere Administration Console can not be used to access the users, roles and group identities in the Access Manager identity repository (6462779). This fix also removes the constraint that remote node operations must be carried out by logging in as serverId, which is supplied in the custom user registry

Caution –

Specific guidelines for case sensitivity must be adhered to, as follows:

Access Manager group and role identities mapped to an IBM WebSphere Application Server role

For example if you have a role named “WASAdmin” in Access Manager, you must enter “wasadmin” in the IBM WebSphere Administration Console not “WASAdmin” or “WasAdmin.” If you type “WasAdmin,” the console is likely to validate and save the changes. However, a failure will result during access control evaluation because of the mismatch in case. Therefore, always use lower case characters for Access Manager role and group names in the IBM WebSphere Administration Console.
An Access Manager user identity mapped to an IBM WebSphere Application Server user identity

For example, if you have created a user in Access Manager named “WasAdminUser,” use the same case in the IBM WebSphere Administration Console.

Supplemental Instructions for Installing and Configuring Policy Agent 2.2–01 for IBM WebSphere Application Server

The instructions describe supplemental steps for installing and configuring Policy Agent 2.2–01 for IBM WebSphere Application Server 5.1.1 or 6.0. Use the instructions in conjunction with the appropriate agent guide, Sun Java System Access Manager Policy Agent 2.2 Guide for IBM WebSphere Application Server 5.1.1 or Sun Java System Access Manager Policy Agent 2.2 Guide for IBM WebSphere Application Server 6.0 and with the appropriate Access Manager documentation. The instructions include examples that serve to clarify the type of actions you can take. The examples include the following:

Example Identities:

wasagentuser

WasAgentRole

Example Access Manager Version:

Access Manager 7.1

While you can use Access Manager 6.3 or Access Manager 7.0 with Policy Agent 2.2–01, the examples provided in the instructions that follow use Access Manager 7.1.

Therefore, links to Access Manager documentation are specifically to Access Manager 7.1 documentation. If you are using a different version of Access Manager, consult the appropriate documentation.

The instructions that follow include supplemental pre-installation, installation, and post-installation steps for Policy Agent 2.2–01.

To Install and Configure Policy Agent 2.2–01 for IBM WebSphere Application Server

Create a user in Access Manager.

Example user: wasagentuser

This user is the user ID to use while installing the agents and adding the custom user registry in the Deployment Manager (In this scenario, serverId would be wasagentuser). For more information on creating a user, see To Create or Modify a User in Sun Java System Access Manager 7.1 Administration Guide.

Note –

When you install the agent for IBM WebSphere Application Server, enter the same name in the agent-profile-name prompt that you have created for the user in this step. For example, wasagentuser. The following example prompt is from the agent installer and illustrates the proper response in this scenario:

Enter a valid agent profile name. Before proceeding with the agent 
installation, please ensure that a valid Agent profile exists in Access Manager.
[ ? : Help, < : Back, ! : Exit ]
Enter the Agent Profile name: wasagentuser

Create a role in Access Manager.

Example role: WasAgentRole

For more information on creating a role, see To Create or Modify a Role in Sun Java System Access Manager 7.1 Administration Guide.

Add the newly created user (wasagentuser) to the newly created role (WasAgentRole).

For more information about adding users to roles, see To Add Users to a Role or Group in Sun Java System Access Manager 7.1 Administration Guide.

Add the appropriate privilege to the newly created role (WasAgentRole).

The privilege to use varies according to the Access Manager version as follows:
- Access Manager 7.0:
  
  Assign the “Read only access to data stores” privilege to the newly created role (WasAgentRole).
- Access Manager 7.1:
  
  Assign the “Read and write access only for policy properties” privilege to the newly created role (WasAgentRole).
For more information about adding privileges to roles for Access Manager 7.1, see Defining Privileges for Access Manager 7.1 in Sun Java System Access Manager 7.1 Administration Guide or Defining Privileges for an Access Manager 7.0 to 7.1 Upgrade in Sun Java System Access Manager 7.1 Administration Guide.

Edit the Access Manager AMConfig.properties file to allow the agent to get a non-expiring SSO token to Access Manager

This step is required to get a non-expiring SSO token for the agent's self authentication to Access Manager.

You must edit the following property to include the distinguished name (DN) of the user (wasagentuser):

com.sun.identity.authentication.special.users

If you have a server farm, you must perform this step on all servers.

Use the legacy SDK DN not the universal UID of the user. For the example presented in this task, the appropriate setting is as follows:

com.sun.identity.authentication.special.users = cn=dsameuser,
ou=DSAME Users, ROOT_SUFFIX|cn=amService-UrlAccessAgent, ou=DSAME Users,
ROOT_SUFFIX|uid=dmgr,ou=people,ROOT_SUFFIX|
uid=wasagentuser,ou=people,ROOT_SUFFIX

Where ROOT_SUFFIX is a place holder that represents the root suffix of the directory user management node. For example, dc=example, dc=com. Ensure that this suffix exists in the instance of the directory server you are using.