Documentation Issues (Sun Java System Access Manager 7 2005Q4 Release Notes)

Sun Java System Access Manager 7 2005Q4 Release Notes

Documentation Issues

Document that Access Manager cannot revert from Realm Mode to Legacy Mode (6508473)

If you install Access Manager 7 2005Q4 in Realm Mode, you cannot revert to Legacy Mode.

If you install Access Manager 7 2005Q4 in Legacy Mode, however, you can change to Realm Mode by using the amadmin command with the -M option. For example:

amadmin -u cn=amAdmin,ou=People,dc=example,dc=com -w amadmin-password -M dc=example,dc=com

Document more information about disabling persistent searches (6486927)

Access Manager uses persistent searches to receive information about Sun Java System Directory Server entries that change. By default, Access Manager creates the following persistent search connections during server startup:

aci - Changes to the aci attribute, with the search using the LDAP filter (aci=*)

sm - Changes in the Access Manager information tree (or service management node), which includes objects with the sunService or sunServiceComponent marker object class. For example, you might create a policy to define access privileges for a protected resource, or you might modify the rules, subjects, conditions, or response providers for an existing policy.

um - Changes in the user directory (or user management node). For example, you might change a user's name or address.

Caution –

Disabling persistent searches for any of these components is not recommended, because a component with a disabled persistent search does not receive notifications from Directory Server. Consequently, changes made in Directory Server for that particular component will not be notified to the component cache, and the component cache will go stale.

For example, if you disable persistent searches for changes in the user directory (um), the Access Manager server will not receive notifications from Directory Server. Therefore, an agent would not get notifications from Access Manager to update its local user cache with the new values for the user attribute. Then, if an application queries the agent for the user attributes, it might receive the old value for that attribute.

Use this property only in special circumstances when absolutely required. For example, if you know that Service Configuration changes (related to changing values to any of services such as Session Service and Authentication Services) will not happen in production environment, the persistent search to the Service Management (sm) component can be disabled. However, if any changes occur for any of the services, a server restart would be required. The same condition also applies to other persistent searches, specified by the aci and um values.

For more information, see CR# 6363157: New property disables persistent searches if absolutely required.

Document Access Manager supported and unsupported privileges (2143066)

Privileges define the access permissions to administrators who are members of roles or groups that exist within a realm. Access Manager allows you to configure permissions for the following administrator types:

Realm administrators can perform all realm-related tasks, including defining identity repositories (data stores), configuring authentication, and defining policies.
Policy administrators can configure policies in existing realms.

The following privileges are supported:

Read and write access to all realm and policy properties. Defines read and write access privileges for realm administrators.
Read and write access for only policy properties. Defines read and write access privileges for policy administrators.
Combination of supported privileges: Read and write access only for policy properties and read only access to data stores. Other combinations of privileges are not supported.

Document cookie-based sticky request routing (6476922)

When Access Manager servers are deployed behind a load balancer, cookie-based sticky request routing prevents a client request from being misrouted to an incorrect Access Manager server (that is, to a server that is not hosting the session). This feature was implemented in Access Manager 7 2005Q4 patch 3.

In the previous behavior, without cookie-based sticky request routing, requests from non-browser based clients (such as policy agents and clients using the remote Access Manager client SDK) were often misrouted to an Access Manager server that was not hosting the session. Then, in order to send the request to the correct server, the Access Manager server had to validate the session using back-channel communication, which usually caused some performance degradation. Cookie-based sticky request routing prevents the need for this back-channel communication and thus improves Access Manager performance.

To implement cookie-based sticky request routing, the Access Manager deployment must be configured as a site. For information, see Configuring an Access Manager Deployment as a Site in Sun Java System Access Manager 7 2005Q4 Deployment Planning Guide.

To configure cookie-based sticky request routing:

To specify a cookie name, set the com.iplanet.am.lbcookie.name property in the AMConfig.properties file. Access Manager then generates the load balancer cookie value using the two-byte server ID (such as 01, 02, and 03). If you do not specify a cookie name, Access Manager generates the load balancer cookie value using the default name amlbcookie plus the two-byte server ID.

If you set the cookie name on the Access Manager server, you must use the same name in the AMAgent.properties file for a Policy Agent. Also, if you are using the Access Manager client SDK, you must also use the same cookie name used by the Access Manager server.

Note: Do not set the com.iplanet.am.lbcookie.value property, because Access Manager sets the cookie value using the two-byte server ID.
Configure your load balancer with the cookie name from Step 1. You can use a hardware or software load balancer with your Access Manager deployment.
If session failover is implemented, enable the com.sun.identity.session.resetLBCookie property for both Policy Agents and the Access Manager server.
- For a Policy Agent, add and enable the property in the AMAgent.properties file.
- For the Access Manager server, add and enable the property in the AMConfig.properties file.
For example:

com.sun.identity.session.resetLBCookie='true'

If a failover situation occurs, the session is routed to a secondary Access Manager server, and the load balancer cookie value is set using the server ID for the secondary Access Manager server. Any subsequent requests for the session are then routed to the secondary Access Manager server.

Document Windows Desktop SSO configuration for Windows 2003 (6487361)

To configure Windows Desktop SSO on Windows 2003, as described in the Configuring Windows Desktop SSO in Sun Java System Access Manager 7 2005Q4 Administration Guide, use the following ktpass command:

ktpass /out filename /mapuser username 
/princ HTTP/hostname.domainname /crypto encryptiontype /rndpass 
/ptype principaltype /target domainname

For example:

ktpass /out demo.HTTP.keytab 
/mapuser http /princ HTTP/demo.identity.sun.com@IDENTITY.SUN.COM 
/crypto RC4-HMAC-NT /rndpass /ptype KRB5_NT_PRINCIPAL /target IDENTITY.SUN.COM

For the syntax definitions, see the following site:

http://technet.microsoft.com/en-us/library/cc779157(WS.10).aspx

Document steps to set up Distributed Authentication UI server passwords (6510859)

The following procedure describes how to set up the encrypted passwords for a Distributed Authentication UI server that communicates with an Access Manager server.

To set up the passwords for a Distributed Authentication UI server:

On the Access Manager server:
1. Encrypt the amadmin password using the ampassword -e utility. For example, on Solaris systems:
```
# cd /opt/SUNWam/bin 
# ./ampassword -e amadmin-password 
AQIC0K3omEozd544XEJIg25GT2wi1D7UAQLX 
```
  Save this encrypted value.
2. Copy and save the am.encryption.pwd property value from the Access Manager server's AMConfig.properties file. For example:
```
am.encryption.pwd=ydV8JXhJF2J35vpxjZRiGt7SH/7mUr+Y
```
On the Distributed Authentication UI server, make these changes to the AMConfig.properties file:
1. Comment out the com.iplanet.am.service.password property.
2. Set the com.iplanet.am.service.secret property to the encrypted amadmin password from Step 1a.
3. Add the am.encryption.pwd and encrypted value that you copied from Step 1b. For example:
```
com.sun.identity.agents.app.username=username 
#com.iplanet.am.service.password=password 
com.iplanet.am.service.secret=AQIC0K3omEozd544XEJIg25GT2wi1D7UAQLX 
am.encryption.pwd=ydV8JXhJF2J35vpxjZRiGt7SH/7mUr+Y
```
Restart the Distributed Authentication UI server.

Online Help for “To create a new site name” needs more information (2144543)

The Access Manager Console online Help is missing the Save step for “To create new site name” under Configuration>System Properties>Platform. If you don't click Save after adding a new site name and you then try to add an instance name, the process fails. Therefore, always click Save after adding the site name, and then add the instance name.

Document that administrator password configuration parameter is `ADMIN_PASSWD` on Windows systems (6470793)

On Solaris and Linux systems, the Access Manager administrator (amadmin) password configuration parameter in the amsamplesilent file is ADMINPASSWD. On Windows systems, however, the parameter in the AMConfigurator.properties file is ADMIN_PASSWD.

If you are running amconfig.bat on Windows systems, set the amadmin password in the AMConfigurator.properties file using the ADMIN_PASSWORD parameter and not ADMINPASSWD.

Release Notes have wrong workaround for known issue (6422907)

Step 3 of the workaround for Running the web services sample returns “Resource offering not found” (6359900) has been corrected.

Document `com.iplanet.am.session.protectedPropertiesList` in `AMConfig.properties` (6351192)

The com.iplanet.am.session.protectedPropertiesList parameter allows you to protect certain core or internal session properties from remote updates via the SetProperty method of the Session Service. By setting this “hidden” key security parameter, you can customize session attributes in order to participate in authorization as well as other Access Manager features. To use this parameter:

With a text editor, add the parameter to the AMConfig.properties file.

Set the parameter to the session properties that you want to protect. For example:

com.iplanet.am.session.protectedPropertiesList = 
PropertyName1,PropertyName2,PropertyName3

Restart the Access Manager Web container for the values to take effect.

Document the roles and filtered roles support for LDAPv3 plug-in (6365196)

After applying the respective patch, you can configure roles and filtered roles for the LDAPv3 plug-in, if the data is stored in Sun Java System Directory Server (fixes CR 6349959). In the Access Manager 7 2005Q4 Administrator Console, in LDAPv3 configuration for the “LDAPv3 Plugin Supported Types and Operations” field, enter the values as:

role: read,edit,create,delete
filteredrole: read,edit,create,delete

You can enter one or both of the above entries, depending on the roles and filtered roles you plan to use in your LDAPv3 configuration.

Document unused properties in the `AMConfig.properties` file (6344530)

The following properties in the AMConfig.properties file are not used:

com.iplanet.am.directory.host
com.iplanet.am.directory.port

`com.iplanet.am.session.client.polling.enable` on server side must not be true (6320475)

The com.iplanet.am.session.client.polling.enable property in the AMConfig.properties file must never be set to true on the server side.

Workaround: This property is set to false by default and should never be reset to true.

Default Success URL is incorrect in the console online help (6296751)

The Default Success URL is incorrect in the service.scserviceprofile.iplanetamauthservice.html online help file. The Default Success URL field accepts a list of multiple values that specify the URL where users are redirected after successful authentication. The format of this attribute is clientType|URL, although you can specify only the value of the URL, which assumes a default type of HTML.

The “/amconsole” default value is incorrect.

Workaround: The correct default value is “/amserver/console”.

Document how to enable XML encryption (6275563)

To enable XML encryption for either Access Manager or Federation Manager using the Bouncy Castle JAR file to generate a transport key, follow these steps:

If you are using a JDK version earlier than JDK 1.5, download the Bouncy Castle JCE provider from the Bouncy Castle site (http://www.bouncycastle.org/). For example, for JDK 1.4, download the bcprov-jdk14-131.jar file.
If you downloaded a JAR file in the previous step, copy the file to the jdk_root/jre/lib/ext directory.
For the domestic version of the JDK, download the JCE Unlimited Strength Jurisdiction Policy Files from the site (http://www.oracle.com/technetwork/java/index.html) for your version of the JDK. For IBM WebSphere, go to the corresponding IBM site to download the required files.
Copy the downloaded US_export_policy.jar and local_policy.jar files to the jdk_root/jre/lib/security directory.
If you are using a JDK version earlier than JDK 1.5, edit the jdk_root/jre/lib/security/java.security file and add Bouncy Castle as one of the providers. For example:
```
security.provider.6=org.bouncycastle.jce.provider.BouncyCastleProvider
```
Set the following property in the AMConfig.properties file to true:
```
com.sun.identity.jss.donotInstallAtHighestPriority=true
```
Restart the Access Manager web container.

For more information, refer to problem ID 5110285 (XML encryption requires Bouncy Castle JAR file).