MLDAP ESM Module Custom Configuration Information

[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 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 DLL (Windows) or 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 Windows this defaults to wldap32.dll, the Microsoft LDAP client. On UNIX, the default is openldap, which is the Micro Focus port of the OpenLDAP client library.

For example:

[LDAP]
 provider=libldap.a

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 is 3. Normally 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 (see Base above) is appended to the value to create the full DN of the user container. The default 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 is CN.

group class=LDAP class name

Set the name of the LDAP object class used to hold group information. The default 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 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 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 is CN=Enterprise Server Resources.

bind=simple | negotiate | es-user

Set the method for binding to the LDAP server:

• The simple 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 should be an LDAP distinguished name.
• The negotiate 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; for Active Directory, it should be a Windows username, optionally prefixed with a domain name followed by a backslash (domain\user).
• The es-user 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 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 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 may cause servers to reject certain queries. For example, Active Directory rejects subtree queries (see search scope above) if referrals are enabled.

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 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 is no.

timeout=seconds

Set the timeout for lengthy LDAP operations. This affects LDAP searches; depending on the LDAP provider, it may 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 succeedes 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 that 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).

[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 is 64; the maximum value is 9999. Increasing this value consumes more shared memory and increase processing time for authorization requests, Micro Focus recommend 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 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 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 default is no), the Compatibility Rule Matching algorithm is used.

rule substitutions=yes | no

Set this to yes to enable the use of the ${user} token (which is 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 (the default is no), 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.

[Passwords] section

expiration=number

Set the default password expiration interval, in days. It only applies if MF-hash verify mode (that is, Micro Focus password hashes) 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 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 day 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

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

expiration-check=setting

Enables a heuristic that attempts to determine if a user bind was rejected by the LDAP server because the user's password was expired. If this set to "1" or a string beginning with "y", and bind-mode verification is enabled (see the [Verify] section), and a password expiration interval is configured, then when a user's bind request is rejected, the module checks to see if their password expiration date has passed. If so, it returns an error code indicating the password is expired, rather than a generic verify-failed error code.

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 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 may 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 may 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) in all.

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

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

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. Normally, 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 allowing 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 ES regions) 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 is 60 (one minute).

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 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 is no.

[Trace] section

Config=yes | no

Setting this to yes triggures 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 defaut, 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 may 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. Micro Focus SupportLine may 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 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 are allowed.
• 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 are allowed
    • entity is a resource entity name (for example "CINQ"); wildcards are allowed
• 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 somewhat, 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.

[Verify] section

mode=MF-hash | bind

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

• The MF-hash 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.
• The bind 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 may be somewhat slower and consume more resources.

Other modes may be supported in the future, such as testing other types of password hashes. The default is MF-hash.

password type=MF | MF-A2 | MF-Argon2 | MF-MD5 | AD | MD5 | plain | compatible

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 (same as MF-A2).
• MF-A2 or MF-Argon2 creates 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.
• The compatible setting first tries to set unicodePwd using the Microsoft syntax, then tries to set userPassword using the MD5 method. This will usually 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.

The default is MF, 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.

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.

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.