|
Sun Java System Access Manager 7 2005Q4 |
Last updated: Aug. 12, 2006
The latest revisions of the Access Manager 7 2005Q4 patches are available for download from SunSolve Online: http://sunsolve.sun.com. The most recent patch IDs are:
Important Access Manager 7 patches are cumulative. You can install patch 3 without first installing patch 1 or patch 2. However, if you did not install patch 1 or patch 2, review the new features and issues in the Access Manager 7 2005Q4 Patch 1 and Access Manager 7 2005Q4 Patch 2 sections to determine if any of the features and issues apply to your deployment. For example, if you didn't install patch 2, you might need to run the amadmin command to load specific XML files.
Access Manager 7 patch 3 (revision 03) fixes a number of problems, as listed in the README file included with the patch. Patch 3 also includes the following new features and known issues:
The Access Manager site monitoring feature includes these new properties:
| Property | Description |
|---|---|
| com.sun.identity.sitemonitor.interval | Interval time in microseconds for site monitoring. The site monitoring feature checks each siteÆs availability within the specified time interval. Default: 60000 microseconds (1 minute). |
| com.sun.identity.sitemonitor.timeout | timeout in microseconds for site availability checking. The site monitoring feature waits for the specified timeout value for a response from the site. Default: 5000 microseconds (5 seconds). |
The patch does not add these properties to the AMConfig.properties file. To use these new properties with values other than the default values:
1. With a text editor, add the properties and their values to the AMConfig.properties file in the following directory, depending on your platform:
2. Restart the Access Manager Web container for the values to take effect.
For Policy Agents, add these properties to the AMAgents.properties file.
Custom implementation. In addition, the com.sun.identity.sitemonitor.SiteStatusCheck class allows you to customize your own implementation for checking site availability using the following interface:
package com.iplanet.services.naming.WebtopNaming$SiteStatusCheck
Each implementation class must use the doCheckSiteStatus method.
public interface SiteStatusCheck {
public boolean doCheckSiteStatus(URL siteurl);
The default version of ID-WSF in Access Manager 7 patch 3 is WSF1.1. There is no separate configuration needed to trigger the ID-WSF, except that the samples need to use the new security mechanisms. The new security mechanisms for the ID-WSF1.1 are:
urn:liberty:security:2005-02:null:X509
urn:liberty:security:2005-02:TLS:X509
urn:liberty:security:2005-02:ClientTLS:X509
urn:liberty:security:2005-02:null:SAML
urn:liberty:security:2005-02:TLS:SAML
urn:liberty:security:2005-02:ClientTLS:SAML
urn:liberty:security:2005-02:null:Bearer
urn:liberty:security:2005-02:TLS:Bearer
urn:liberty:security:2005-02:ClientTLS:Bearer
New Property for Liberty ID-WSF Support
The com.sun.identity.liberty.wsf.version property determines the Liberty ID-WSF framework when the framework cannot determine from the in-bound message or from the resource offering when Access Manager is acting as the WSC. Values can be 1.0 or 1.1. The default is 1.1.
Note The patch installation does not add the com.sun.identity.liberty.wsf.version property to the AMConfig.properties file (CR# 6458184). To use this new property, add it to the AMConfig.properties file with the appropriate value after you install the patch and then restart the Access Manager Web container.
After Access Manager 7 patch 3 is installed, run the following command to load the schema changes:
# AccessManager-base/bin/amadmin -u amadmin -w amadmin_password -t /etc/opt/SUNWam/wsf1.1_upgrade.xml
The default value of AccessManager-base is /opt/SUNWam on Solaris systems and /opt/sun/identity on Linux systems.
The ID-WSF discovery registration can use these new security mechanisms when registering. Also, WSCs will automatically detect which version to use while communicating to WSPs. To configure for ID-WSF1.1, follow the Readme files for the Liberty ID-FF sample1 and the ID-WSF samples that are included with the product.
An organization in an Access Manager DIT that was created before the Access Manager 7 release might not have the sunISManagedOrganization object class. Also, an organization created by a product other than Access Manager will not have the sunISManagedOrganization object class in its definition.
Workaround. Before you upgrade to Access Manager 7 2005Q4, make sure that all organizations in the DIT have the sunISManagedOrganization object class in their definition. If necessary, manually add this object class before you upgrade.
An upgrade caused the following error on the Current Sessions tab in the Access Manager Console:
Failed to get valid Sessions from the Specified server
This problem applies to deployments that are upgrading from Access Manager 6.x versions that have a root suffix of the form o=orgname.
Workaround. After installing Manager 7 2005Q4, apply Manager 7 Patch 3 and then run the amupgrade script to migrate the data, as follows:
When you deploy the Access Manager client SDK (amclientsdk.jar) and enable polling, errors such as the following can occur:
ERROR: Send Polling Error:
com.iplanet.am.util.ThreadPoolException: amSessionPoller thread pool's task queue is full.
Such errors can occur after you deploy the Distributed Authentication UI, J2EE agents, or in any situation where you deploy the Access Manager client SDK on a client machine.
Workaround: If you have only a few hundred concurrent sessions, add following properties and values in either the AMConfig.properties file or the AMAgents.properties 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 the amtune-identity script. For example, for a machine with 4GB of RAM, the Access Manager amtune-identity script sets the following values:
com.sun.identity.session.notification.threadpool.size=28
com.sun.identity.session.notification.threadpool.threshold=76288
Set similar values on the client side in the AMAgent.properties or AMConfig.properties file when the Distributed Authentication UI server or the Access Manager client SDK is deployed on a client machine with 4GB of RAM.
Access Manager site failover includes the following new properties:
com.sun.identity.sitemonitor.interval
com.sun.identity.sitemonitor.timeout
For more information, see New Configuration Properties for Site Monitoring.
If you do not want to use the default administrative user (amadmin) for Distributed Authentication application authentication, follow this procedure to create a Distributed Authentication administrator:
com.sun.identity.authentication.special.users=cn=dsameuser,ou=DSAME Users,o=am|cn=amService-UrlAccessAgent,ou=DSAME Users,o=am|uid=distauthadmin,ou=People,o=am
Add this property to the AMConfig.properties file of all Access Manager servers, so that the Distributed Authentication admin user is not subject to session limits and session quotas.
If your deployment includes a load balancer in front of multiple Distributed Authentication UI servers, set the following properties in the AMConfig.properties file after you deploy the WAR file.
com.iplanet.am.lbcookie.name=DistAuthLBCookieName
com.iplanet.am.lbcookie.value=DistAuthLBCookieValue
For cookie replaying to work properly for Access Manager session failover, add the following property to the AMAgent.properties file for the Policy Agent and set it to true. For example:
com.sun.identity.session.resetLBCookie='true'
By default, a Policy Agent and Access Manager servers assume a load balancer cookie name of "amlbcookie". If you change the name of the cookie on the back-end server, you must use the same name in the the AMAgent.properties file for the Policy Agent. Also, if you are using the Access Manager client SDK, you must also use the same cookie name used by the back-end server.
Access Manager no longer supports the the com.iplanet.am.lbcookie.value property on servers to customize the load balancer cookie. Instead, Access Manager now uses the server ID, which is configured as part of session configuration, for the cookie value and for the name to be replayed by the agent.
After setting up the Liberty Identity Federation Framework (ID-FF) sample 1, Federation succeeded, but SSO failed.
Workaround. Add the uuid of dsameuser to the com.sun.identity.authentication.special.users property in the AMConfig.properties file. For application authentication, dsameuser needs a non-expiring SSO token for the Access Manager server.
When a user logs into Access Manager, repetitive LDAP searches on the user's nsRoleDN attribute occur.
Workaround: After the Access Manager 7 patch 3 is installed, run the following command (shown for Solaris systems):
# /etc/SUNWam/bin/amadmin -u amadmin -w amadmin_password -t /etc/opt/SUNWam/idRepoServiceAddAttrSchemaRequest_Cache.xml
An authentication module can override the "goto" URL and request re-direction to a different URL of an external Web site to get the user status validated.
See also the following CR 6385184 for additional information.
In this scenario, the deployment is using a custom authentication module to access a provisioning/credit card site:
Workaround: To fix this problem, apply latest version of the "Core Mobile Access" patch, depending on your platform:
After applying the patch, restart the Web container.
Access Manager 7 patch 2 (revision 02) fixed a number of problems, as listed in the README file included with the patch. Patch 2 also includes the following new features and known issues:
Patch 2 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.
| 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. |
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:
2. Restart the Access Manager web container for the values to take effect.
The new com.sun.identity.federation.spadapter property defines the implementation class for com.sun.identity.federation.plugins.FederationSPAdapter, which is used to add application specific processing during Federation processing on the Service Provider side.
See also CR# 6385696: Existing and new IDPs and SPs are not visible.
LDAPFilterCondition support is added in patch 2. Policy administrator can now specify an LDAP filter in the Condition while defining a policy. Policy would be applied to the user only if the LDAP entry of the user satisfies the LDAP filter specified in the Condition. The LDAP entry of the user is looked up from the directory specified in the Policy Config service.
To register and use the LDAPFilterCondition, run following commands after the Access Manager 7 patch 2 is installed.
# AccessManager-base/bin/amadmin -u amadmin -w amadmin_password -s /etc/opt/SUNWam/AddLDAPFilterCondition.xml
# AccessManager-base/bin/amadmin -u amadmin -w amadmin_password -t /etc/opt/SUNWam/amPolicyConfig_mod_ldfc.xml
The default value of AccessManager-base is /opt/SUNWam on Solaris systems and /opt/sun/identity on Linux systems.
Patch 3 Note If you have not installed Access Manager patch 2 (or did not run these commands after installing patch 2), run the above commands after installing patch 3 to import the XML files released with patch 2.
After Access Manager 7 patch 2 is installed, run following commands:
# cd DirectoryServer-Base/shared/bin
# ./ldapmodify -h DirectoryServerHost -p DirectoryServerPort -D "cn=Directory Manager" -w DirectoryMangerPassword -a -f /etc/opt/SUNWam/accountLockout.ldif
# AccessManager-base/bin/amadmin -u amadmin -w amadmin_password -t /etc/opt/SUNWam/accountLockoutData.xml
The default value of AccessManager-base is /opt/SUNWam on Solaris systems and /opt/sun/identity on Linux systems.
The default value of DirectoryServer-base is /var/opt/mps/serverroot on Solaris systems and /var/opt/sun/directory-server on Linux systems.
Patch 3 Note If you have not installed Access Manager patch 2 (or did not run these commands after installing patch 2), run the above commands after installing patch 3 to import the XML files released with patch 2.
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 trimmed off, so that can be accessed before the session is purged. For example,
com.sun.identity.session.property.doNotTrimList=UserId, HostName
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
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
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
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
Access Manager 7 patch 1 (revision 01) fixed a number of problems, as listed in the README file included with the patch. Patch 2 also includes the following new features and known issues:
Access Manager 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 was released, a debug file was created only when the first debug message was logged to the file.
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.
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.
Important If any of the files in your 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.
Before you install a patch, back up the following files:
The default value of AccessManager-base is /opt/SUNWam on Solaris systems and /opt/sun/identity on Linux systems.
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, re-deploy, and configure Access Manager, as described in the the Access Manager 7 2005Q4 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 Access Manager 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.To add or remove a patch on Solaris systems, use the patchadd and patchrm commands, which are provided with the OS.
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-03
patchadd Command
The following example installs a patch on a standalone machine:
# patchadd /var/spool/patch/120954-03
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 checks the accuracy of the other parameters values in $BASEDIR/SUNWam/amsilent contain default values. Uncomment and modify the value of each password parameter. Then, run the following command:
# cd $INSTALL_DIR/bin
# ./amconfig -s AccessManager-base/amsilent
The default value of AccessManager-base is /opt/SUNWam on Solaris systems and /opt/sun/identity on Linux systems.
Caution The 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, on a Solaris system:
# 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-03
When the 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 AccessManager-base 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 AccessManager-base/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 AccessManager-base/bin
# ./amconfig -s AccessManager-base/amsilent
The default value of AccessManager-base is /opt/SUNWam on Solaris systems and /opt/sun/identity on Linux systems.
For additional information and examples about the patchadd and patchrm commands, see the appropriate man pages.
The following example installs a patch on a standalone Linux machine:
# ./installpatch
When the postpatch script is executed, messages that will be printed are similar to the messages on a Solaris system.
However, the procedure to back out a patch on a Linux system is different than on a Solaris system. There is no generic script to back out a Linux patch. If a lower version of the patch was previously installed, you can 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.
See the next section for more information.
The patch installer might not preserve some of the customized WAR files, replacing them with non-customized versions. To help you identify and then manually update the customized contents of a WAR file, consider the following procedure.
In the following examples, AccessManager-base is /opt/SUNWam on Solaris systems and /opt/sun/identity on Linux systems.
The WAR files that get patched are:
The changeable content in a WAR file includes:
To make sure that all custom changes are preserved, follow these steps. Before you make changes to a file, always backup the file first.
# cd temporary-directory
# jar -xvf AccessManager-base/console.war
# jar -xvf AccessManager-base/services.war
# jar -xvf AccessManager-base/password.war
# cd temporary-directoryFor example, for Steps 2-4:
# jar -uvf AccessManager-base/console.war $path/$modified file
# jar -uvf AccessManager-base/services.war $path/$modified file
# jar -uvf AccessManager-base/password.war $path/$modified file
# mkdir /tmp/war.tmp
# cd /tmp/war.tmp
# jar -xvf /opt/SUNWam/services.war
# vi index.html
# jar -uvf /opt/SUNWam/services.war index.html
# cd /opt/SUNWam/bin
# ./amconfig -s /opt/SUNWam/amsilent
# cd /opt/SUNWam/bin
# ./amserver stop
# ./amserver start
For more information about running the amconfig script, see the
Access Manager 7 2005Q4 Administration Guide:
http://docs.sun.com/doc/819-2137.
If you are using Distributed Authentication or the Client SDK, recreate and redeploy the Distributed Authentication WAR file and/or the Client SDK WAR file after you install the patch. For information, see:
Copyright 2006 Sun Microsystems, Inc. All rights reserved.