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.
[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 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 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).
- 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.
[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.
- 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 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 is compatible for
Enterprise Server 5.0 and earlier, and loose for
Enterprise Server 6.0 and later.
[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:
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:
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.