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

Microsoft Active 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.

APS supports Microsoft Active Directories running in LDAP mode only.

Schema Updates

APS tries to place as few restrictions as possible for the schema that it needs, in part because many sites have policies or requirements for how schemas are updated, naming conventions and data layout issues. 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. 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.

   Attributes need not have the names defined above. If the attributes are to be renamed, the names must be remapped.

   Microsoft Active Directory requires that each attribute have an OID (a globally unique identifier). 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.
   • Active Directory requires that custom objectClasses have an OID (a globally unique identifier). CA has obtained and assigned "1.3.6.1.4.1.2552.1.1.9.1" as the OID for the smapsInfo objectClass. If a different name is used, a different OID should also be obtained.
   • 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. 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.

Special Setup

Certain remappings are required in the APS.cfg file to identify and process Active Directories. The following three lines are the minimum required to support an Active Directory as a user store (in the [Mapping] section of the APS.cfg file):

userPassword={IsInDirectory("<dirname>")} unicodePwd
inetOrgPerson={IsInDirectory("<dirname>")} user
smapsPassword ={ IsInDirectory("<dirname>") }

Note that <dirname> is the name of the User Directory entry in your Policy Store.

If the only User Directory is an Active Directory, then the following three lines can be used:

userPassword=unicodePwd
inetOrgPerson=user
smapsPassword=

Native Password Policy Support

APS does not support Active Directory password content policies (the policies that define the required format for a password). Active Directory will refuse a password change if it does not conform to its defined native password policy. However, this refusal is returned as a generic error code.

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

APS does support some of Active Directory's native expiration policies.

• When calculating password expiration dates, it uses the PasswordExpirationDate attribute (can be remapped) and compares it to its own password expiration date. APS will use whichever value is sooner. The Password Warning date will be calculated backwards from the resulting password expiration date.
• When it needs the date/time that the password was last changed, APS uses the pwdLastSet (remappable) attribute or its own value, whichever is earliest.
• When calculating account expiration dates, it uses the accountExpires attribute (can be remapped) and compares it to its own account expiration date. APS will use whichever value is sooner. The Account Inactivity Warning date will be calculated backwards from the resulting account expiration date.
• When calculating the last login date, it uses the lastLogon attribute (can be remapped) and compares it to its own last login date. APS will use whichever value is later.
• APS honors Active Directory's immediate change flag.

Disabling/Enabling User Accounts

If the user satisfies the conditions for any Ignore keyword in the APS.cfg file (page 55), 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 setting, the user will be considered disabled. The keyword defines the Disabled Reason code.
• If the smapsDisabledUntil field starts with the word "FOREVER", the user 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 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 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 (APS will never set the native account status bits):

• 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 setting followed by the text "Failure Count".

  • Otherwise:
    • If the Use Internal Disables setting is in effect, smapsDisabledUntil is set to "FOREVER Failure Count".
    • If the Use Internal Disables setting 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 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 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 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 it is already disabled are not true. In other words, the account cannot be a member of a disabled group, smapsDisableUntil must be set correctly, etc.

Even then, it may appear that an account remains disabled. The usual cause is that while the account does get enabled, the conditions that caused it to become disabled remain, thus causing APS to just disable it 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

Most APS features are supports by Active Directory, but there is some special processing in addition to the native support above.

Active Directory requires that passwords be updated using LDAPS (LDAP over SSL) connections. If writebacks are used, this means that the LDAP Writeback Use SSL setting may be required.

If not using writebacks, the "Use Secure Connections" checkbox must be selected in the SiteMinder User Directory entry.

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 setting will not function under Active Directory.

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 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 Active Directories, 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 entitled 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 and this optimization applies directly to Active Directory implementations.

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 can be 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 Active Directory "features" have created some idiosyncrasies for APS support:

• Active Directory requires that passwords be updated using LDAPS (LDAP over SSL) connections. If writebacks are used, this means that the LDAP Writeback Use SSL setting may be required. If not using writebacks, the "Use Secure Connections" checkbox must be selected in the SiteMinder User Directory entry.
• 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 explicitly 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.
• APS does not support Active Directory Servers that have a space embedded in their name.