test

Sun Java System Access Manager 7.1 Postinstallation Guide

Appendix A Directory Server Considerations

Access Manager 7.1 requires a Directory Server to store user information and Access Manager configuration data. Considerations include these topics:

Configuring a Directory Server That is Not Provisioned With User Data

In this deployment scenario, you installed Access Manager by running the Java ES installer and your Directory Server is not yet provisioned with user data. In this deployment scenario, you must configure Directory Server as follows:

You can now provision users in Directory Server for the deployment.

To perform these tasks, use either the Directory Server 6.0 Directory Service Control Center (DSCC) or the ldapmodify utility. For more information, see the Sun Java System Directory Server Enterprise Edition 6.0 Administration Guide.

Configuring a Directory Server That is Provisioned With User Data

In this deployment scenario, Sun Java System Directory Server is installed with an existing directory information tree (DIT), but the schema does not include the Sun organization and user naming attributes (that is, the sunISManagedOrganization object class is not in the root suffix).

You installed Access Manager 7.1 on a host server using either of these methods:

In this deployment scenario, you must load the following Access Manager LDIF files into Directory Server:

LDIF File 

Description 

sunone_schema2.ldif and ds_remote_schema.ldif

Access Manager schema changes 

sunAMClient_schema.ldif and sunAMClient_data.ldif

Access Manager client data and schema changes 

installExisting.ldif

Access Manager entries 

The Access Manager LDIF files are located in the following directory, depending on your platform:

ProcedureTo Configure the Directory Server Schema For Access Manager

Before You Begin

To modify the Directory Server schema, you must have the appropriate Directory Server administrator privileges and know the administrator password.

To load the LDIF files, use either the Directory Service Control Center (DSCC) or the ldapmodify utility. For information about these options, see Deciding When to Use DSCC and When to Use the Command Line in Sun Java System Directory Server Enterprise Edition 6.0 Administration Guide.

  1. Load the sunone_schema2.ldif and ds_remote_schema.ldif files for the Access Manager schema changes.

  2. Load the sunAMClient_schema.ldif and sunAMClient_data.ldif files for the Access Manager client data and schema changes.

  3. In the installExisting.ldif file, edit the passwords (userPassword entry) for the following users:

    • puser

    • dsameuser

    • amldapuser

    • amAdmin

    Note: The passwords for puser, dsameuser, and amAdmin and can be the same value, but the password for amldapuser must be a different value.

  4. Load the installExisting.ldif file.

  5. Add the Directory Server indexes and enable the referential integrity plug-in, as described in the following sections:

  6. Load the Access Manager services using the amserveradmin script:

    1. Change to the directory where the amserveradmin script is located:

      • Solaris systems: /etc/opt/SUNWam/config/ums

      • Linux systems: /etc/opt/sun/identity/config/ums

    2. Check the umsExisting.xml file and make any changes to the naming attribute values as required for your Directory Server implementation.

    3. Edit the amserveradmin script and replace ums.xml with umsExisting.xml.

    4. Run the amserveradmin script. For example:

      # ./amserveradmin "cn=amadmin,ou=people,dc=example,dc=com" "amadmin_password"

  7. Restart the Access Manager web container.

    You should now be able to login to the Access Manager Admin Console.

Indexing Access Manager Attributes in Directory Server

Directory Server indexes improve the performance of searches of Directory Server data. The following table lists the recommended attributes that you should consider indexing for Access Manager (if they are not already indexed).

Table A–1 Recommended Access Manager Attributes to Index in Directory Server

Attribute 

Index Type 

nsroledn

Equality, Presence, and Substring 

memberof

Equality and Presence 

iplanet-am-static-group-dn

Equality 

iplanet-am-modifiable-by

Equality 

iplanet-am-user-federation-info-key

Equality 

sunxmlkeyvalue

Equality and Substring 

o

Equality, Presence, and Substring 

ou

Equality, Presence, and Substring 

sunPreferredDomain

Equality, Presence, and Substring 

associatedDomain

Equality, Presence, and Substring 

sunOrganizationAlias

Equality, Presence, and Substring 

ProcedureTo Add Indexes to Directory Server

  1. Make sure that Directory Server is configured and running.

  2. Add indexes using either the Directory Server Console or the ldapmodify command-line utility.

    See Table A–1 for a list of the recommended Access Manager attributes to index.

    If you use the ldapmodify utility, load the Access Manager index.ldif file, which is available in the following directory, depending on your platform:

    • Solaris systems: /etc/opt/SUNWam/config/ldif

    • Linux and HP-UX systems: /etc/opt/sun/identity/config/ldif

    • Windows systems:javaes-install-dir\identity\config\ldif

      javaes-install-dir represents the Java ES 5 installation directory. The default value is C:\Program Files\Sun\JavaES5.

  3. Restart Directory Server.

Enabling the Directory Server Referential Integrity Plug-in

When enabled, the Directory Server Referential Integrity plug-in performs integrity updates on specified attributes immediately after a delete or rename operation. This process ensures that relationships between related entries are maintained throughout the database. If the Referential Integrity plug-in is not already enabled, perform the following procedure.

ProcedureTo Enable the Referential Integrity Plug-in

  1. Make sure that Directory Server is configured and running.

  2. Enable the Referential Integrity plug-in using either the Directory Server Console or the ldapmodify command-line utility.

    If you use the ldapmodify utility, load the Access Manager plugin.ldif file, which is available in the following directory, depending on your platform:

    • Solaris systems: /etc/opt/SUNWam/config/ldif

    • Linux and HP-UX systems: /etc/opt/sun/identity/config/ldif

    • Windows systems:javaes-install-dir\identity\config\ldif

      javaes-install-dir represents the Java ES 5 installation directory. The default value is C:\Program Files\Sun\JavaES5.

  3. Restart Directory Server to enable the plug-in.

Disabling Persistent Searches in Directory Server

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:

Persistent searches can cause performance overhead on Directory Server. If you determine that improving performance is critical in a production environment, disable persistent searches using the com.sun.am.event.connection.disable.list property.

Caution – Caution –

Do not disable persistent searches unless the performance improvement is required for your deployment. The com.sun.am.event.connection.disable.list property was introduced primarily to avoid overhead on Directory Server when multiple version 2.1 J2EE agents are used, because each of these agents establishes these persistent searches. The version 2.2 J2EE agents no longer establish these persistent searches.

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.

Or, 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, you can disable the persistent search to the Service Management (sm) component. However, if any changes do occur for any of the services, a server restart would be required. The same condition also applies to other persistent searches, as specified by the aci and um values.

ProcedureTo Disable Persistent Searches

  1. Set the com.sun.am.event.connection.disable.list property in the AMConfig.properties file to one or more of the following values, previously described in this section: aci, sm, um.

    Values are case insensitive. To specify multiple values, separate each value with a comma. For example:

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

  2. Restart the Access Manager web container for the new property value to take effect.

Enabling a Persistent Search

If you later want to enable a persistent search that you have disabled, set the property to a blank value for the specific search. For the previous example, to enable the search for Access Manager information tree (service management node) changes but leave the search disabled for user directory (user management node) changes, set the property as follows:

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

Configuring a User Directory on a Directory Server Instance Different From the Access Manager Information Tree Node

In this deployment scenario, the Access Manager information tree is in one Sun Java System Directory Server instance, but the user directory node is in a different Directory Server instance. You want Access Manager to write to user profiles in the user directory node in order to support features such as account locking or account lockout.

In this scenario, the user directory node requires the schema that is installed into the Directory Server instance that contains the Access Manager information tree. Therefore, you must update the schema manually by loading the following two files, in order, into the Directory Server instance that contains the user directory node:

These files are available in the following directory, depending on your platform:

If you are using a directory other than Sun Java System Directory Server to store your users (for example, Microsoft® Active Directory), you must add specific object classes and attributes to that directory schema. For a list of these object classes and attributes, see Appendix B, Access Manager User LDAP Entries.

Configuring Different Root Suffixes for the Access Manager Information Tree and User Directory Nodes

In Sun Java System Directory Server, you can separate Access Manager configuration data in the Access Manager information tree (or service management node) from the user data in the user directory (or user management node) by specifying a different root suffix for each node.

This scenario applies to deployments that want to separate the Access Manager configuration data from user data but do not support an LDAPv3 data repository. For example, deployments with Sun Java System Communications Suite products use the Access Manager SDK (AMSDK) to access user data.

If you deploying this scenario and are using the AMSDK to access user data in a Realm Mode deployment, a corresponding organization or sub-organization must exist for each realm or sub-realm. To have Access Manager create an organization or sub-organization for each realm or sub-realm, enable the Copy Realm Configuration attribute (sun-idrepo-amSDK-config-copyconfig-enabled) in the Access Manager Console for the default (top-level realm).

The following figure shows the directory structure for this scenario.

Figure A–1 Access Manager Information Tree and User Directory Nodes

This figure shows different root suffixes for the Access Manager information tree and user data in the user directory node.

ProcedureTo Configure Different Root Suffixes for the Access Manager Information Tree and User Directory Nodes

To configure Access Manager with different suffixes for the Access Manager Information Tree (service management node) and user directory node, first install Access Manager by running the Java ES installer with the Configure Later option. Then, configure Access Manager by running the amconfig script with configuration values specified in the amsamplesilent file (or a copy of the file).

Important: Before you configure the two suffixes in the procedure below:

  1. Log in as or become superuser (root).

  2. Install Access Manager by running the Java ES installer with the Configure Later option.

  3. In the amsamplesilent file (or copy of the file), set the root suffixes as follows:

    • Set the SM_CONFIG_BASEDN variable to the root suffix of the Access Manager information tree node (service management node).

      Note: The value indicated by SM_CONFIG_BASEDN must already exist in the directory, created using Directory Server tools.

    • Set the ROOT_SUFFIX variable to the initial or root suffix of Directory Server.

  4. Set the CONFIG_* variables as follows:

    • Set CONFIG_AD to false (the default), since Sun Java System Directory Server is the configuration data store. The Directory Server schema will be loaded.

    • Set CONFIG_SERVER to the fully qualified domain name of the Directory Server host where the Access Manager Information Tree (service management data) is stored. The suffix on this host is indicated by the SM_CONFIG_BASEDN variable. The default is the value of DS_HOST.

    • Set CONFIG_PORT to the port for the Directory Server indicated by the CONFIG_SERVER variable. The default is the value of DS_PORT.

    • Set CONFIG_ADMINDN to the DN that is used to connect to the directory indicated by the CONFIG_SERVER variable. The default is "cn=dsameuser,ou=DSAME Users".

    • Set CONFIG_ADMINPASSWD to the password for CONFIG_ADMINDN. The default is the value of the ADMINPASSWD variable.

  5. Set any other variables in the amsamplesilent file (or copy of the file) as required for your deployment.

  6. Run the amconfig script with the edited amsamplesilent file (or copy of the file).

    For example, on a Solaris system with Access Manager installed in the default directory:

    # cd /opt/SUNWam/bin
# ./amconfig ./amsamplesilent

  7. Restart the Access Manager web container.

Configuring Access Manager With Directory Server in MMR Mode

This deployment scenario includes the following components:

Depending on whether you installed Access Manager in Realm Mode or Legacy Mode, perform the following configuration steps for each Access Manager instance:

ProcedureTo Configure Each Access Manager Instance in Realm Mode

Before You Begin

Start the Directory Server instance (ds1.example.com) on the first machine only. Add the Access Manager indexes to the first Directory Server instance, as described in Indexing Access Manager Attributes in Directory Server.

  1. Log in as or become superuser (root) on the server where Access Manager is installed.

  2. Backup the serverconfig.xml file.

    The serverconfig.xml file is in the following directory, depending on your platform:

    • Solaris systems: /etc/opt/SUNWam/config

    • Linux and HP-UX systems: /etc/opt/sun/identity/config

    • Windows systems: C:\Program Files\Sun\JavaES5\identity\config

  3. In the serverconfig.xml file, add the secondary Directory Server instance. For example:

    ...
<iPlanetDataAccessLayer>
    <ServerGroup name="default" minConnPool="1" maxConnPool="10">
            <Server name="Server1" host=" ds1.example.com" port="389" type="SIMPLE" />
            <Server name="Server2" host=" ds2.example.com" port="389" type="SIMPLE" />
...

  4. Login to the Access Manager Realm Mode Console as amadmin.

  5. Click Access Control > Realm Name realm-name General .

    1. Add both Access Manager instances to the Realm/DNS Aliases list. For example:


      amserver1.example.com
amserver2.example.com

    2. Save the changes.

  6. Click Access Control > Realm Name realm-name > Authentication Module Instances – LDAP .

    1. Add the secondary Directory Server instance to Secondary LDAP Server. For example: ds2.example.com:389

    2. Save the change.

  7. After you have performed the changes on both Access Manager instances, restart the Access Manager web container on both host servers.

  8. On the secondary Directory Server instance, add the Access Manager indexes as follows:

    1. Start the secondary Directory Server instance.

    2. Add the Access Manager indexes using either the Directory Server 6.0 Directory Service Control Center (DSCC) or the ldapmodify utility.

      For information about adding indexes, see Indexing Access Manager Attributes in Directory Server.

    3. Restart the secondary Directory Server instance.

ProcedureTo Configure Each Access Manager Instance in Legacy Mode

Before You Begin

Start the Directory Server instance (ds1.example.com) on the first machine only. Add the Access Manager indexes to the first Directory Server instance, as described in Indexing Access Manager Attributes in Directory Server.

  1. Log in as or become superuser (root) on the server where Access Manager is installed.

  2. Backup the serverconfig.xml file.

    The serverconfig.xml file is in the following directory, depending on your platform:

    • Solaris systems: /etc/opt/SUNWam/config

    • Linux and HP-UX systems: /etc/opt/sun/identity/config

    • Windows systems: C:\Program Files\Sun\JavaES5\identity\config

  3. In the serverconfig.xml file, add the secondary Directory Server instance. For example:

    ...
<iPlanetDataAccessLayer>
    <ServerGroup name="default" minConnPool="1" maxConnPool="10">
            <Server name="Server1" host=" ds1.example.com" port="389" type="SIMPLE" />
            <Server name="Server2" host=" ds2.example.com" port="389" type="SIMPLE" />
...

  4. Login to the Access Manager Legacy Mode Console as amadmin.

  5. Click Directory Management > Organizations organization-name.

    1. Make sure that Organization Aliases includes both Access Manager instances. Add the instances, if necessary. For example:


      amserver1.example.com
amserver2.example.com

    2. Add both Access Manager instances to the DNS Aliases Names list.

    3. Save the changes.

  6. Click Configuration > Authentication Service Name – LDAP.

    1. Add the secondary Directory Server instance to Secondary LDAP Server. For example: ds2.example.com:389

    2. Save the change.

  7. After you have performed the changes on both Access Manager instances, restart the Access Manager web container on both host servers.

  8. On the secondary Directory Server instance, add the Access Manager indexes as follows:

    1. Start the secondary Directory Server instance.

    2. Add the Access Manager indexes using either the Directory Server 6.0 Directory Service Control Center (DSCC) or the ldapmodify utility.

      For information about adding indexes, see Indexing Access Manager Attributes in Directory Server.

    3. Restart the secondary Directory Server instance.

Specifying a User Naming Attribute Other Than the User ID (uid)

If you are using the Access Manager SDK to create users, you might want to specify an attribute other than the default user ID (uid) as the naming attribute. For example, you might want to use the user's email (mail) or common name (cn) attribute. Or, you might want to use a different attribute altogether, such as an application generated user ID. This section describes these topics:

Changing the Naming Attribute Before Running the amconfig Script

In this scenario, you install Access Manager with the Java ES installer Configure Later option and then run the amconfig script to set the user naming attribute (as well as other attributes). You want to change the user naming attribute before you run the amconfig script.

Procedure To Specify a User Naming Attribute Other Than the User ID (uid)

  1. In the amsamplesilent file (or copy of the file), set the USER_NAMING_ATTR variable to the new attribute you want to use.

    For example, for the mail attribute: USER_NAMING_ATTR=mail

    Specify a valid naming attribute supported by Directory Server and in the default Access Manager supported naming attribute list. Or, if the naming attribute you want to use is not in the list of Access Manager supported attributes, add the attribute to the ums.xml and amUser.xml files, as described in the following steps.

  2. In the ums.xml file, add the attribute to the list in the CreationTemplate for the BasicUser. For example, to use the mail attribute:

    <SubConfiguration name="CreationTemplates" >
                    <SubConfiguration name="BasicUser" id="CreationUmsObjects">
                        <AttributeValuePair> <Attribute name="name" />
                            <Value>BasicUser</Value>
                        </AttributeValuePair>
                        <AttributeValuePair> <Attribute name="javaclass" />
                            <Value>com.iplanet.ums.User</Value>
                        </AttributeValuePair>
                        <AttributeValuePair> <Attribute name="required" />
                            <Value>objectClass=top</Value>
                            <Value>objectClass=person</Value>
                            <Value>objectClass=organizationalPerson</Value>
                            <Value>objectClass=inetOrgPerson</Value>
                            <Value>objectClass=iPlanetPreferences</Value>
                            <Value>objectClass=iplanet-am-user-service</Value>
                            <Value>objectClass=inetuser</Value>
                            <Value>objectClass=inetAdmin</Value>
                            <Value>objectClass=iplanet-am-managed-person</Value>
                            <Value>objectClass=sunAMAuthAccountLockout</Value>
                            <Value>cn=default</Value>
                            <Value>sn=default</Value>
                            <Value>uid</Value>
                            <Value>inetuserstatus=Active</Value>
                            <Value>mail</Value>
                        </AttributeValuePair>
                        <AttributeValuePair> <Attribute name="optional" />
                            <Value>*</Value>
                        </AttributeValuePair>
                        <AttributeValuePair> <Attribute name="namingattribute" />
                            <Value>uid</Value>
                        </AttributeValuePair>
                    </SubConfiguration>

  3. Also in the ums.xml file, add the attribute to the BasicUserSearch template.

  4. In the amUser.xml file, add the attribute (such as mail) to the <User> schema (if it is not already in the schema).

  5. Run the amconfig script with the amsamplesilent file (or copy of the file) from Step 1.

Changing the Naming Attribute After Installation

In this scenario, you have installed and configured Access Manager and you want to change the user naming attribute. You must modify the ums.xml file and then reload the DAI service using the amadmin utility.

ProcedureTo Change the Naming Attribute After Installation

  1. In the ums.xml file (used for the DAI service), add the attribute to the list in the CreationTemplate for the BasicUser. For example, to use the mail attribute:

    <SubConfiguration name="CreationTemplates" >
                    <SubConfiguration name="BasicUser" id="CreationUmsObjects">
                        <AttributeValuePair> <Attribute name="name" />
                            <Value>BasicUser</Value>
                        </AttributeValuePair>
                        <AttributeValuePair> <Attribute name="javaclass" />
                            <Value>com.iplanet.ums.User</Value>
                        </AttributeValuePair>
                        <AttributeValuePair> <Attribute name="required" />
                            <Value>objectClass=top</Value>
                            <Value>objectClass=person</Value>
                            <Value>objectClass=organizationalPerson</Value>
                            <Value>objectClass=inetOrgPerson</Value>
                            <Value>objectClass=iPlanetPreferences</Value>
                            <Value>objectClass=iplanet-am-user-service</Value>
                            <Value>objectClass=inetuser</Value>
                            <Value>objectClass=inetAdmin</Value>
                            <Value>objectClass=iplanet-am-managed-person</Value>
                            <Value>objectClass=sunAMAuthAccountLockout</Value>
                            <Value>cn=default</Value>
                            <Value>sn=default</Value>
                            <Value>uid</Value>
                            <Value>inetuserstatus=Active</Value>
                            <Value>mail</Value>
                        </AttributeValuePair>
                        <AttributeValuePair> <Attribute name="optional" />
                            <Value>*</Value>
                        </AttributeValuePair>
                        <AttributeValuePair> <Attribute name="namingattribute" />
                            <Value>uid</Value>
                        </AttributeValuePair>
                    </SubConfiguration>

  2. Delete the DAI service using the amadmin command. For example, on Solaris systems:

    # # cd /opt/SUNWam/bin
# ./amadmin -u amadmin -w amadminpassword -r DAI

  3. Reload the DAI service, again using the amadmin command. For example:

    # ./amadmin -u amadmin -w amadminpassword
-s /etc/opt/SUNWam/config/xml/ums.xml

  4. Restart the Access Manager web container.