Access Manager 7 patch 5 (revision 05) fixes a number of problems, as listed in the README file included with the patch. Patch 5 also includes the following new features, issues, and documentation updates.
New Features in Patch 5
Support for specific application idle session timeout values
CDC Servlet can be deployed on a Distributed Authentication UI server
Realm can be specified when CDC servlet redirects to the Access Manager login URL
Certificate Authentication can use UPN value to map user profile
Post authentication processing of logout occurs in a multiple-server environment
User no longer must authenticate twice in authentication chain
Known Issues and Limitations in Patch 5
CR# 6527528: Patch removal leaves XML files with amldapuser password in clear text
CR# 6527516: Full server on WebLogic requires JAX-RPC 1.0 JAR files to communicate with client SDK
CR # 6523499: Patch 5 amsilent file is readable by all users on Linux systems
CR# 6520016: Patch 5 SDK-only install overwrites the samples makefiles
CR#6515502: LDAPv3 repository plug-in does not always handle Alias Search Attribute correctly
CR# 6515383: Distributed Authentication and J2EE agent do not work in same web container
CR# 6508103: Online help returns application error with Application Server on Windows systems
CR# 6507383 and CR# 6507377: Distributed Authentication requires explicit goto URL parameter
CR# 6402167: LDAP JDK 4.18 causes LDAP client/Directory Server problems
CR# 6352135: Distributed Authentication UI server files are installed in incorrect location
CR# 6513653: Issue with com.iplanet.am.session.purgedelay property setting
Globalization (g11n) Issues
Documentation Updates
Document that Access Manager cannot revert from Realm Mode to Legacy Mode (6508473)
Document more information about disabling persistent searches (6486927)
Document Access Manager supported and unsupported privileges (2143066)
Document Windows Desktop SSO configuration for Windows 2003 (6487361)
Document steps to set up Distributed Authentication UI server passwords (6510859)
Online Help for “To create a new site name” needs more information (2144543)
Patch 126371 provides support for HP-UX systems. For more information see:
For information about installation on HP-UX systems, see the Sun Java Enterprise System 2005Q4 Installation Guide for UNIX.
Patch 124296 provides support for Windows systems. For more information see:
For information about installation on Windows systems, see the Sun Java Enterprise System 2005Q4 Installation Guide for Microsoft Windows.
Patch 5 (and later) includes the updateschema.sh script to load the following files to update the Directory Server service schema:
AddLDAPFilterCondition.xml
amPolicyConfig_mod_ldfc.xml
accountLockoutData.xml
accountLockout.ldif
idRepoServiceAddAttrSchemaRequest_Cache.xml
wsf1.1_upgrade.xml
amAuth_mod.xml
amAuthCert_mod.xml
In previous Access Manager patch releases, you were required to load these files manually.
To run the updateschema.sh script:
Log in as or become superuser (root).
Change to the patch directory.
Run the script. For example, on Solaris systems:
# cd /120954-07 # ./updateschema.sh
On Windows systems, the script is updateschema.pl.
When the script prompts you, enter these items:
Directory Server host name and port number
Directory Server admin user DN and password
amadmin DN and password
The script validates your entries and then loads the files. The script also writes the following log file:
Solaris systems: /var/opt/SUMWam/logs/AM70Patch.upgrade.schema.timestamp
Linux systems: /var/opt/sun/identity/logs/AM70Patch.upgrade.schema.timestamp
After the script finishes, restart the Access Manager web container.
Note If you back out patch 5, the schema changes added by the updateschema.sh script are not removed from Directory Server. However, you do not need to remove these schema changes manually because they will not affect Access Manager functionality or usability after the patch is backed out.
Patch 5 allows different applications to have different session idle timeout values. In an enterprise, some applications might require session idle timeout values that are less than the session idle time out specified in the session service. For example, you have specified session the idle timeout value in the session service as 30 minutes, but an HR application should timeout if a user has been idle for more than 10 minutes.
Requirements to use this feature are:
Agents protecting the application must be configured to enforce URL policy decisions from Access Manager.
Agents must be configured to run in self policy decision cache mode. See the following properties:
For web agents: com.sun.am.policy.am.fetch_from_root_resource
For J2EE agents: com.sun.identity.policy.client.cacheMode
The Access Manager AMConfig.properties file must specify a policy component evaluation order such that Condition is evaluated last. See the following property:
com.sun.identity.policy.Policy.policy_evaluation_weights
The application access allowed by the agent based on a locally cached decision will not be known to the Condition on Access Manager. Therefore, the actual application idle timeout will be between the application idle timeout to the application idle timeout minus the agent cache duration.
To use this feature:
Add an Authentication Scheme Condition to the policies protecting the application that requires the application specific session idle timeout.
Specify the Application Name and Timeout Value in the Authentication Scheme Condition.
Use the same Application Name and Time Out value in all the policies that apply to the resources for the application.
Specify the Timeout Value in minutes. If the value is 0 or greater than the session idle timeout value specified in the session service, the value is ignored, and the timeout from session service will apply.
For example, consider a policy http://host.sample.com/hr/*, with this Authentication Scheme Condition:
Authentication Scheme: LDAP
Application Name: HR
Timeout Value: 10
If there are multiple policies defined to protect resources of the HR application, you must add the Condition to all of the policies.
When a user in a distinct session attempts to access the HR application protected by the Access Manager agent, that user is prompted to authenticate for the LDAP scheme (if the user is not yet authenticated).
If the user has already authenticated to the LDAP scheme, that user is allowed access only if the time is less than 10 minutes since the time the last authentication or if the time is less than 10 minutes since that user's last access time to the HR application. Otherwise, the user is prompted to authenticate to the LDAP scheme again to access the application.
The CDC Servlet can coexist with a Distributed Authentication UI server in the DMZ to enable Cross-Domain Single Sign-On (CDSSO). The Access Manager server can be deployed behind a firewall, and all access to Access Manager to achieve CDSSO is handled by the CDC Servlet in the Distributed Authentication UI server. To enable CDSSO, refer to the specific policy agent documentation and perform these additional steps:
Modify the agent's AMAgent.properties file to point to the CDC Servlet on the Distributed Authentication side (client). For example, for web agents, change the following property:
com.sun.am.policy.agents.config.cdcservlet.url= http://DAhost.DAdomain:DAport/DISTAUTH_DEPLOY_URI/cdcservlet
Define policies as necessary in Access Manager for resources that need to be protected by the agent. For example, if agent is at host.example.com:80, define a policy for the resource as http://host.example.com:80/*.
You can now specify a realm name to the CDC servlet, so that when the redirect to the Access Manager login URL occurs, the realm name is included, and the user can logo into the specific realm. For example:
com.sun.am.policy.agents.config.cdcservlet.url= http://lb.example.com/amserver/cdcservlet?org=realm1
Previously, Certificate Authentication used only the dn component in the subjectDN to map a user profile. Access Manager now allows the user principal name (UPN) value in SubjectAltNameExt for profile mapping.
Post authentication processing now occurs when a user logs out of a different server from the one originally logged into in a multiple-server environment, either with or without session failover configured.
SAML now supports a new name identifier service provider interface (SPI), so that a site can customize the name identifier in the SAML assertion. A site can implement the new NameIdentifierMapper interface to map a user account to a name identifier in the subject of a SAML assertion.
The Access Manager site monitoring feature includes the following new properties to allow you to specify the behavior of the site status check.
Property |
Description |
com.sun.identity.urlchecker.invalidate.interval |
Time interval in milliseconds for recognizing a down or non-responding site. Default: 70000 milliseconds (70 seconds). |
com.sun.identity.urlchecker.sleep.interval |
Time interval in milliseconds that the site status check should sleep. Default: 30000 milliseconds (30 seconds). |
com.sun.identity.urlchecker.targeturl |
Different target URL for checking the Access Manager process status. Default: "/amserver/namingservice". |
The patch does not add these properties to the AMConfig.properties file. To use these new properties with values other than the default values:
Add the properties and their values to the AMConfig.properties file. For Policy Agents, add these properties to the AMAgents.properties file.
Restart the Access Manager web container for the values to take effect.
Consider the following scenario. A site configures an authentication chain with three LDAP modules. All modules are set to SUFFICIENT, and both the iplanet-am-auth-shared-state-enabled and iplanet-am-auth-store-shared-state-enabled options are set to true. For example:
<AttributeValuePair> <Value>A-LDAP SUFFICIENT iplanet-am-auth-shared-state-enabled=true iplanet-am-auth-store-shared-state-enabled=true</Value> <Value>B-LDAP SUFFICIENT iplanet-am-auth-shared-state-enabled=true iplanet-am-auth-store-shared-state-enabled=true</Value> <Value>C-LDAP SUFFICIENT iplanet-am-auth-shared-state-enabled=true iplanet-am-auth-store-shared-state-enabled=true</Value> </AttributeValuePair>
Patch 5 adds the new iplanet-am-auth-shared-state-behavior-pattern option to the module options with two possible values: tryFirstPass (default) and useFirstPass.
To prevent a user from having to enter the user ID and password twice to get authenticated (as described in the previous scenario), set this new option to useFirstPass for all modules in the chain. Previously, a user who existed only in the third LDAP instance was required to enter a user ID and password twice to get authenticated.
Patch 5 includes these changes to the performance tuning scripts:
Tuning script removes unnecessary ACIs from Directory Server
Tuning scripts can tune the Distributed Authentication UI server web container
Patch 5 allows you to specify passwords for the tuning scripts in a text file. Previously, you could enter passwords only as a command-line argument, which could cause security issues. To use a password file, set the following variables, as needed, in the file:
DS_ADMIN_PASSWORD=DirectoryServer-admin-password AS_ADMIN_PASSWORD=ApplicationServer8-admin-password
For example, to tune Application Server 8:
# ./amtune-as8 password-file
where password-file contains AS_ADMIN_PASSWORD set to the Application Server 8 administrator password.
The tuning scripts use the -j password-file option when they call the ldapmodify, ldapsearch, db2index, and dsconf Directory Server utilities.
If Access Manager 7 2005Q4 is installed in Realm Mode, delegation privileges are used to determine access permissions, and therefore some Directory Server ACIs are not needed. Access Manager 7 2005Q4 patch 5 allows you to remove the unnecessary ACIs by running the amtune-prepareDSTuner script. This script reads a list of ACIs from the remacis.ldif file and then calls the ldapmodify utility to remove them.
You can run the amtune-prepareDSTuner script to remove the unnecessary ACIs on Solaris, Linux, HP-UX, and Windows systems. For more information, including how to run the script, see Technical Note: Sun Java System Access Manager ACI Guide.
After you deploy the Distributed Authentication UI server on a web container, you can tune the web container by running the Access Manager tuning scripts. The following tuning scripts set the JVM and other tuning options for the respective web container:
Table 2 Access Manager Web Container Tuning Scripts
Web Container |
Tuning Script |
---|---|
amtune-ws61 |
Web Server 6.1 |
amtune-as7 |
Application Server 7 |
amtune-as8 |
Application Server Enterprise Edition 8.1 |
To tune a web container for a Distributed Authentication UI server:
Because Access Manager server is not installed on the system where the Distributed Authentication UI server is deployed, copy the appropriate web container tuning script (shown in the previous table), amtune-env configuration file, and amtune-utils script from an Access Manager server installation. If you want to tune the Solaris or Linux operating system, copy the amtune-os script too.
Edit the parameters in the amtune-env configuration file to specify the web container and tuning options. To run the script in REVIEW mode, set AMTUNE_MODE=REVIEW in the amtune-env file.
Run the web container tuning script in REVIEW mode. In REVIEW mode, the script suggests tuning changes based on values in the amtune-env file but does not make any actual changes to the deployment.
Review the tuning recommendations in the debug log file. If needed, make changes to the amtune-env file based on this run.
To make tuning changes, set AMTUNE_MODE=CHANGE in the amtune-env file.
Run the tuning script in CHANGE mode to make the tuning changes to the deployment.
For more information about running the tuning script to tune an Access Manager web container, see Chapter 2, Access Manager Tuning Scripts, in Sun Java System Access Manager 7 2005Q4 Performance Tuning Guide.
Patch 5 includes a single amtune-os script to tune both the Solaris OS and Linux OS. The script determines the OS type from the uname -s command. Previously, Access Manager provided separate amtune-os scripts to tune each OS.
If Access Manager is installed in a Solaris 10 local zone, all tuning scripts except amtune-os can run in the local zone. In a local zone, the amtune-os script displays a warning message but does not tune the OS. The script then continues running any other tuning scripts that you have requested. Previously, in a local zone, the amtune-os script would abort, and any subsequent tuning scripts that you requested would not run.
In a Solaris 10 global zone, the amtune script invokes amtune-os to tune the OS as well as any other scripts that you have requested to run.
Patch 5 includes tuning scripts for Windows systems. Running the tuning scripts on a Windows system is similar to running the scripts on a Solaris system or Linux system, with these differences:
Windows scripts are written in Perl and require Active Perl 5.8 to run.
If you are tuning Directory Server, after running amtune-prepareDSTuner.pl script, you must copy the amtune-utils.pl, amtune-directory.pl, remacis.ldif, and amtune-samplepassordfile files to the Directory Server system, because the script cannot compress these files.
A script to tune the Windows operating system is not available.
Support for zones is not provided.
Before running a script, you must set the $BASEDIR parameter to the Access Manager installation directory in the amtune-env.pl file.
If Access Manager is installed on a Sun Fire T1000 or T2000 server, the Patch 5 tuning scripts for Web Server 6.1 and Application Server 8 set the JVM GC ParallelGCThreads parameter to 8:
-XX:ParallelGCThreads=8
This parameter reduces the number of garbage collection threads, which could be unnecessarily high on a 32–thread capable system. However, you can increase the value to 16 or even 20 for a 32 virtual CPU machine such as a Sun Fire T1000 or T2000 server, if it minimizes full garbage collection activities.
Also, for Solaris SPARC systems with a CMT processor with CoolThreads technology, in the /etc/opt/SUNWam/config/AMConfig.properties file, it is recommended that you add the following property at the end of the file:
com.sun.am.concurrencyRate=value
The default value is 16, but you can set this property to a lower value, depending on the number of cores in the Sun Fire T1000 or T2000 server.
To enable Basic Authentication in the Microsoft Internet Information Services (IIS) 6.0, the policy agent must obtain the user's name and password. Patch 5 includes the following new classes to enable this functionality using DES encryption of the user's password:
DESGenKey.java generates a unique key used to encrypt and decrypt the user's password.
ReplayPasswd.java reads the encryption key value from the com.sun.am.replaypasswd.key property in the AMConfig.properties file, encrypts the password, and assigns it to the sunIdentityUserPassword session property.
To use the Basic Authentication in IIS 6.0, you must perform steps on both the Access Manager server side and the IIS 6.0 policy agent side.
On the Access Manager server side:
Execute DESGenKey.java to generate a unique encryption key for password encryption and decryption. On Solaris systems, the DESGenKey.java file is located under the com/sun/identity/common directory, included in am_sdk.jar in the /opt/SUNWam/lib directory. For example, the following command generates an encryption key:
# cd /opt/SUNWam/lib # java -cp am_sdk.jar com.sun.identity.common.DESGenKey
Assign the encryption key value from Step 1 to the com.sun.am.replaypasswd.key property in the AMConfig.properties file.
Deploy ReplayPasswd.java as a post authentication plug-in. Use the complete class name when you configure the plug-in: com.sun.identity.authentication.spi.ReplayPasswd.
On the IIS 6.0 policy agent side:
Assign the encryption key value from the server side to the com.sun.am.replaypasswd.key property in the AMAgent.properties file. Both the Access Manager server and the IIS 6.0 policy agent must use the same encryption key.
Enable Basic Authentication in IIS 6.0 Manager.
The IIS 6.0 policy agent reads the encrypted password from the session response, decrypts the password from the com.sun.am.replaypasswd.key property, and sets the authentication headers, to allow the Basic Authentication to work.
For information about the IIS 6.0 policy agent, see the Sun Java System Access Manager Policy Agent 2.2 Guide for Microsoft Internet Information Services 6.0.
When a user's account is locked, Access Manager 7 2005Q4 patch 5 on HP-UX systems reports errorCode = null instead of errorCode = 107 if the password retry count is exceeded.
Workaround. None.
Before you run the amtune-identity tuning script, it is recommended that you add the following property set to false to the AMConfig.properties file:
com.sun.identity.log.resolveHostName=false
A value of false minimizes the impact of resolving host names and thus can improve performance. However, if you want the client machine's hostname to be printed in the amAuthentication.access log, set the value to true.
If you remove patch 5 from an Access Manager full server installation, the amAuthLDAP.xml and amPolicyConfig.xml files contain the amldapuser password in clear text. These files are in the following directory, depending on your platform:
Solaris systems: /etc/opt/SUNWam/config/xml
Linux and HP-UX systems: /etc/opt/sun/identity/config/xml
Workaround: Edit the amAuthLDAP.xml and amPolicyConfig.xml files and delete the clear text password.
In Access Manager 7 2005Q4 patches, the Access Manager configuration script for BEA WebLogic Server (amwl81config) adds the JAX-RPC 1.1 JAR files to the classpath for the WebLogic instance. While this modification is beneficial to products such as Sun Java System Portal Server, a full server installation (DEPLOY_LEVEL=1) deployed on WebLogic Server cannot communicate with a client SDK installation, and exceptions will subsequently occur.
If Access Manager 7 2005Q4 server is installed on BEA WebLogic Server, the CLASSPATH in the startWebLogic.sh script must be set to the location of the JAX-RPC 1.0 JAR files to communicate with Access Manager client SDK.
Workaround: Before applying the Access Manager patch, set the CLASSPATH in the startWebLogic.sh script for the WebLogic Server instance to use the JAX-RPC 1.0 JAR files instead of the JAX-RPC 1.1 JAR files:
On the Access Manager server, login as or become superuser (root).
Edit the startWebLogic.sh script and replace the CLASSPATH to use the JAX-RPC 1.0 JAR files. For example:
Current value:
CLASSPATH=/etc/opt/SUNWam/config: AccessManager-base/AccessManager-package-dir/lib/jax-qname.jar: AccessManager-base/AccessManager-package-dir/lib/namespace.jar: AccessManager-base/AccessManager-package-dir/lib/jaxrpc-api.jar: AccessManager-base/AccessManager-package-dir/lib/jaxrpc-spi.jar: AccessManager-base/AccessManager-package-dir/lib/jaxrpc-impl.jar:
New value:
CLASSPATH=/etc/opt/SUNWam/config: AccessManager-base/AccessManager-package-dir/lib/jax-qname.jar: AccessManager-base/AccessManager-package-dir/lib/namespace.jar: AccessManager-base/AccessManager-package-dir/lib/jaxrpc_1.0/jaxrpc-api.jar: AccessManager-base/AccessManager-package-dir/lib/jaxrpc-ri.jar:
where AccessManager-base is the base installation directory. The default value is /opt on Solaris systems and /opt/sun on Linux and HP-UX systems. AccessManager-package-dir is the Access Manager package directory.
5. Restart the WebLogic Server instance.
On Linux systems. the postpatch script creates the /opt/sun/identity/amsilent file with permissions of 644, which allows read access by all users.
Workaround: After executing the installpatch script, change the permissions on the amsilent file to allow read and write access only to the owner. For example:
# chmod 600 /opt/sun/identity/amsilent
In this deployment scenario, two Access Manager instances are deployed on the same host server, with each instance on a different web container instance. You then follow these steps:
Apply patch 5.
Modify the amsilent file and redeploy the first Access Manager instance.
Modify the amsilent again for the second Access Manager instance, and then redeploy that instance.
If NEW_INSTANCE=false in the amsilent file, the serverconfig.xml file for the first Access Manager instance is overwritten with information from the second Access Manager instance. A subsequent restart of the first Access Manager instance fails. The serverconfig.xml file is in the following directory depending on your platform:
Solaris systems: /etc/opt/SUNWam/config
Linux systems: /etc/opt/sun/identity/config
Workaround: When you deploy the second Access Manager, set NEW_INSTANCE=true in the amsilent file. The serverconfig.xml file for the second Access Manager instance is then updated with the correct information, and the serverconfig.xml file for the first Access Manager instance is not overwritten.
Applying patch 5 to an SDK-only machine overwrites the samples makefiles.
Workaround: Applying patch 5 to an SDK-only machine does not require a reconfiguration; however, if you want to use the samples makefiles, follow these steps to update the LDIF and properties files (that is, perform tag swapping) for the samples makefiles:
Run the amconfig script with DEPLOY_LEVEL=14 to uninstall the SDK and unconfigure the web container.
Run the amconfig script with DEPLOY_LEVEL=4 to re-install the SDK and reconfigure the web container.
For most searches, this problem has been fixed. However, be careful when setting the Alias Search Attribute. The value of the alias search attributes must be unique across an organization. If more than one alias search attribute is set, it is possible that one entry in the data store matches one attribute, and another entry matches with the other attribute. In this situation, Access Manager server throws the following error:
An internal authentication error has occurred. Contact your system administrator.
Workaround: None
A Distributed Authentication UI server and a J2EE policy agent do not work if they are installed in the same web container.
Workaround: Create a second web container instance and deploy the Distributed Authentication UI server and J2EE policy agent on different instances of the container.
If you deploy Access Manager on Sun Java System Application Server on a Windows system, clicking Help in the left panel of the help screen for the Realm Mode console returns an application error.
Workaround: Copy the javaes-install-dir\share\lib\jhall.jar file to the JAVA_HOME\jre\lib\ext directory and then restart Application Server.
If an explicit goto URL parameter is not specified, a Distributed Authentication UI server attempts to redirect to the goto on a success URL specified in Access Manager. This redirect can fail for these reasons:
The URL is relative, and no corresponding page is available at the Distributed Authentication UI server
The URL is absolute, and the browser cannot reach the URL.
Workaround: Always specify an explicit goto URL parameter for a Distributed Authentication UI server.
Access Manager 7 2005Q4 was released with LDAP JDK 4.18 as part of the Java ES 2005Q4 release, which resulted in a number of Access Manager and Directory Server connection problems.
Workaround: Apply one of the following Sun Java System LDAP Java Development Kit patches:
Solaris OS, SPARC and x86 platforms: 119725-04
Linux OS: 120834-02
The patches are available on SunSolve Online: http://sunsolve.sun.com.
On Solaris systems, the Java ES installer installs the Distributed Authentication UI server Makefile.distAuthUI, README.distAuthUI, and amauthdistui.war files in an incorrect location: /opt/SUNComm/SUNWam.
Workaround: Copy these files to their correct location: /opt/SUNWam.
Note: Any Distributed Authentication UI server problems fixed in a patch will go into the /opt/SUNComm/SUNWam/amauthdistui.war file, so whenever you apply a patch to the Access Manager server and then rebuild and deploy the WAR file, you must also copy these files to the /opt/SUNWam directory.
If Access Manager is installed in a locale that uses multibyte characters (such as Japanese) on a Windows or HP-UX system, a search in the console online help with keywords entered using multibyte characters does not work.
Workaround: None
Patch 6 update: Access Manager 7 2005Q4 patch 6 fixes this problem on Windows systems. However, the problem still exists on HP-UX systems.
If Access Manager is installed in a locale that uses multibyte characters (such as Japanese or Chinese) on a Windows system, during Access Manager configuration, words are garbled in output messages at the terminal window.
Workaround: None, but this problem does not affect the configuration itself.
If you install patch 5 (124296-05) in a non-English locale on a Windows system, some strings in the install panels appear as property keys instead of the actual message text. Examples of property keys are PRODUCT_NAME, JES_Patch_FinishPanel_Text1, and JES_Patch_FinishPanel_Text2.
Workaround: None
The Access Manager amtune script sets the com.iplanet.am.session.purgedelay property to 1, in order to allow as many Access Manager sessions as possible. This property specifies the number of minutes to delay the purge session operation. For clients such as Sun Java System Portal Server, however, a value of 1 might not be sufficient.
Workaround: Reset the com.iplanet.am.session.purgedelay property after you run the amtune script:
In the AMConfig.properties file, set the property to the new value. For example:
com.iplanet.am.session.purgedelay=5
Restart the Access Manager web container for the new value to take effect.