Previous Topic Next topic Print topic


MLDAP ESM Module Custom Configuration Information

The MLDAP ESM Module also 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.

Here are the various configuration sections, and the options that can be set in each section.

[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 (eg "_t.so.2") will be 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.
Example:
[LDAP]
 provider=libldap.a
will instruct 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) will be 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 that if this option is set to a non-default value, the sample LDAP schema and data files will 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.
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 will search only the first level within the specified user, group, and resource containers. tree will search 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 will reject 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 will either succeed or fail quickly (the server will either accept or reject 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 will be 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 will take 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 will consume more shared memory and increase processing time for authorization requests, so we 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 will get 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 will attempt to keep track of login attempts by updating this attribute. It will be 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 will attempt 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 will be 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.

[Passwords] section

expiration=number
Set the default password expiration interval, in days. It only applies if MF-hash verify mode (ie, 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 will be 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.

Example:

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

will set 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 will check to see if their password expiration date has passed. If so, it will return 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, ie no password history is kept.
minimum length=number
Require that new passwords be at least number characters long. (Note that while ESF itself supports long passwords, MSS is currently limited to a maximum of 8 characters, so use caution when setting this value.) 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.
maximum length=number
Require that new passwords be no more than number characters long. (Note that while ESF itself supports long passwords, MSS is currently limited to a maximum of 8 characters, so use caution when setting this value.) 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.
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.

Example:

[Passwords]
required=alphabetic, numeric

will cause password changes to fail 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, so 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, etc. 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 will 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 that any setting here will obviously not be secret from 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 will 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 will be valid for this length of time after it's generated; after that it will be rejected. The default is 60 (one minute).

[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 will be the same as for the LDAP server (which will be the same as for logging into the OS itself, if the OS is using LDAP authentication). However, 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 | 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.
  • 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 will 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 is 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 that 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 won't 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 that 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.

[Trace] section

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 will make 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 will make 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 will make a log entry for every search that returns an error other than "not found". (During Auth requests, there will typically be many searches that return "not found"; the "fail" setting avoids logging these normal unsuccessful searches.) If it is set to "found", the module will log all searches that succeed or return an error other than "not found". If it is set to "all", "y", or "yes", it will log 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 will make a log entry if one of these "silent modify" operations fails. If it is set to "all", "y", or "yes", it will log 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 will make 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 will make 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 will be logged. If it is set to "changes", additional messages will be logged when an update request causes the module to change internal state, such as the MSS attributes (operator class, etc) 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 (eg "TCICSTRN"); wildcards are allowed
      • entity is a resource entity name (eg "CINQ"); wildcards are allowed
  • result is allow, deny, unknown, fail, any, or debug

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

Examples:

  • verify:SYSAD:deny will trace Verify (signon) requests where the SYSAD user is denied
  • auth:SYSADM group:TCICSTRN:C*:allow will trace 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 dataset 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 dataset.

Previous Topic Next topic Print topic