Sun Java System Access Manager 7 2005Q4

# Sun Java™ System Access Manager 7 2005Q4 Patch 2 Release Notes

Release Date: Apr. 21, 2006

## Contents

- What's New in Patch 2
- Pre-Installation Considerations
- Patch Installation Instructions
- Known Issues and Limitations

## What's New in Patch 2

The Access Manager 7 patch 2 fixes a number of problems, as listed in the README file included with this patch.

Patch 2 also includes the following new properties for the User Management (Access Manager SDK), Identity Repository (IdRepo), and Service Management caches. These properties allow you to enable and disable the different caches independently, based on your deployment requirements, and to set the time to live (TTL) for the cache entries.

### New Properties for the User Management, Identity Repository, and Service Management Caches

Property | Description
--- | ---
New Properties to Enable and Disable Caches
`com.iplanet.am.sdk.caching.enabled` | Global property that enables (true) or disables (false) the Identity Repository (IdRepo), User Management, and Service Management caches. If true, or if the property is not present in the `AMConfig.properties` file, all three caches are enabled.
Note The following three properties to enable or disable the specific caches apply only if the previous property is set to false.
`com.sun.identity.amsdk.cache.enabled` | Enables (true) or disables (false) only the User Management (Access Manager SDK) cache.
`com.sun.identity.idm.cache.enabled` | Enables (true) or disables (false) only the Identity Repository (IdRepo) cache.
`com.sun.identity.sm.cache.enabled` | Enables (true) or disables (false) only the Service Management cache.
New User Management Cache Properties for TTL
`com.iplanet.am.sdk.cache.entry.expire.enabled` | Enables (true) or disables (false) the expiration time (as defined by the following two properties) for the User Management cache.
`com.iplanet.am.sdk.cache.entry.user.expire.time` | Specifies the time in minutes that user entries for the User Management cache remain valid after their last modification. That is, after this specified time elapses (after the last modification or read from the directory), the data for the entry that is cached will expire. Then, new requests for data for these entries must be read from the directory.
`com.iplanet.am.sdk.cache.entry.default.expire.time` | Specifies the time in minutes that non-user entries for the User Management cache remain valid after their last modification. That is, after this specified time elapses (after the last modification or read from the directory), the data for the entry that is cached will expire. Then, new requests for data for these entries must be read from the directory.
New Identity Repository Cache Properties for TTL
`com.sun.identity.idm.cache.entry.expire.enabled` | Enables (true) or disables (false) the expiration time (as defined by the following property) for the IdRepo cache.
`com.sun.identity.idm.cache.entry.default.expire.time` | Specifies the time in minutes that non-user entries for the IdRepo cache remain valid after their last modification. That is, after this specified time elapses (after the last modification or read from the repository), the data for the entry that is cached will expire. Then, new requests for data for these entries must be read from the repository.
New Property for Federation Service Provider
`com.sun.identity.federation.spadapter` | In order to allow applications to get hold of assertion, response information such as status etc, a federation service provider adapter is added. The default implementation is com.sun.identity.federation.plugins.FSDefaultSPAdapter. The default value of the property is added by the patch.

### Using the New Caching Properties

The Access Manager 7 2005Q4 patches do not automatically add the caching properties to the `AMConfig.properties` file.

To use these new properties:

1. With a text editor, add the properties and their values to the `AMConfig.properties` file in the following directory, depending on your platform:

- Solaris systems: `/etc/opt/SUNWam/config`
- Linux systems: `/etc/opt/sun/identity/config`

2. Restart the Access Manager web container for the values to take effect.

### LDAPFilterCondition support

LDAPFilterCondition support is added in patch 2. Policy administrator can now specify an ldap filter in the Condition while defining policy. Policy would be applied to the user only if the ldap entry of the user satisfies the ldap filter specified in the Condition. Ldap entry of the user is looked up from the directory specified in PolicyConfig service.

To register and use LDAPFilterCondition, please run following commands after 7.0 patch2 is installed.

# $BASEDIR/bin/amadmin -u amadmin -w amadmin_password -s /etc/opt/SUNWam/AddLDAPFilterCondition.xml
# $BASEDIR/bin/amadmin -u amadmin -w amadmin_password -t /etc/opt/SUNWam/amPolicyConfig_mod_ldfc.xml

### Bug# 6324056: Federation Fails when using Artifact Profile

The fix is to apply a "Core Mobile Access". The patch numbers are :

- Solaris™ Operating System (Solaris OS) on SPARC® based systems: 119527-03
- Solaris OS on x86 platforms: 119528-03
- Linux systems: 119529-03

The web container should be restarted after applying the patch.

### Bug# 6283582: Num of login failures are not shared across AMs

please run following commands after 7.0 patch2 is installed

# cd <DirectoryServerBase>/mps/serverroot/shared/bin
# ./ldapmodify -h <DirectoryServerHost> -p <DirectoryServerPort> -D "cn=Directory Manager" -w <DirectoryMangerPassword> -a -f /etc/opt/SUNWam/accountLockout.ldif
# $BASEDIR/bin/amadmin -u amadmin -w amadmin_password -s /etc/opt/SUNWam/accountLockoutAuthServiceSchema.xml
# $BASEDIR/bin/amadmin -u amadmin -w amadmin_password -t /etc/opt/SUNWam/accountLockoutData.xml

### Bug# 6293673: Need to retain the original session information when sending out session timeout notification

A new property `com.sun.identity.session.property.doNotTrimList` is added to `AMConfig.properties`, which can contain list of comma separated session property names. Once a session is timed out, those properties defined in this list will not be trimed off, so that can be accessed before the session is purged. For example,

com.sun.identity.session.property.doNotTrimList=UserId, HostName

### Bug# 6244578: AM should warn user that the browser cookie support is disabled/not available

A new property `com.sun.identity.am.cookie.check` is added to `AMConfig.properties`, which indicates whether server should check for the cookie support / cookie enabled in the browser. Value `true` will result in server checking for the cookie support / cookie enabled in the browser and throwing an error page if the browser does not support or has not enabled cookie. This value should be set to `false` (which is default) if the server is expected to support cookieless mode for Authentication functionality. For example,

com.sun.identity.am.cookie.check=true

### Bug# 6236892: Image/Text place holder while CDCServlet is processing the AuthNResponse after Login

A few new properties are added to `AMConfig.properties`. The property `com.iplanet.services.cdc.WaitImage.display` needs to be set to true to have an image displayed in the browser while waiting for the protected page in a CDSSO scenario (default is false). The other three following properties allow to choose the name, the width and and the height of the image. The default name for the image is waitImage.gif. This image be copied in the login_images directory. The default size is 420 x 120. These properties will be read by CDCServlet. For example,

com.iplanet.services.cdc.WaitImage.display=false
com.iplanet.services.cdc.WaitImage.name=waitImage.gif
com.iplanet.services.cdc.WaitImage.width=420
com.iplanet.services.cdc.WaitImage.height=120

### Bug# 6363157: Need to disable unnecessary persistent searches which affect performance

A new property `com.sun.am.event.connection.disable.list` is added to `AMConfig.properties`, which specifies which event connection can be disabled. There are three valid values - aci, sm and um (case insensitive). Multiple values should be separated with comma. For example,

com.sun.am.event.connection.disable.list=aci, um

### Bug# 6385696: Existing and new IDP's and SP's are not visible

A new property `com.sun.identity.federation.spadapter` is added to `AMConfig.properties`, which specifies the default implementation of federation service provider adapter where the application can get hold of assertion, response information. For example,

com.sun.identity.federation.spadapter=com.sun.identity.federation.plugins.FSDefaultSPAdapter

Back to Top

## Pre-Installation Considerations

This document applies to the following Access Manager 7.0 2005Q4 platforms and their respective patch IDs:

- Solaris™ Operating System (Solaris OS) on SPARC® based systems: 120954
- Solaris OS on x86 platforms: 120955
- Linux systems: 120956

Before You Get Started The Access Manager patches described in this document do not install Access Manager. Before you install the patch, Access Manager 7 2005Q4 must be installed on the server. For information about installation, see the Sun Java Enterprise System 2005Q4 Installation Guide for UNIX: http://docs.sun.com/doc/819-2328

You should also be familiar with running the `amconfig` script to deploy Access Manager, as described in the the Access Manager Administration Guide: http://docs.sun.com/doc/819-2137

For a list of the Access Manager patches that are made obsolete by this patch and any patches that you must install before you install this patch, refer to the README file included with this patch.

Caution These patches (as with any other patches) should be tested on a staging or pre-deployment system before you put them into a production environment. Also, the patch installer might not update your customized JSP files properly, so you might need to make manual changes in these files in order for Access Manager to function properly.

Back to Top

## Patch Installation Instructions

Before you install a patch, backup the following files:

- `/etc/opt/SUNWam/config/xml/template/idRepoService.xml` on Solaris systems
  or `/etc/opt/sun/identity/config/xml/template/idRepoService.xml` on Linux systems
- `AccessManager-base/locale/amIdRepoService.properties`
- `AccessManager-base/locale/amConsole.properties`

where `AccessManager-base` is `/opt/SUNWam` on Solaris systems and `/opt/sun/identity` on Linux systems.

To add or remove a patch use the `patchadd` and `patchrm` commands, which are provided with the Solaris OS.

### Solaris 10 Zones

The Solaris 10 operating system introduced the new concept of "zones." Consequently, the `patchadd` command includes the new `-G` option, which adds a patch only to the global zone. By default, the `patchadd` command looks for the `SUNW_PKG_ALLZONES` variable in the `pkginfo` of packages to be patched. However, for all Access Manager packages, the `SUNW_PKG_ALLZONES` variable is not set, and the `-G` option is required if Access Manager 7 2005Q4 is installed in the global zone. If Access Manager is installed in a local zone, the `patchadd -G` option has no effect.

If you are installing Access Manager 7 2005Q4 patches on a Solaris machine, it is recommended that you use the `-G` option. For example:

# patchadd -G AM7.0_patch_dir

Similarly, if Access Manager is installed in the global zone, the `-G` option is required to run the `patchrm` command. For example:

# patchrm -G 120954-02

### patchadd Command

The following example installs a patch on a standalone machine:

# patchadd /var/spool/patch/120954-02

When the postpatch script is executed, the following message will be printed, except on a system that has only the Access Manager SDK component installed:

After the patch installation, redeploy the Access Manager applications by following the steps in the Patch Installation Instructions section. A draft `amsilent` file is created in `$BASEDIR/SUNWam` directory.

This amsilent is based on `$INSTALL_DIR/bin/amsamplesilent`, but with some required parameters set according to the Access Manager config files on this system.

The password parameter values in `$BASEDIR/SUNWam/amsilent` contain default values. Uncomment and modify the value of each password parameter, and carefully check the accuracy of the other parameters in this file. Then, run the following command:

# cd $INSTALL_DIR/bin
# ./amconfig -s $BASEDIR/SUNWam/amsilent

Caution The `$BASEDIR/SUNWam/amsilent` file contains plain text passwords. After you have run the `amconfig` script to deploy Access Manager, delete (or move and secure) the `amsilent` file to prevent any potential security problems.

After you run the `amconfig` script, restart the Access Manager processes. For example:

# cd /opt/SUNWam/bin
# ./amserver stop
# ./amserver start

Then restart the Access Manager web container.

### patchrm command

The following example removes a patch from a standalone system:

# patchrm 120954-02

When the post backout script is executed, a similar message will be printed, except on a system that has only the Access Manager SDK component installed.

After the patch is removed, redeploy the Access Manager applications by following the Patch Installation Instructions. A draft amsilent file is created in the `$BASEDIR/SUNWam` directory.

This `amsilent` file is based on `$INSTALL_DIR/bin/amsamplesilent`, but with some required parameters set according to the Access Manager config files on this system.

The password parameter values in $BASEDIR/SUNWam/amsilent contain default values. Uncomment and modify the value of each password parameter and carefully check and make sure the accuracy of other parameters in this file. Then run the command as follows:

# cd $INSTALL_DIR/bin
# ./amconfig -s $BASEDIR/SUNWam/amsilent

For additional information and examples about the `patchadd` and `patchrm` commands, see the appropriate man pages.

### Linux Platform

The following example installs a patch on a standalone machine:

# ./installpatch

When the postpatch script is executed, messages that will be printed are similar to the messages on a Solaris platform.

However, the procedure to back out a patch on a Linux platform is different than on a Solaris platform. There is no generic script to back out a Linux patch. If a lower version of the patch was previously installed, you can simply re-install that version and then follow the postpatch instructions to redeploy the Access Manager applications by running the `amconfig` script.

If the patch is installed on the Access Manager 7 2005Q4 RTM release and you want to remove the patch and restore the system to the RTM state, you must reinstall the Access Manager RTM bits using the `reinstallRTM` script. The `reinstallRTM` script takes the path where the Access Manager RTM RPMs are stored and installs the RTM RPMs over the patched RPMs. For example:

# ./scripts/reinstallRTM path_of_AM7.0_RTM_RPM_directory

After you run the `reinstallRTM` script, redeploy the Access Manager applications by running the `amconfig` script.

Back to Top

## Known Issues and Limitations

Caution If any of the files in the current installation are customized, back up those files before you install the patch. After you install the patch, compare the backed up files with the new files installed by this patch to identify the customizations. Merge the customizations with the new files and save them. For more information about how to handle customized files, read the following information.

### Bug# 6254355: Access Manager patches do not redeploy Access Manager applications in postpatch scripts

Due to complexity of updating customized content of several WAR files deployed on a web container, the patch installer might not preserve some of the customized files, replacing them with non-customized versions. To help you identify and then manually update the customized contents of a WAR file, read the following quick guide.

There are multiple ways to modify WAR files:

- Edit the files in the `$BASEDIR/$PRODUCT_DIR/web-src/applications/` directory.
- Modify the JSP files associated with the Access Manager custom admin console, authentication modules, services, etc.
- Modify the resource bundles/property files in the WAR file.

$BASEDIR applies to `/opt` and $PRODUCT_DIR applies to `SUNWam` on Solaris systems. On Linux systems, $BASEDIR applies to `/opt` and $PRODUCT_DIR applies to `/sun/identity`.

The WAR files that get modified are:

- $BASEDIR/$PRODUCT_DIR/amconsole.war
- $BASEDIR/$PRODUCT_DIR/ampassword.war
- $BASEDIR/$PRODUCT_DIR/amservices.war

The changeable content in a WAR file includes:

- Properties files (`$BASEDIR/$PRODUCT_DIR/locale/*.properties`)
- Tag library descriptors (`$BASEDIR/$PRODUCT_DIR/web-src/applications/WEB-INF/*.tld`)
- The `web.xml` file and the files used to construct it (`WEB-INF/web.xml` and `WEB-INF/*.xml`)
- Application specific files:
  - JSP (`*.jsp`) files
  - Images (`*.gif`) files
  - Style sheets - background colors, font sizes, etc. (`*.css`) files

These files are in the following directories:

- $BASEDIR/$PRODUCT_DIR/web-src/applications/console/
- $BASEDIR/$PRODUCT_DIR/web-src/services/
- $BASEDIR/$PRODUCT_DIR/web-src/password/

To update the WAR files:

# cd $BASEDIR/$PRODUCT_DIR
# jar -uvf amconsole.war <$path/$modified file>
# jar -uvf amservices.war <$path/$modified file>
# jar -uvf ampassword.war <$path/$modified file>

Here is an example:

# cd /opt/SUNWam
# jar -uvf amconsole.war index.html
# rm index.html

### Workaround for Problem 6254355

The following workaround is for the issue described in problem 6254355. Follow these steps to make sure that all custom changes are properly preserved.

Note The steps below should preserve custom changes in most cases. However, if the changes are not preserved, use the technique described above.

1. Make sure all your customized JSP files reside in the proper subdirectories under the `$BASEDIR/$PRODUCT_DIR/web-src/` directory and that you have backed up all of your customized files.
2. Install the patch.
3. Check whether the patch installer made any changes to your customized JSP files in the `$BASEDIR/$PRODUCT_DIR/web-src/...` directories and manually add your original custom changes to the ones that got changed.
4. Create a silent configuration file (for example, `amsilent`) based on the `$BASEDIR/$PRODUCT_DIR/bin/amsamplesilent` template file and then set the appropriate configuration variables in the file, including:
   • DEPLOY_LEVEL=21
   • DIRECTORY_MODE=5
   • Passwords for DS_DIRMGRPASSWD, ADMINPASSWD, and AMLDAPUSERPASSWD
   • Access Manager Web container variables
   For more information about the Web container variables, see the `amsamplesilent` file in the `/opt/SUNWam/bin` directory on Solaris systems or the `/opt/sun/identity/bin` directory on Linux systems.
5. Run the `amconfig` script as shown below. Before you run `amconfig`, Directory Server and the Access Manager web container must be running. For example, to run `amconfig` on a Solaris system with Access Manager installed in the default base installation directory:

   > # cd /opt/SUNWam/bin
   > # ./amconfig -s $BASEDIR/SUNWam/amsilent

6. After you the `amconfig` script restart the Access Manager processes. For example:

   > # cd /opt/SUNWam/bin
   > # ./amserver stop
   > # ./amserver start

   Then, restart the Access Manager web container.

For more information about running the `amconfig` script, see the Access Manager Administration Guide:
http://docs.sun.com/doc/819-2137

### Bug# 6320475: com.iplanet.am.session.client.polling.enable on server side must not be true

The `com.iplanet.am.session.client.polling.enable` property in the `AMConfig.properties` file on the server side is set to false by default and should never be reset to true.

### Bug# 6358751: Access Manager 7 patch 1 apply fails if the there are embedded spaces in the encryption key

If the password encryption key contains spaces, applying the patch fails.

Workaround Use a new encryption key that includes no spaces. For detailed steps of changing the encryption key, see Appendix B, "Changing the Password Encryption Key" in the Access Manager 7 2005Q4 Deployment Planning Guide: http://docs.sun.com/doc/819-2136

### Debug files

All debug files are created by default in the debug directory, even when `com.iplanet.services.debug.level` property in the `AMConfig.properties` file is set to error. Before Access Manager 7 Patch 1, a debug file was created only when the first debug message was logged to that file.

Back to Top

Copyright 2006 Sun Microsystems, Inc. All rights reserved.