Advanced Password Services (APS) Guide › User Directories: Schema, Storage and Capabilities › LDAP Directories

LDAP Directories

Note: APS does support Microsoft Active Directory and this support is provided using its LDAP interface. However, because Active Directory deviates so extensively from the LDAP specification, APS contains a significant amount of special processing and thus Active Directory is discussed in its own section.

Starting with Version 3.0, APS no longer stored its per-user information in a single LDAP attribute (the "Blob"); all information is stored in individual attributes. This section describes these attributes, the data that they are expected to contain (and the format) and how to set up your schema.

Sites converting from APS versions prior to version 3 should contact CA for a utility to convert their old style APS Blob to the new attributes.

LDAP Schema Updates for CA Directory

To extend the CA Directory schema for APS, source three files in the server-instance-name.dxg file located in the /dxserver/config/schema directory.

Follow these steps::

1. Navigate to /dxserver/config/schema.
2. Type the following commands:

   source nsroaming.dxc
   source sunone.dxc
   source CA_APS-eTrust80-user.dxc
   

LDAP Schema Updates for Other Databases

There is no "standard" way to update an LDAP schema. Each vendor implements their own way to do it. In addition, most sites have policies or requirements for how schemas are updated, naming conventions and data layout issues.

APS tries to place as few restrictions as possible for the schema that it needs. The attributes must exist for every user entry in the User Directory that will be maintained by APS, with the exception of the attributes marked as optional and suppressed in the [MAPPINGS] section of the APS Configuration File.

How sites accomplish this is entirely up to the administrators at the site. There are a number of choices available; no tools are provided to do this for you (there are some sample files provided for iPlanet LDAP directories, however). CA Professional Services has considerable experience in this area and can help or advise you, if you so desire.

There are three steps required to ensure that the attributes exist for every user:

1. The attributes must be defined as valid attributes for the directory. This can be done manually using the LDAP console or similar utility.
   • For iPlanet LDAP Server Version 4.x User Directories, the APS installation kit includes a file called smaps.user_at.conf that can be used to define these attributes. This file cannot be used directly, but can be merged with an existing schema definition to update the directory. Please refer to the iPlanet documentation for details.
   • For iPlanet LDAP Server Version 5.x User Directories, the APS installation kit includes a file called 56NetegrityAPS.ldif that can be used, with some editing, to define these attributes.
   • Other LDAP implementation will have different requirements to define these attributes and they may have to be defined manually through a vendor-supplied user interface.

   Attributes need not have the names defined above. If the attributes are to be renamed, the names must be remapped as described in the [MAPPINGS] section.

   The LDAP RFI requires that each attribute have an OID (a globally unique identifier). Some implementations do not require this or build them automatically. Other implementations not only require an OID, but that it also conform to OID formatting standards. CA has obtained and assigned the following OIDs for this use (these are also listed in the Schema section above):

1. The attributes need to be assigned to an objectClass. The choice of objectClass is entirely up to the site.
   • If the site already has a custom user objectClass, the attributes should probably be assigned to it (as optional attributes).
   • The site could define a new custom objectClass. The APS installation kit includes smaps.user_oc.conf and 56NetegrityAPS.ldif files (for iPlanet LDAP Directories, versions 4.x and 5.x, respectively) that define the attributes in terms of a new custom object class called smapsInfo. However, the site can use any name they so desire; APS never even sees it.

     The LDAP RFI requires that custom objectClasses have an OID (a globally unique identifier). Some implementations do not require this or build them automatically. Other implementations not only require an OID, but that it also conform to OID formatting standards. CA has obtained and assigned "1.3.6.1.4.1.2552.1.1.9.1" as the OID for the smapsInfo objectClass.

   • It may be possible to add the new attributes to an existing, standard, objectClass, such as inetOrgPerson. This is usually not recommended by LDAP vendors, but it may be possible. iPlanet, for example, forbids it from within its Console, but it can be done by editing its configuration files. This method is generally not a good idea, but it is possible.

   An attribute can appear in multiple objectClasses.

2. The objectClass containing the attributes must be assigned to every user in the User Directory. For LDAP directories, this amounts to adding the objectClass to the list of classes stored in the object's objectClass attribute.

   Note that the selection of where to put the attributes (described in the previous step) can have a considerable impact on this step. For example, if the attributes were added to a standard objectClass, this step is already done. If an existing custom objectClass was used, then this step may already be done. Using a new objectClass will require that this step be performed.

   Also, consider new users. As new users get added to the User Directory, they will need to have access to the attributes as well, so the objectClass will need to be added to their list as well. This will probably impact any user management system implemented at the site.

To use 56NetegrityAPS.ldif on iPlanet LDAP Directories Only:

• Edit the 56NetegrityAPS.ldif file using your favorite editor
• Locate the two instances of smapsInfo (case-insensitive). Rename this class to the name of the class that you want to use. Note that if you want to add the APS attributes to an existing class, you will have to remove this class definition and add the attributes to your chosen class in the file in which it is defined (probably 99user.ldif).
• Save the file.
• Locate the file 99user.ldif in your iPlanet directory. Make sure that you locate the one associated with the desired LDAP directory instance.
• Put the modified 56NetegrityAPS.ldif file into the same directory.
• Restart the LDAP Directory Server.

Note: These steps only need to be performed on a single Master Directory. The changes will be propagated to other masters and consumers (though the changes will be recorded in subsidiary servers in the 99user.ldif file).

Special Setup

There is no special setup for standard LDAP User Directories.

Native Password Policy Support

There is no standard for LDAP native password policies. However, many vendors have implemented them using extended services (how extended services are accessed is defined in the LDAP standard, but the particular details of such extensions is vendor-specific).

Expiration policies are enforced by LDAP directories when the user attempts to authenticate to the directory. This authentication is actually performed by SiteMinder, before APS is invoked. Any failure, even if accompanied by extended information such as Password Expired, is seen by SiteMinder as an authentication failure and so reported to APS. Thus, APS is unable to support such policies.

Password content policies are enforced during the password change process. Most LDAP implementations will refuse a password change if it does not conform to a native password policy. However, this refusal is returned as a generic error code and (vendor-specific) extensions need to be used to determine the specific reason for the refusal. APS does not support native password content policies on standard LDAP user directories.

This second restriction is relatively easy to avoid. APS will apply its own password content policies before attempting to update the password in the underlying directory. If the APS content policy is at least as restrictive as the Directory's policy, then the password will already conform the the directory's rules. Bear in mind that this method cannot accommodate the password history restrictions.

Expiration policies are considerably more difficult to accommodate. Most sites simply turn off any native expiration policies and use SiteMinder (with APS) to perform all authentications. If LDAP is to be used directly by some applications, those applications should be modified to update APS' control information on every authentication.

Disabling/Enabling User Accounts

If the user satisfies the conditions for any Ignore keyword in the APS.cfg file, APS will not perform any authentication time processing for this user, including detecting if the user is disabled or detecting disabling conditions (such as password expired).

Recognizing a Disabled User

APS will recognize that a user is disabled if any of the following are true (this is not necessarily the order in which APS actually does detection). Note that the Use Internal Disables setting does not affect detection, only how APS actually disables users.

• If the user is a member of a standard LDAP (forward) group whose name starts with "DISABLED". APS searches for this membership using the following information:
  • The Search Base as defined in the associated SiteMinder User Directory entry.
  • A group objectclass of groupOfUniqueNames (can be remapped).
  • The group name attribute of GroupCN (by default, maps to cn, but can be remapped to another name).
  • A value for its uniqueMember (also remappable) attribute that contains this user's full DN.

  The Disabled Reason is derived from the text following "DISABLED" in the group's name (any additional hyphen is removed).

  This search cannot be suppressed.

• If the user is a member of a standard LDAP (reverse) group whose name starts with "DISABLED".
  • APS uses the attribute memberof (remappable) in the current user's entry. This attribute is assumed to contain the DN's of the (reverse) groups in which the user is a member.
  • The DN is assumed to start with the group's name attribute, which is remapped from GroupDN (by default, maps to cn, but can be remapped to another name).
  • If the group's DN starts with "DISABLED", the user is considered disabled.

  The Disabled Reason is derived from the text following "DISABLED" in the group's name (any additional hyphen is removed).

  This search can be suppressed by remapping "memberof" to a null value.

• If the user satisfies any of the conditions defined in APS.cfg using the Disable, the user will be considered disabled. The keyword defines the Disabled Reason code.
• If the smapsDisabledUntil field starts with the word "FOREVER", the user account will be considered disabled. The rest of the text (after "FOREVER") in the attribute will be used as the Disabled Reason code.
• If the smapsDisabledUntil field contains a date/time that is in the future, the user account will be considered disabled. The rest of the text (after the date/time) in the attribute will be used as the Disabled Reason code.
• If the smapsDisabledAfter field contains a date/time that is in the past, the user account will be considered disabled. The rest of the text (after the date/time) in the attribute will be used as the Disabled Reason code.
• If the smapsMustLoginBy field contains a date/time that is in the past, the user will be considered disabled. The rest of the text (after the date/time) in the attribute will be used as the Disabled Reason code.

The account may become disabled (as described in the next section) during authentication, but this will set one of the above conditions.

Disabling a User

APS itself can disable a user for only four reasons:

• Exceeded Failure Count. This can only occur during the authentication process.
  • If Auto Reset Failure Count is in effect:

    smapsDisabledUntil is set to the current date and time, plus the number of minutes indicated by the Max Failures On Change followed by the text "Failure Count".

  • Otherwise:
    • If the Use Internal Disables is in effect, smapsDisabledUntil is set to "FOREVER Failure Count".
    • If the Use Internal Disables is not in effect, the user is added to the Disabled-FailureCount group. APS will search for this group using the GroupCN attribute (defaults to cn, can be remapped). If the group does not exist, it will be created in the OU defined by the LDAP Disabled Groups setting.
• Password Expired (any grace period expired and all grace logins expended). This can be done either at authentication time or by APSExpire.
  • If the Use Internal Disables setting is in effect, smapsDisabledUntil is set to "FOREVER Password Expired".
  • If the Use Internal Disables setting is not in effect, the user is added to the Disabled-PasswordExpired group. APS will search for this group using the GroupCN attribute (defaults to cn, can be remapped). If the group does not exist, it will be created in the OU defined by the by the LDAP Disabled Groups setting.
• Account Expired due to inactivity. This can be done either at authentication time or by APSExpire.
  • If the Use Internal Disables setting is in effect, smapsDisabledUntil is set to "FOREVER User Expired".
  • If the Use Internal Disables setting is not in effect, the user is added to the Disabled-UserExpired group. APS will search for this group using the GroupCN attribute (defaults to cn, can be remapped). If the group does not exist, it will be created in the OU defined by the by the LDAP Disabled Groups setting.
• Locked out from FPS misuse. This can only be done by the FPS process.
  • If the Use Internal Disables setting is in effect, smapsDisabledUntil is set to "FOREVER FPS Lockout".
  • If the Use Internal Disables setting is not in effect, the user is added to the Disabled-FPSLockout group. APS will search for this group using the GroupCN attribute (defaults to cn, can be remapped). If the group does not exist, it will be created in the OU defined by the by the LDAP Disabled Groups setting.

Enabling a User Account

APS never really enables an account itself. Some of the mechanisms used by APS to maintain the user status have built-in reset capabilities (dates). APS does not actually update a user record to re-enable it.

To re-enable an account, a site must ensure that all of the above criteria that APS uses to detect that a user account is already disabled are not true. In other words, the user account cannot be a member of a disabled group, smapsDisableUntil must be set correctly, etc.

Even then, it may appear that a user remains disabled. The usual cause is that while the user account does get enabled, the conditions that caused the account to become disabled remain, thus causing APS to just disable the account again. These reasons are:

• The password remains expired. Either set smapsBaseDate (recommended) or smapsLastPasswordChange (not recommended) to a more recent value.
• The account remains expired. Either set smapsBaseDate (recommended) or smapsLastLogin (not recommended) to a more recent value.
• smapsFailureCount shows that the user remains locked out (see the description of the field at the beginning of this chapter for details on how to reset this field - it is not sufficient to merely delete its value).

Special APS Processing/Limitations

For the most part, all APS features are supports by standard LDAP directories (of course, "standard" is the operative word).

The IsLDAP() function (used in settings overrides) returns TRUE if the current user is stored in an LDAP directory (of any type).

The LDAP Disabled Groups setting controls where APS will create any disabled groups within the directory, if the Use Internal Disables setting is not in effect.

The Check LDAP Password Existence and Auto Force Change settings may or may not be supported, depending on whether the implementation allows an LDAP client to read the (hashed) user password.

LDAP Reverse Groups

When APS was originally designed, LDAP supported groups in one way: what are now call forward groups.

A forward group is a group object, physically stored, that contains the DN of all of its members in a multi-valued attribute (usually uniqueMember).

Forward groups do not scale well. In order to provide more scalability, the LDAP standards committee defined reverse groups.

A reverse group is a group object, physically stored, whose DN is contained in its member's records (usually memberof or groups). In other words, each user contains a list of the groups of which it is a member in a multi-valued attribute. Reverse groups scale much better than forward groups.

APS supports forward groups by default, but can support reverse groups, if they are used at the site. It can also support a mix of forward and reverse groups.

You must tell APS which groups will be reverse groups (since there is no standard, quick, way to tell the difference). You configure this in the [Mappings] section of the APS Configuration File.

To have APS treat all LDAP groups as reverse groups, use:

LDAP.ReverseGroups=*

An asterisk should not be considered a wildcard. It can only be used in the above manner to indicate that all groups are reverse groups.

To specify a single group as a reverse group:

LDAP.ReverseGroups=cn=Disabled-NoCredit, o=nds.com

Multiple such lines can exist, one for each reverse group.

Note: Some LDAP vendors has also implement something that they call virtual groups. APS does not support virtual groups as of this writing, but, for most purposes, they can be easily simulated using override expressions or using the Disable setting.

Forgotten Password Services (FPS)

All FPS functionality is supported for standard LDAP implementations, with the exception of question/answer encryption. This can still be accomplished, however, using the SmAPSEx library.

APSExpire

APSExpire has special settings for LDAP directories so that the user directory can be partitioned into smaller "chunks" for processing. See the chapter on Daily Processing (APSExpire), for details.

APSAdmin

APSAdmin fully supports LDAP User Directories. However, APSAdmin only supports the entry of the full user DN on the user selection panel.

Fault Tolerance & Performance

A considerable amount of work has gone into APS to optimize performance when dealing with LDAP directories.

APS reads the entire user entry into memory before handling any request. This means that all settings overrides and attribute references required by email templates canbe handled without another request to the directory server. The additional overhead of this single read is nominal, the performance of the read is the lookup and network latency, not the actual data transfer.

When writing to the directory, APS "gangs" all of the updates into a single request to the directory server. This is a huge performance gain. While suppressing individual attributes can improve storage resource utilization (disk space), it has little impact on the update performance; the performance overhead for the entire update far outweighs the incremental performance cost of additional fields (as long as the updates are submitted together).

A side-effect of the ganged updates is improved fault tolerance. LDAP guarantees that all writes submitted as a single request either succeed or fail together. No single field will be updated without the others.

What this means, for example, is that the password cannot be updated without the password change date attribute. They either both update or neither updates.

In a multi-mastering situation, this is even more critical. Parts of the update cannot go to each of two servers. All of the updates will be posted to the same place at the same time.

APS does not use SiteMinder's Enhanced Referrals. It does not keep pools of LDAP handles, pinging them periodically to determine connection health and to keep the connections from timing out. It does use SiteMinder handles for reading (and, in some cases, writing) to the directory server, but requests normal handles from SiteMinder.

This means that APS fully supports multi-mastering. With no writeback settings (discussed below), APS follows write referrals to any or all masters that it needs to accomplish its task. This is entirely handled within the LDAP SDK and is subject to its own performance issues.

LDAP supports master/consumer servers, where one or more directory servers are masters and others are consumers. Consumer servers are, by definition, read only and are tuned for high performance reads. Typically, SiteMinder is configured to deal with consumers and all writes should go to the master(s). When a change goes to the master, it replicates that change to other masters and any consumers.

However, LDAP implements such relationships using referrals. When the write is made to a consumer server, the server responds to the LDAP client with a special message that says "I am a consumer, please resubmit your request to <list of master servers>". The LDAP client is expected to (possibly open a new connection and) resubmit the request to each of the master servers in the list until the request is satisfied.

The LDAP SDK can be told to accomplish this automatically and, in fact, when SiteMinder Enhanced Referrals are turned off, it does so. APS uses such handles when it uses SiteMinder handles.

However, even this mechanism has a fairly significant performance penalty when doing a large number of writes: every write is at least two round trips to directory servers; the first to the consumer which then returns the referral.

Sites can bypass this referral process within APS by specifying LDAP Write Back Information. This tells APS that one or more master servers exist and to do all writes to that list instead of submitting the update request to the SiteMinder-supplied handle.

Known Directory Idiosyncrasies

A few implementation-dependent "features" have created some idiosyncrasies for APS support:

• Some LDAP implementers have disallowed the reading of the hashed user password. In these cases, APS cannot support the Check LDAP Password Existence and Auto Force Change settings. This is implementation-dependent.
• Some LDAP implementations (Websphere among them) only recognize the first n characters of attribute names as being unique. Some APS attributes may be too long or identical out to this limit, causing issues with the directory. This problem is easily solved by remapping the names of the attributes to shorter names.
• If the LDAP Disabled Groups setting is not defined and APS needs to create a new disabled group, it attempts to create the group at the root of the directory tree. It determines this root by using the last component of the user's DN. Some implementations of LDAP default the last two components of the default DN to domain components ("dc") rather than organization ("o"). In these configurations, there is no container for the last component; the last two components must be used instead. APS is not aware of this and will fail to create the group.
• This is easily solved in one of two ways: Either use the LDAP Disabled Groups setting to explicity specify where groups should be created or pre-create all of the groups so that APS does not need to create them.
• The same physical LDAP directory is sometimes configured to SiteMinder multiple times, either with different search criteria or with different administrator credentials. Since APS tries to match up the current user's LDAP directory (as specified by SiteMinder as the server's IP address or network name) with that specified within the SiteMinder Policy Store, these cases can cause problems when APS selects the wrong SiteMinder User Directory (thus either using the wrong credentials or the wrong search base).

  This problem can be solved by defining multiple names for the same LDAP directory within the Policy Server's host file, all with the same IP address (alternatively, multiple DNS aliases could also be used). Then the multiple User Directories can be specified within the SiteMinder Policy Store, each with a unique name. APS can then determine the correct entry to use.

• Some LDAP implementations impose security within the directory, most notably iPlanet with its Access Control Information (ACIs). This is not part of the LDAP specification at all and can make troubleshooting APS very difficult. CA generally recommends using administrator credentials with full rights to user entries. In the case of iPlanet, the cn=Directory Manager administrator bypasses ACI checking altogether.
• For iPlanet User Directories, the cn=Directory Manager administrator has some special processing on the directory server. Specifically, it bypasses all security (ACIs), it has no limits on its resource limitations (timeouts and size limits), and it receives priority processing.

  APS is very careful of its resource utilization, so its use of the Directory Manager can be considered "safe"; it will not consume unreasonable amounts of server resources. However, the use of this account must be determined by the site.

• LDAP directories must be writable for APS to operate at full function. Advanced Password Services saves information to each user's record in the LDAP directory (in particular, the new password), so the directory must not prevent active writing.

  Backup LDAP servers, as of this writing, are, by the LDAP specification, read-only servers. If SiteMinder is configured to use a backup LDAP server, APS will be unable to write to the directory. Errors will be logged to the console indicating this state.

  This problem can sometimes be avoided using the writeback settings in the APS Configuration File, but only if the Primary LDAP Directory Server is operational at all times.

APS supports LDAP multi-mastering in two ways:

• It will automatically follow any write referrals sent back as the result of a write to a consumer server.
• The LDAP Write Back Information allow the specification of more than one master server.

  Some implementations of LDAP are actually LDAP interfaces to other data stores. Many of these implementations provide multi-mastering on their own. Examples are X.500, ISOCOR and Oracle's LDAP implementation. CA does not recommend any particular implementation.

  While APS does generally support the same consumer failover as SiteMinder and fully supports LDAP multi-mastering, the FPS subsystem does not currently support consumer failover.