MLDAP ESM Module Custom Configuration Information

The MLDAP ESM Module supports some additional configuration that can be set by editing the text in the Configuration Information area. Text in this area is organized into sections which begin with a "tag" in square brackets, followed by lines in the form name=value.

The following list the various configuration sections, and the options that can be set in each section:

[Auth] section

audit rule=yes | no

When this setting is enabled, and the Security Manager is able to satisfy an Auth or XAuth (resource access permission) request, it generates an audit event describing the effective rule - the security rule which was used to make the decision.

The audit event has category code 100 and event code 1. It includes:

The Security Manager index and name.
The module name ("mldap_esm").
The Username.
The Subsystem.
The type of request ("AUTH" or "XAUTH").
The name of the resource.
The access decision ("allowed", "denied", or "answered").
The name of the rule.

The rule name is the LDAP CN (Common Name) of the microfocus-MFDS-Resource object which was matched to the request and had an ACL (Access Control List) which applied to the request.

Note: This has no effect if ESF Auditing is not enabled.

[LDAP] section

provider=module

The name of the dynamically-loadable module containing the LDAP client functions. It should be a shared object (UNIX), exporting the standard LDAP C API functions. On UNIX, if module does not include a file extension, the standard Micro Focus file extension for that platform (for example, "_t.so.2") is appended so the same configuration can be used on platforms with different naming conventions. On UNIX, the default is to search for the LDAP client library as it is typically installed for this platform.

For example:

[LDAP]
 provider=libldap.a

This instructs the ESM Module to use the provider library libldap.a, the LDAP client available from IBM for AIX.

version=2 | 3

Set the LDAP protocol version. The default value is 3. Typically, this does not need to be changed, since if either the client or server does not support version 3, they should automatically fall back to version 2.

base=DN

Set the base container for Enterprise Server security information in the LDAP server. The default is CN=Micro Focus,CN=Program Data,DC=local, which is the container used in the sample configuration. The value should be the common part of the DNs of the Enterprise Server Users, Enterprise Server User Groups, and Enterprise Server Resources containers.

Note: If your user, group, and resource containers are in separate branches of your LDAP repository, you can set base to an empty string and use full DNs for user container, group container, and resource container.

user class=LDAP class name

Set the name of the LDAP object class used to hold user information. The default is microfocus-MFDS-User, but installations with existing user definitions in an LDAP repository might want to extend those definitions with the Micro Focus MTO user attributes and use them instead.

user container=partial DN

Set the name of the LDAP container that holds Enterprise Server user objects. The value should be one or more LDAP DN components; the LDAP "base" DN is appended to the value to create the full DN of the user container. See base above for more information. The default value is CN=Enterprise Server Users.

user ID attribute=name

Set the name of the LDAP attribute that holds the MTO user name in an Enterprise Server user object. This is useful if your LDAP schema already uses the default "CN" (Common Name) attribute for some other purpose.

Note: If this option is set to a non-default value, the sample LDAP schema and data files have to be edited in order to create compatible data in the LDAP repository.

Attribute names are case-insensitive. The default value is CN.

group class=LDAP class name

Set the name of the LDAP object class used to hold group information. The default value is microfocus-MFDS-Group.

group container=partial DN

Set the name of the LDAP container that holds Enterprise Server group objects. The default is CN=Enterprise Server User Groups.

group member attribute=name

Set the name of the LDAP attribute that holds the list of Enterprise Server users who are members of each group object. Attribute names are case-insensitive. The default is microfocus-MFDS-Group-member, unless the group type is set to AD, in which case it is member.

group short name attribute=name

Set the name of the optional LDAP attribute for group objects which is to be used as the Enterprise Server name of the group, if it has a value. Enterprise Server user-group names are restricted to 8 characters. By default, the first 8 characters of the group's CN (LDAP Common Name) is used as the group name. This configuration option can be used to tell the MLDAP ESM Module to use the value of a different attribute for the group's name. If the attribute is not defined for the group class, or it is not set for a given group, then the CN is used.

If this option is used, the group's "short name" (the value of this attribute) should be used when:

Specifying the group in a resource ACL.
Specifying a signon group for the ESF Verify operations.
Specifying a nested group (one group as a member of another group).

You can use an existing string attribute, such as displayName or microfocus-MFDS-UID, for the group short name, or add a new attribute to the LDAP schema.

group type=MF | custom | AD | both

Configures the processing of user-group information. This setting enables the use of Active Directory user groups and group members specified by its LDAP distinguished name. See Using Non-Micro Focus Group Objects with LDAP-based Security for more information.

resource class=LDAP class name

Set the name of the LDAP object class used to hold resource access rule information. The default value is microfocus-MFDS-Resource.

resource container=partial DN

Set the name of the LDAP container that holds Enterprise Server resource access rule objects. The default value is CN=Enterprise Server Resources.

bind=simple | negotiate | es-user

Set the method for binding to the LDAP server:

simple: This method sends the LDAP credentials in plain text. If you have the ESM Module configured to use a privileged LDAP account, for example, if it has authority to set user attributes, in order to support user password-change requests, and the network connection between the module and the LDAP server is not secure, use one of the other methods. With this method, the "Authorized ID" in the Security Manager configuration must be an LDAP distinguished name.
negotiate: This method lets the ESM Module and the LDAP server negotiate the most secure method to use. With most LDAP servers this should prevent the LDAP credentials from being sent in the clear. With this method, the "Authorized ID" in the Security Manager configuration depends on the LDAP server.
es-user: This method is only supported on Windows, and only when connecting to Active Directory. It tells the module to bind to LDAP using the user account of the current process (ES/MTO or MFDS). The credentials are not sent in the clear. With this method, the "Authorized ID" and "Password" fields in the Security Manager configuration are ignored.

The default value is simple.

search scope=child | tree

Set the scope for LDAP searches. child searches only the first level within the specified user, group, and resource containers. tree searches the entire LDAP hierarchy below the container. Using tree can significantly impact performance, but is useful for directories that organize users or other LDAP records into separate containers.

onelevel and one-level (the technical LDAP term for this scope) are synonyms for child. subtree is a synonym for tree.

The default value is child.

referrals=yes | no | default

Enable or disable LDAP referrals. LDAP referrals let one LDAP server pass a query along to another server. Usually referrals do not need to be enabled, and in some cases enabling referrals might cause servers to reject certain queries. For example, Active Directory rejects subtree queries if referrals are enabled. See search scope above for more information.

If this is set to default or not set at all, the MLDAP ESM Module leaves the LDAP provider's referrals setting unchanged, and the behavior depends on the provider and server.

The default value is default, for compatibility with earlier versions of the MLDAP ESM Module, unless you have search scope=tree also configured, in which case the default value is no.

timeout=seconds

Set the timeout for lengthy LDAP operations. This affects LDAP searches; depending on the LDAP provider, it might also affect binding or other operations. If this option is not configured or the value is 0, the provider's default timeout is used.

connect timeout=seconds

Set the timeout for LDAP connection attempts. This affects only the first stage of connecting to the LDAP server: opening the TCP conversation. In most cases, this either succeeds or fails quickly (the server either accepts or rejects the connection attempt), so this timeout usually only comes into play when network problems prevent reaching the server host system, or the server host system is down. If this option is not configured or the value is 0, the default is the value of the timeout option, if set; or the LDAP provider's default connection timeout if not.

retry attempts=number

If the LDAP server is unavailable, retry the connection this many times. The amount of time the module waits between attempts can be set using the retry interval option. The default is not to retry. If the initial connection attempt fails, the module returns an error immediately.

Note: The ESF initialization, the thread invoking ESF, and any processing that depends on security in any other threads are blocked until the connection succeeds or the module returns an error to ESF.

retry interval=seconds

The number of seconds to wait between attempts to contact the LDAP server. If this value is not set, the module uses exponential backoff: it waits one second before the first retry attempt, then two seconds before the next, doubling the time between each attempt. So the total wait time, not including any time taken by the connection attempts themselves, will be 2^N - 1 seconds, where N is the total number of attempts, including the first. If retry attempts is set to 5, it takes the module at least 31 seconds to report failure. This value can be set to 0 to have the module try again as soon as each attempt fails (no wait).

retry bind=yes | no

If this option is set to yes, and the retry attempts option is set to a value greater than 1, then LDAP bind operations that fail with various potentially transient errors, such as LDAP_BUSY and LDAP_OTHER, will be retried, even if a previous ldap_connect operation succeeded.

If it is set to no, then LDAP bind operations are only retried if the server does not support ldap_connect. If the server does support ldap_connect, then that can be retried if it fails; but if it succeeds, the bind is only tried once.

The default value is no, which corresponds to the behavior in earlier versions of the product, this corresponds to versions earlier than 3.0 PU24, 4.0 PU18, and 5.0 PU7.

always retry bind=yes | no

If this option is set to yes, and the retry attempts option is set to yes, then LDAP bind operations will be retried regardless of the error returned from the LDAP bind operation even if it is considered an non-retryable error. If it is set to no, then LDAP bind operations are only retried for errors that are retryable.

keepalive idle time=seconds

Linux only, and only when using the OpenLDAP client library. Set the time in seconds before starting keepalive probes on the conversation. The default is determined by the operating system configuration. See the tcp(7) Linux man page for more information.

keepalive interval=seconds

Linux only, and only when using the OpenLDAP client library. Set the time in seconds between keepalive probes. The default is determined by the operating system configuration. See the tcp(7) Linux man page for more information.

keepalive probes=integer

Linux only, and only when using the OpenLDAP client library. Set the number of keepalive probes that can go unacknowledged by the remote side until the conversation is terminated. The default is determined by the operating system configuration. See the tcp(7) Linux man page for more information.

restart=yes | no

If this is set to yes, enable the LDAP option LDAP_OPT_RESTART, which causes some LDAP client libraries, including OpenLDAP, to retry some operations after certain transient failures, such as being interrupted by a non-fatal signal. This is safe and usually preferable. If it is set to "no", the option is not enabled.

The default value is yes.

retry search=N

N is a non-negative integer. If it is positive, an LDAP search request which fails to return either a result or an error indication from the server will be retried up to N times. This might be useful with client libraries such as OpenLDAP which can fail in search for various reasons without returning a valid LDAP error, at the potential cost of taking longer to fail when the LDAP server is genuinely unavailable.

The default value is 0 (only attempt the search once).

[Operation] section

maxgroups=number

Set the maximum number of user groups supported in Use-all-groups mode. This must be at least as large as the number of groups that include any user who will sign on to the region. The default value is 64; the maximum value is 9999. Increasing this value consumes more shared memory and increase processing time for authorization requests, Micro Focus recommends keeping it close to the actual number of user groups you have defined. It has no effect when the "Use all groups" option is not enabled.

Note: If you have multiple MLDAP ESMs stacked in a security configuration, they must have the same setting for maxgroups, unless Federation is explicitly disabled. This requirement is enforced by the module; you are issued a warning if your configuration specifies different maxgroups settings for different instances of the MLDAP ESM Module.

signon attempts=number

Set the maximum number of consecutive failed sign-on (Verify) attempts before a user account is automatically disabled. If number is set to an integer greater than 0, then after that many attempts to sign a user on with incorrect passwords, the account is disabled. Successfully signing a user on with the correct password resets the count. The default value is 0, which disables this feature.

plus-wildcard=yes | no

If this is set to yes, the plus (+) character is interpreted as a wildcard when it appears in a resource rule name. It functions like the * and ** wildcards, except that it always matches exactly one character.

The default value is no.

set login count=yes | no

If the user class includes the microfocus-MFDS-User-LoginAttempts attribute, and this option is set to yes (the default), the MLDAP ESM Module attempts to keep track of login attempts by updating this attribute. It is set to an integer value which is incremented for each failed login attempt and reset to zero when the user logs in successfully. If the ESM Module does not have permission to update the user object, this setting has no effect.

set login time=yes | no

If the user class includes the microfocus-MFDS-User-LastLoginTime attribute, and this option is set to yes (the default), the MLDAP ESM Module attempts to set it to the current UTC time when the user logs in successfully. If the ESM Module does not have permission to update the user object, this setting has no effect.

version 1 authentication=yes | no

If this option is set to yes, the Compatibility Rule Matching algorithm is used. See Compatibility Rule Matching for more information. The default value is no.

rule substitutions=yes | no

Set this to yes to enable the use of the ${user} and ${user_long} tokens, which are replaced with the userid of the user making the access request, in resource access control rules. See Username Substitution for more information. Compatibility rule matching must not be enabled.

check TLQ first=yes | no

If this option is set to yes, it modifies the behavior used to determine if a user is authorized to use a resource. If no exactly matching rule is found, the next query returns all rules that match the TLQ followed by a wildcard, for example, DEV.JCL.TEMP searches for DEV.*. This option might alter the rule finally used for authorization. This option can improve performance when there are large numbers of resources in a class.

The default value is no.

maximum qualifiers for initial check=number

This option is the generalized form of the check TLQ first option. Where number can be 0 or a positive integer. If number is set to 0, then the behavior is equivalent to check TLQ first=no. If number is set to 1, then the behavior is equivalent to check TLQ first=yes. If number is greater than 1, then when the system searches for rules for a resource name with qualifiers, up to number of the initial qualifiers are used. If the resource name has fewer than number qualifiers, only the available qualifiers will be used in the search. For example, if maximum qualifiers for initial check is set to 2, and a request for a resource named DEV.JCL.TEMP is made. The following LDAP searches are performed in order:

A search for the exact name DEV.JCL.TEMP.
If the previous search returns no rules, or the request cannot be satisfied using those rules, a search for DEV.JCL.*. That is, a search for rules beginning with the literal string DEV.JCL.
If that search returns no rules, or the request cannot be satisfied using those rules, a search for all rules containing wildcards is made.

As with check TLQ first, this option might alter which rule is used for authorization, this can lead to unexpected results. This option can improve performance if there are a large number of resource rules in the DATASET class.

Setting this option implies check TLQ first=yes.

The default value is 0 if check TLQ first is not set or is set to no, and 1 if check TLQ first is set to yes.

percent-wildcard=yes | no

If this is set to yes, the percent (%) character is interpreted as a wildcard when it appears in a resource rule name. It functions like the * and ** wildcards, except that it always matches exactly one character. At most, only one of the plus-wildcard and percent-wildcard options can be enabled. The percent wildcard is provided for closer emulation of IBM RACF rule names; the plus wildcard is provided for closer emulation of CA Top Secret rule names.

The default value is no.

dss-wildcard=compatible | loose | strict

This option controls how the sequence ".**", also known as "dot-star-star", is treated in rule names.

If it is set to compatible, then when ".**" appears in a rule name it is treated as a literal dot (.) character followed by the "**" wildcard, unless it appears at the end of a name, in which case the dot is ignored and it is treated like the "**" wildcard. For example, in this mode, a rule named "A.B.**" matches "A.B", "A.B.C", and "A.BC.D". This is the behavior in Enterprise Server prior to release 6.0.

If it is set to loose, the ".**" sequence is a special wildcard which matches either the empty string or any string beginning with a dot character. For example, in this mode, "A.B.**" would not match "A.BC.D", because "C.D" does not begin with a dot. However, "A.B.**.C.D" would match both "A.B.C.D" (the wildcard matches the empty string) and "A.B.X.C.D" (it matches a string beginning with a dot). This behavior is closer to that of RACF on the mainframe. It is the default beginning with Enterprise Server 6.0.

Note: Exact emulation of RACF is not guaranteed.

If it is set to strict, the ".**" sequence is always interpreted as a literal dot character followed by the "**" wildcard. With this setting "A.B.**" would not match "A.B" or "A.BC", but would match "A.B.C" and "A.B.C.D".

The default value is compatible for Enterprise Server 5.0 and earlier, and loose for Enterprise Server 6.0 and later.

check constraints for already-verified users=yes | no

When this setting is enabled, when the Security Manager is processing a Verify (authentication) request where a previous Security Manager has already allowed the Verify, the Security Manager will still check certain constraints and disallow the verify if those checks fail. The constraints are whether signon is allowed (microfocus-MFDS-User-AllowLogin); whether the account is expired (microfocus-MFDS-User-ExpirationDate); and whether the user is a member of the signon group, if one was specified. The default value is no.

group membership uses short name=yes | no

When this setting is enabled, when the Security Manager searches groups to determine which ones a user belongs to, it uses the user's "short name" (ES userid) rather than its "long name" (LDAP CN). This only applies to Micro Focus group objects (of class microfocus-MFDS-Group) and to custom group types which use the simple username to identify members. It does not apply when configured to use AD groups, or custom groups which use the LDAP distinguished name to identify members. This is useful when name mapping is enabled and a Security Manager knows the user only by the ES userid. The default value is no.

search users by short name=yes | no

When this setting is enabled, the Security Manager will use the user's "short name" (ES userid) rather than its "long name" (LDAP CN) to search for an LDAP record for the user. This is useful when name mapping is enabled and a Security Manager identifies the user only by the ES userid. The default value is no.

[Passwords] section

expiration=number

Set the default password expiration interval, in days. It only applies if MF-hash verify mode (that is, a Micro Focus password hash) is being used. This is the default, but many organizations use bind verify mode, in which case password expiration has to be managed by your LDAP server. If a user changes their password, and their account is configured with a password expiration date, the microfocus-MFDS-User-Pwd-ExpirationDate attribute, and that date is in the past or less than this many days in the future, then it is changed to this many days in the future. The default value is 90 days. The microfocus-MFDS-User-Pwd-ExpirationDate attribute must be set to a string of digits representing the four-digit year, the two-digit month, and the two-digit day of the date the password expires (yyyymmdd). Anything following the day is ignored. The standard "UTC Coded Time" format used by many LDAP clients and servers works. You can set an initial password expiration date using a regular LDAP client, or using the esfadmin utility with the ALTUSER command and the PASSEXP attribute.

For example:

esfadmin -uADMIN -pADMIN -U"cn=..." -Pxxx altuser user=SYSAD passexp=20091231

this sets the password expiration date for the user SYSAD to the last day of 2009.

bind failure analysis=setting

Enables a set of heuristics that attempt to determine the most probable reason a user bind was rejected by the LDAP server, which might include invalid credentials, expired password, locked account, and so on. If this is set to 1 or a string beginning with y, and bind-mode verification is enabled, then when a user's bind request is rejected, the module checks a series of optional user attributes for evidence of why the bind might have failed. See [Verify] section for more information. Based on these heuristics it returns what it determines is the most appropriate error code. See MLDAP ESM Module Bind Rejection Heuristics for more information.

bind failure analysis=setting

expiration-check

A historical alias for bind failure analysis.

history=number

Remember number previous password hashes for each user; when users try to change their passwords, if the new password matches one of the stored hashes, reject the request. This option has no effect if the module configuration does not let the module update the user's attributes. The default value is 0, that is, no password history is kept.

minimum length=number

Require that new passwords be at least number characters long. If you are using a password type other than "MF", you might also be able to configure this and other password requirements in your LDAP server or OS security policy.

Note: While ESF itself supports long passwords, some MSS programs and APIs are currently limited to a maximum of 8 characters, so use caution when setting this value.

maximum length=number

Require that new passwords be no more than number characters long. If you are using a password type other than "MF", you might also be able to configure this and other password requirements in your LDAP server or OS security policy.

Note: While ESF itself supports long passwords, some MSS programs and APIs are currently limited to a maximum of 8 characters, so use caution when setting this value.

required=list of classes

Require new passwords to include at least one character from each of the listed classes. The supported classes are alphabetic, mixed-case, numeric, and punctuation. Class names should be separated by whitespace and/or commas.

For example:

[Passwords]
required=alphabetic, numeric

this results in password changes failing if the new password does not include at least one letter and one digit.

complexity=number

Require new passwords to include at least one character from number + 1 character classes. Upper and lower case are counted separately, for example, complexity=1 would be satisfied by a mixed-case password, or a password with lower-case letters and digits, or digits and punctuation characters, and so on. Characters that are not (ASCII) letters, digits, or punctuation are counted as another character class, so there are five classes, upper, lower, digit, punctuation, and other.

The various password restriction options can be used in combination, for example:

[Passwords]
 minimum length=6
 required=mixed-case
 complexity=2

this would enforce passwords of at least 6 characters, with both upper and lower case letters and at least one non-letter character.

[Passtoken] section

default=none | self: Set the default passtoken creation and use privileges. Typically, whether a user can create or use ESF Passtokens with this ESM Module is controlled by per-user attributes. If those attributes are not set, they default to none, which means by default users can neither create passtokens nor be signed on using them. Setting this value to self changes the default behavior to allow the creation and use of self-only passtokens.
secret=string: Set the secret data which serve as the key for the Message Authentication Code (MAC) in ESF Passtokens generated by the ESM Module. This data prevents attackers who do not know it from forging passtokens.
Note: Any setting here is not secret to anyone who can read the MFDS repository.
If this value is set, it must be set the same for all security domains (MFDS and enterprise server region) that exchange passtokens.
secret file=path: Set the path to a file that contains the secret data for the passtoken MAC. This is more secure than setting the secret data directly in the configuration. If SecretFile is set, any Secret directive is ignored. If neither is set, a built-in default is used.
duration=seconds: Set the duration for passtokens. A token is valid for this length of time after it is generated; after that, it is rejected. The default value is 60 seconds.
table size=size: Sets the size of the table used to store passtokens. If passtokens are being used for multi-factor authentication, then this table must be larger than the peak number of users concurrently logging on. The default size value is 64.
Note: Increasing the size degrades performance by increasing memory requirements.
short passtoken reuse=yes | no: Sets whether or not short passtokens, which are used for multi-factor authentication, can be used once or multiple times and until they expire based on the duration option. The default value is no.

[Prefix Search] section

Enabled=setting

Enable the Prefix Search wildcard optimization for limiting the scope of wildcard resource entities checked (under a resource class) if an exact resource entity match is not found when checking authorization requests. If this is set to a string beginning with "y" or to "1", the ESM Module will use this feature for any class rules specified in this section.

classname=number

Where the classname specifies a resource class name and the number is the prefix length.

This means that if there is not an exact match for a resource entity, which will be under a resource class, in the LDAP directory, instead of defaulting to a wildcard check for all resource entities which at least contain a *, the entities' name will be taken and will use the prefix length to establish what the LDAP search will be for.

For example, if MYCLASS=3 is specified, then if an authorization request for entity MYENTITY in class MYCLASS, then the prefix search would be for MYE*. MYE* would be used to try to find a relevant entity that can fulfil the authorization request. This occurs before falling back to check other wildcard entities in the class.

Note: Avoid using rules for classes like DATASET or PHYSFILE which contain "." characters. You can enable check TLQ first for classes like DATASET which use data set names.

[Trace] section

Config=yes | no: Setting this to yes triggers the module to emit a message for each valid configuration setting specified in the Configuration Information field of your Security Manager. This can be used for auditing and debug purposes. By default, this option is set to no.

Rule=setting

Enable the logging of the effective rule for resource-access decisions. If this is set to a string beginning with "y" or to "1", the ESM Module makes a log entry for every authorization decision noting which rule was used to make the decision.

Groups=setting

Log various messages regarding the processing of user groups. If this is set to a string beginning with "y" or to "1", the ESM Module makes a log entry when it determines that a user belongs to a group during Verify, or when it finds a group ACE that applies to a request during Auth. This is particularly useful when debugging problems with All-Groups mode.

Search=setting

Enable the logging of some LDAP search operations. Not all searches are currently logged. If this is set to fail, the ESM Module makes a log entry for every search that returns an error other than "not found". During Auth requests, there is typically many searches that return "not found"; the fail setting avoids logging these normal unsuccessful searches. If it is set to found, the module logs all searches that succeed or return an error other than "not found". If it is set to all, y, or yes, it logs all search operations, including ones that return "not found".

Modify=setting

Enable the logging of some LDAP modify operations which are normally not logged. If this is set to fail, the ESM Module makes a log entry if one of these silent modify operations fails. If it is set to all, y, or yes, it logs all of these modify operations, including ones that succeed. Currently affected operations include setting the last-login-time user attribute, and possibly others.

Bind=setting

Enable the logging of LDAP bind operations. If this is set to a string beginning with y or to 1, the ESM Module makes a log entry when it binds to the LDAP server. This might be useful if you are investigating an issue with network traffic to the LDAP server.

Locks=setting

Enable the logging of intra-process and inter-process locking. If this is set to a string beginning with "y" or to "1", the ESM Module makes a log entry when it tries to acquire, acquires, or releases a lock. Customer Care might ask you to enable this tracing mode to diagnose certain unlikely problems.

Update=setting

Enable the logging of update requests, which are ESF control requests, made using MFDS or the esfupdate command-line utility, that notify ESF and the ESM Modules of changes to security configuration or data. If this is set to y or yes, update requests are logged. If it is set to changes, additional messages are logged when an update request causes the module to change internal state, such as the MSS attributes (operator class, and so on) of a user or a user's group membership. If it is set to all, additional messages are logged when an update request does not cause changes.

TraceN=rule

Define a rule for filtered tracing. Filtered tracing lets you trace only requests that meet a set of conditions, defined by the tracing rule. N in the name is a number from 1 to 8 (the maximum number of filtered-tracing rules): Trace1, Trace2, and so on. You can define rules out of order and skip numbers - they only need to be unique and between 1 and 8.

A tracing rule has the following format:

function:actor[:parameters]:result

where:

function

Is verify or auth

actor

Is a username; for auth rules, it can also be a group name followed by the word group. Wildcards can be used.

parameters

Specific to the function:

For verify, there are no parameters
For auth, this must be class:entity, where:

class

Is a resource class name (for example "TCICSTRN"); wildcards can be used.

entity

Is a resource entity name (for example "CINQ"); wildcards can be used.

result

Is allow, deny, unknown, fail, any, or debug

The request is traced if all of the conditions of the rule are met. Tracing means one or more informational messages about the request is written to the log. A result setting of debug is logged based on any result (like any), but logs additional information during processing a request that matches the function, actor, and parameters.

For example:

verify:SYSAD:deny traces Verify (signon) requests where the SYSAD user is denied.
auth:SYSADM group:TCICSTRN:C*:allow traces Auth (authorization) requests where a member of the SYSADM group requests access to any resource in the TCICSTRN class with a name beginning with C, and the request is allowed.

Filtered tracing is useful in isolating issues on busy systems, where normal tracing would produce excessive output. It does affect performance, since each request must be examined to see if it matches a trace rule.

Be sure to use a double asterisk (**) in wildcard specifications for data set names, if you want them to match qualifiers. For example, use auth:SYSAD:DATASET:**:deny to see all cases where SYSAD is denied access to a data set.

Cache=setting

Log messages regarding the operation of the LDAP search-result cache. See MLDAP ESM Module Caching for more information. If this is set to a string beginning with y or to 1, the ESM Module logs messages regarding cache searches, additions, removals, and other activity.

[Update] section

rename active users=no | individual | all

Use this setting to enable the ACEE rename feature. When it is set to no, ESF Update processing will not attempt to rename ACEEs. See Renaming ACEEs and Implementing Security Manager Changes for more information.

When set to individual, ESF Update User requests will cause the MLDAP ESM Module to check whether the named user has been renamed. If so, the module will find all ACEEs for the user and attempt to rename them.

When set to all, ESF Update User requests will trigger rename processing for the specified user as described above. In addition, ESF Update Users and Update All requests will cause the MLDAP ESM Module to search all ACEEs to determine if their associated user has been renamed, then process all of those changes.

CAUTION:

This can take a significant amount of time, depending on how many users have signed on to the enterprise server instance, and will block most other work from being processed.

The default value is no.

[Verify] section

attempt password change=after | before | both

When bind-mode authentication is enabled, specify whether password changes should be attempted before or after trying to authenticate the user's credentials by binding. If this is set to after, the password change will be attempted only after a successful bind, and will use the session bound to the user's account. If it is set to before, the password change will be tried before binding, using the security manager's LDAP session. If it is set to both, it will be attempted before binding, and if that fails, it will also be attempted after binding.

This setting is normally only useful for the Active Directory (AD) password type, and requires additional configuration in Active Directory or AD LDS. See Changing passwords with the MLDAP ESM Module for more information. It has no effect when the verify mode is not bind.

Micro Focus strongly recommends against changing this setting when using any password-type setting other than AD.

The default value is after.

migrate passwords=setting

Enable automatic migration of passwords using a different verifier type to the specified type. Currently only migrating from MF-MD5 to MF-A2 is supported. If this is set to a string beginning with y or to 1, then when a user successfully signs in with their current password, if their current password verifier is of a different type than the value of the password type setting, the MLDAP ESM Module will attempt to replace the verifier with one of the new type. This can be used to gradually migrate users to a more secure type of verifier.

mode=MF-hash | bind

Determine how user credentials (username and password) are verified:

MF-hash: This method retrieves the value of the microfocus-MFDS-User-Pwd attribute, which contains a verifier (a salted cryptographic hash) for the password. It computes the equivalent hash of the supplied password, and verifies that they match. With this method, the passwords used for verifying users under ESF are private to ESF, and not associated with the operating system or LDAP server.
bind: This method uses the LDAP server itself to verify the user's credentials, by using them to bind to the server. With this method, the user's password for ESF is the same as for the LDAP server, which is the same as for logging into the OS itself, if the OS is using LDAP authentication.
Note: This method might be slower and consume more resources.

The default value is MF-hash.

password attribute=name

Overrides the name of the attribute of the user class that contains password data, for setting passwords. See the descriptions of the password types above for the defaults.

password change failure=allow | deny

This configuration setting determines what happens when a user requests a password change, and the password change fails, for example, because the new password is too short but the user would have been successfully signed on without the password change.

If it is set to allow, the verify request will succeed and the user will be signed on, but the user's password will not be changed. If it is set to deny, a password-change failure causes the verify request to be denied.

In older versions of the product, the behavior in this case was inconsistent among various configurations. It is now consistent and can be controlled with this setting.

The default value is deny.

Controls how passwords are set in LDAP when a new password is supplied as part of a Verify operation:

MF: Creates a secure verifier (a salted cryptographic hash) of the password, and sets it as the value of the microfocus-MFDS-User-Pwd attribute. This is suitable if you are using the microfocus-MFDS-User class for your Enterprise Server users. It corresponds to the MF-hash password-verification method described above. Currently this is a salted MD5 hash of the password, the same as the MF-MD5 setting. Starting with Enterprise Server 4.0, it will use a salted Argon2 hash, the same as MF-A2.
MF-A2|MF-Argon2: These create a secure verifier using a salted Argon2 hash. This is supported starting in Enterprise Server Patch Update 2. It is more secure - harder to find a matching password - than the previous MF-MD5 scheme, particularly for short passwords.
MF-MD5: Creates a secure verifier using a salted MD5 hash, as used in older versions of Enterprise Server. You can use this if you need to use the same LDAP directory with older and newer versions of Enterprise Server. This is less secure than the new Argon2-based verifier (MF-A2).
AD: Sets the attribute unicodePwd to the value of the supplied password, in quotes. This is a special operation for Microsoft Active Directory (and ADAM) which is equivalent to setting a user's password using the Windows APIs. Active Directory create and store a secure hash of the password. This is suitable if you are using a Microsoft-supplied class for your Enterprise Server users. It corresponds to the bind password-verification method described above, if you are using Active Directory.
MD5: Computes the MD5 hash of the password and sets it as the value of the userPassword attribute, using the syntax specified by RFC 2307, which is not standard but widely supported by LDAP servers. It corresponds to the bind password-verification method if you are using an LDAP server which supports this password type, such as OpenLDAP.
plain: Sets the userPassword attribute in plaintext. It should normally only be used for development purposes, since it is not secure with most LDAP servers.
Note: There is an option in Active Directory (which is enabled by default in ADAM) that makes userPassword an "alias" for unicodePwd; if that option is enabled, this method can be used to set passwords in Active Directory or ADAM.
compatible: This setting first tries to set unicodePwd using the Microsoft syntax, then tries to set userPassword using the MD5 method. This will typically work when the ESM Module is configured to use the bind verification method: if the LDAP server is Active Directory, the unicodePwd attribute setting will work, and if another LDAP server is being used, there will not be a unicodePwd attribute so the more common userPassword attribute will be set instead.
SSHA512: Specifies a salted 512-bit SHA-2 hash of the password, using RFC 2307 syntax. This password type is supported by OpenLDAP with the optional pw-sha2 module, and by some other LDAP servers.
Note: SSHA512 is significantly more secure than the MD5 type.
MF: This is the default value, unless the password verification mode is set to bind, in which case the default is compatible.
Note: The MLDAP ESM Module does not currently support the LDAP Modify Password Extended Operation (RFC 3062). Also note that Active Directory, and possibly other servers, only allow password changes over a secure LDAP connection (SSL/TLS or otherwise encrypted) by default; see your LDAP server documentation for more information.