MLDAP ESM Module

The MLDAP ESM Module is the ESM Module that enables LDAP servers to be used as External Security Managers for Enterprise Server. MLDAP (Micro Focus LDAP) is an interface to multiple LDAP providers. It lets the MLDAP ESM Module communicate with a variety of LDAP directories, such as Microsoft Active Directory. The directory can be located on the same system with ES, which is often the case for development workstations. (Windows development systems can use ADAM, Microsoft's version of Active Directory for applications, for example.) Or the directory can be remote, which is more common in production environments.

Within the LDAP directory, you define users, user groups, resource classes, and resources, and these objects contain the attributes used to make security checks (for the Verify, Auth, and XAuth procedures). Micro Focus defines a schema for these objects and their attributes, but in many cases you can adapt an existing directory for at least part of this information, for example in order to reuse an existing repository of user information.

When the MLDAP ESM Module is invoked by ESF Manager to process a security request, it searches the configured LDAP repository for relevant rules and applies whatever it finds. Like other ESM modules, it can return a definite result if it finds an applicable rule, or an indefinite result otherwise. (See the discussion of Security Function Return Codes.) Since multiple ESM Modules can be configured, this allows configurations such as user and resource information in separate directories, or resolving some requests using LDAP and others using some other ESM.

LDAP Client and Server Software

The MLDAP ESM Module uses an LDAP client library, also called a provider, to communicate with an LDAP server.

The MLDAP ESM Module uses the Micro Focus MLDAP library to provide a common API to LDAP providers. The ESM Module tells MLDAP what LDAP provider library to load and call. Micro Focus does not supply an LDAP provider library of our own. On Windows, the default provider is the one Microsoft includes with the operating system. On Unix, we bundle the OpenLDAP open source client library as the default provider.

You can also configure the ESM Module to use a different provider library by setting the provider option in the Security Manager configuration.

The LDAP server maintains a directory (sometimes called a repository) of security, configuration, and other data. Micro Focus does not supply its own LDAP server, but we do bundle the Microsoft ADAM (Active Directory / Application Mode) server on Windows.

This documentation assumes you already have an LDAP provider library installed on the system where you're using the MLDAP ESM Module, and an LDAP server available on your network. If not, you can contact your operating system vendor or try the free OpenLDAP implemenation from http://www.openldap.org.

The Micro Focus LDAP Schema

LDAP directories are composed of objects with attributes. The objects are arranged hierarchically within special objects called containers; containers can hold both regular objects and other containers. Each object is of a particular class, which defines what attributes that object can have and other information.

The definition of object classes and the hierarchy of containers in an LDAP directory is called a schema. Each LDAP directory has a schema, which can be extended by importing another schema into it. The MLDAP ESM comes with the Micro Focus Schema which can be imported into your LDAP server. It's also possible to adapt an existing schema to replace part of the Micro Focus schema, but that requires advanced LDAP knowledge. The rest of this discussion assumes you are using the standard Micro Focus schema.

All objects have a Distinguished Name or DN, which is a string made up of components in the form type=value, separated by commas. The DN is unique among all the objects in the directory. Objects also have a Common Name or CN, which is a simple string (possibly including spaces). CNs are not unique across the directory, but may be required to be unique within a certain scope, such as within the object's container.

The standard Micro Focus LDAP Schema puts all of its objects in an outer container called the Application Partition. By default this is named:

   CN=Micro Focus,CN=Program Data,DC=local

Within the application partition, we define containers for users, user groups, and resources:

   CN=Enterprise Server Users,CN=Micro Focus,CN=Program Data,DC=local
   CN=Enterprise Server User Groups,CN=Micro Focus,CN=Program Data,DC=local
   CN=Enterprise Server Resources,CN=Micro Focus,CN=Program Data,DC=local

The Enterprise Server Users container will hold one object of class microfocus-MFDS-User for each user defined for ES. This object class, also defined by the Micro Focus schema, includes the user name (as its CN), password (or a password verifier such as a hash value), user information used within MTO such as an optional operator class, and security information such as expiration date and whether login is allowed.

Note:
The MLDAP ESM Module can be configured to use an LDAP class other than microfocus-MFDS-User. For example, if you have existing LDAP users defined using the LDAP class user, you can extend your LDAP schema to add the user attributes defined by Micro Focus to the user class and then configure the ESM module to use it for user definitions. Note, though, that adding new users through the ESM Module (using MFDS or the esfadmin utility) may not work (due to additional object constraints) if you do not use the microfocus-MFDS-User class, in which case you will have to use third-party LDAP or provisioning tools to create new users.

The Enterprise Server User Groups container holds objects of class microfocus-MFDS-Group, which simply contain the name of the group (as CNs) and the list of users who belong to that group. User groups simplify writing resource security rules for multiple users, as rules can be applied to entire groups as well as to users.

The Enterprise Server Resources container holds additional containers, one for each resource class. All protected resources (programs, transactions, datasets, etc) belong to a resource class (not to be confused with an LDAP object class), which in effect specifies the namespace for the resource name. That is, you can define resources with the same name, provided they belong to different classes. MTO resources use various class names defined by IBM. Non-MTO resources, such as ES configuration definitions in MFDS, use resource class names defined by Micro Focus (using syntax that's not permitted for MTO resource class names, to avoid collisions). Users can also define their own resource classes for performing explicit access checks in applications.

Each resource class is defined as a container in Enterprise Server Resources, with the class name becoming the CN of the class container.

Within each class container are zero or more resource objects, of class microfocus-MFDS-Resource. For these objects, the CN can either be a full resource name, such as a transaction name or a dataset name, or it can be a partially- or fully-wildcarded name, which will match various resource names. This lets you write a single rule to apply to multiple resources. Wildcards are discussed in more detail below.

Each resource object also has an attribute named microfocus-MFDS-Resource-ACE, which is a multivalued attribute that holds the Access Control List (ACL) that specifies access rights for that resource. (Each entry in an ACL is referred to as an Access Control Entry, or ACE.) ACLs are discussed in more detail below.

Wildcards for Resource, User, and Group Names

The MLDAP ESM Module supports two kinds of wildcards:

*
Match zero or more characters, except the period (".", aka full stop, dot) character. This exception is generally only useful in dataset names, where it indicates that the wildcard only applies to the current DSN qualifier.
**
Match zero or more characters, including ".". Usually used only in dataset names, to indicate any number of qualifiers, since the period character does not usually appear in other names.

Wildcards can appear in two places:

Match Rank

Both rules and ACEs are prioritized by match rank, which is a measure of how closely the wildcarded string matches the literal string that the ESM Module is searching for (either the resource name or the user/group name). Match rank is an integer value; the higher the value, the closer the match, and the higher the priority of the matched item.

Match rank only applies to matching patterns - patterns that do not match are skipped and never ranked.

Match rank is computed from the number of literal characters and the number of distinct wildcard sequences in the pattern. A distinct wildcard sequence is any number of adjacent wildcard characters, so "*" and "**" both count as one sequence. The rank is also normalized by the length of the name being matched to the pattern; this lets the ESM Module compare rank for user ACEs and group ACEs even if the user name and the group name are different lengths (as they usually are). The formula is:

   R = 512 x L / N - W + 1

where R is the rank value, L is the number of literal characters in the pattern, N is the length of the name being matched, and W is the number of wildcard sequences. So "pat" would outrank "p**t**", which would outrank "p*", which would outrank "*a*", which would outrank "*".

When the MLDAP ESM Module gets back multiple rules for a wildcard search, it sorts them by match rank and processes them in priority order. (Processing stops when the query can be answered - see Resource Rules for details.) When the module is processing the ACEs in an ACL, it lets higher-ranked ACEs (ones that better match the user's or group's name) override lower ones.

For example, if the module is asked to authorize access to a resource named "RESOURCE", and has found rules named "R*" and "R*E", the latter rule will be processed first, because it has higher rank. If it is authorizing for user "USER" and finds ACEs "allow:U*:read" and "deny:*:read", the former would take effect because of its higher rank.

When two rules or ACEs have the same rank, their relative priority is undefined, and either may take effect; so avoid creating conflicting rules and ACEs with the same rank.

Resource Rules, Search Order, and Precedence

Since the MLDAP ESM Module supports wildcards in resource rule names, it's possible that several rules may apply to a single resource access query. The module has to communicate with the LDAP server to retrieve rules, and the server has to search for rules that match the search string sent by the module. That makes it prohibitively expensive, generally speaking, for the module to simply search for all the rules that might apply to a request.

To provide adquate performance, the MLDAP ESM Module tries to answer an access query (AUTH or XAUTH call) with as few LDAP searches as possible, using these principles:

  1. Access is determined by the first defining rule that the module finds and processes. A defining rule is a rule that can answer the access query. It:
    • Applies to the right class of resource.
    • Has a name that matches the resource name, either literally or as a wildcard pattern match.
    • Has an Access Control List that includes at least one entry that applies to the specified user (including user group membership), and that allows or denies the level (for AUTH) or type (for XAUTH) of access requested. Note that denial may be implicit; see Permissions.
  2. The module first searches for a rule with the same literal name as the resource it's looking for. If it gets a request for access to a transaction named "TRAN", for example, it will first look for a rule named "TRAN".
  3. If no such rule is found, or it is not a defining rule for the user making the request (that is, it doesn't have an ACE that applies to the current user), the module performs a longest prefix search for matching wildcarded rules:
    1. First, it will search for the resource name followed by a literal "*" character - that is, for a wildcard rule that begins with a prefix that matches the sought name literally.
    2. Then it replaces the last character of the prefix with a "*" character (so "NAME*" becomes "NAM*") and performs another search. This process will continue until it gets to "*" or it finds a defining rule.
    3. If any of these searches returns multiple rules, they will be processed in match rank order. For example, if the module is trying to authorize access to "NAME" and searches for "N*", it might find rules named "N*" and "N*E". The latter would be processed before the former, because it has higher rank (is a closer match).

One consequence of this approach that may not be immediately obvious is that a short prefix followed by a wildcard will take effect before a wildcard followed by a long (or indeed any) suffix. For example, when searching for "NAME", a rule named "N*" would be found and used before one named "*AME".

Resource Access Control Lists

Each protected resource has one or more ACLs associated with it, either specifically for that resource, or through a wildcard resource object that matches the resource's name. Each ACL, in turn, has one or more ACEs. Each ACE specifies an actor, which is a user, a wildcard pattern for users, or a group, and one or more permissions that are granted (allow) or denied (deny) to that actor.

ACEs

An ACE (Access Control Entry) is an entry in an ACL (Access Control List), which can have zero or more entries. In our schema, an ACLs is the multi-valued attribute "microfocus-MFDS-Resource-ACE"; each value is a separate ACE. (Don't confuse these ACEs with the ACEEs used by ESF - they're completely different things.)

The general ACE format is:

   setting:actor:action-1,...,action-n

where:

MTO resources (transactions, programs, datasets, etc) will typically only have one action per ACE. With the mainframe-style permissions used in MTO, there's no point in specifying multiple actions, since only the highest action applies. For the "extended" or "independent" permissions used for MFDS resources (server definitions and administrative controls) it's often useful to specify multiple actions in an ACE.

Users and Groups

An ACE applies to the current user if the actor string matches the user's name (including with wildcards, if any) or the name of the user's signon group, or if all-groups mode is enabled, the name of any group the user belongs to.

The user's signon group is normally the user's default group; the MLDAP ESM Module assigns this group name from the value of the LDAP attribute microfocus-MFDS-User-DefaultGroup. A different group can optionally be supplied in the VERIFY call that authenticates the user; if the user is a member of that group, they will use that group as their signon group for that session. Usually, the signon facility (such as the CICS CESN transaction) provides a way for users to enter an optional group name.

As of MLDAP ESM Module 1.6.0, actor names in ACEs are case-insensitive, so an ACE like allow:sysad:read will apply to the SYSAD user.

"Use all groups" Mode

Normally, only the user's signon group is used when checking for group permissions for a resource, for performance reasons. If the option "Use all groups" is enabled in MFDS for the current ES Server, however, users will automatically have the permissions of all the groups they currently belong to. (In this case the signon group is unimportant.) This is equivalent to the "List-of-groups processing" available as an option in some mainframe security facilities, or the usual behavior of Unix and Microsoft Windows.

Note:
Use-all-groups mode consumes additional resources (notably CAS shared memory, when running under CAS) for the list of group names and the per-user group membership information. Also, it requires additional LDAP searching and processing during Verify operations, and additional processing during Auth and XAuth operations. (It is especially expensive when operating on ACLs that include wildcarded group names, such as "allow:x* group:update", which would apply to all groups with names beginning with "x".)

When use-all-groups mode is in effect, there is a configurable limit to the number of user groups. (The limit applies to the number of groups that include users who have signed on since the region was started, so groups that are defined but not used don't count against it.) See [Operation] section.

If you have stacked multiple MLDAP ESM Modules in your security configuration, there are special considerations for use-all-groups mode. See the sections on Federation and maxgroups for more information.

Federation in the MLDAP ESM Module

The ESF Federation setting affects how instances of the MLDAP ESM Module work together, when multiple ESMs using the MLDAP ESM Module are stacked in the security configuration. Federation is not a concern if there is only one MLDAP ESM Module in the stack.

If federation is disabled, the MLDAP ESM Module will ignore any Auth and XAuth operations that refer to users which are not known to that module. For example, suppose you have two LDAP repositories, with some of your users defined in the first repository and the other users defined in the second. To accommodate this configuration you have created a security configuration with two MLDAP ESM Modules on the stack, one pointing to the first LDAP repository and the other to the second. Assume the user Alice is defined in the second repository and that federation is disabled. When Alice tries to access a resource, ESF will make an Auth request to each ESM in turn. The first ESM does not have information about Alice, as she's defined in the second ESM, so it will return "unknown" for the Auth request. The second ESM will then process the request normally. That means resource ACLs defined in the first ESM will not be consulted when determining Alice's access.

If federation is enabled, or is set to compatibility mode (currently the default), then the first ESM will look for resource ACLs that apply to the Auth request, even though it was not the ESM that verified the user Alice.

Federation also affects use-all-groups mode. If federation is enabled, all MLDAP ESM Modules in the process will share a single set of group names and group membership information. If federation is disabled, each MLDAP ESM Module will have its own set of group names and group membership information. In federation compatibility mode, there is only one set of group names shared by all modules, but each module has its own information about what users belong to each group.

The compatibility federation setting can lead to unexpected results, since an ESM may not have group information for a user and so may not apply group-based ACLs as you expect. When using multiple MLDAP ESM Modules, it's usually best to explicitly enable or disable federation, especially if use-all-groups mode is enabled.

In general, you should enable federation if you want your LDAP security information combined, as if it all came from a single LDAP repository. You should disable federation if your LDAP repositories are designed to be independent (so, for example, resource access rules from one LDAP repository should not be applied to users from the other repository).

If redundant (also known as high-availability) mode is enabled for ESF itself, federation is automatically enabled.

Access Levels and Permissions

There are two ESF API Auth functions: AUTH and XAUTH. AUTH is used by MTO; XAUTH currently by MFDS, and probably by other non-MTO facilities (such as Web Services) in the future.

AUTH implements mainframe-style permissions, where a user is granted a permission level that includes all the "lower" permissions (write access implies read access and so forth). XAUTH implements more modern discretionary access controls (DACs) with up to 32 independent permission bits. The ES MTO subsystems (CICS, etc) use AUTH and mainframe permissions; MFDS uses XAUTH and independent (aka "extended") permissions.

Resources are typically defined for MTO or for MFDS, and not for both, so the two kinds of permissions do not normally apply to the same object. If they do, for some reason, an allow ACE that specifies the desired MFDS permissions will also grant the highest specified access level for mainframe-style permissions. For example, "allow:user:read,update" grants read and update access under MFDS and update-level access under MTO.

Mainframe-Style Access Levels (MTO)

Mainframe-style permissions are a strict hierarchy of six levels:

  1. no access
  2. execute
  3. read-only (plus execute for programs)
  4. update (adds ability to write)
  5. control (adds the ability to delete, etc)
  6. alter (can do anything, including changing permissions)

For mainframe-style permissions, the "add" and "delete" tokens in an ACE are synonyms for "update". The "none" token is a synonym for the lowest level (no access), when used in an allow rule; in a deny rule, it has no effect except to override any lower-ranked deny rule. The "all" token is a synonym for the highest level (currently "alter").

So rather than a set of orthogonal permissions, as in most DAC systems, we have a current permission level which can be increased by allow rules.

If we encounter a deny rule for the access level we're looking for or a lower one, we deny the request. If the user wants update access, for example, they're not affected by a deny for control, but they are affected by a deny for read, because update requires read.

Independent Permissions (MFDS)

Independent (aka extended) permissions are separate from one another; a user can have write access but not read access to a resource under the independent-permissions model. Independent permissions are used if the ESF caller uses the XAUTH request. Currently only MFDS uses XAUTH.

With independent permissions, a user has a set of permissions for any given resource that can include some, all, or none of the following:

Allow ACEs add the specified permissions to the set; deny ACEs remove the specified permission. (If allow and deny ACEs of equal rank specify the same permission for a user, the deny overrides the allow, and the permission is not granted.)

For independent permissions, the "all" token corresponds to setting all of the permissions (ie it is a synonym for "execute, read, update, add, delete, control, alter"), and the "none" token sets none of the permissions.

ACE Precedence

ACEs can refer to users or groups. They can specify an exact name or a pattern with wildcards. They can allow or deny an access level or set of permissions.

This flexibility means that even within the single ACL belonging to the defining rule that the MLDAP Module uses to determine whether the requested access is allowed (or what the user's effective access rights are, for a permissions query), there may be conflicting ACEs. The module applies these rules to make its access decision:

Processing ACLs

To process an ACL, the module iterates through the entries (ACEs) in the list. Note that the LDAP server may return an ACL's entries in any order, so do not assume the order of entries has any effect on the outcome. For each entry:

After processing all of the ACL:

In other words, access-level requests first decide whether user or group rules should apply (based on rank), then determine the level that results from those rules, then return the appropriate result based on that level.

Permissions-set requests start with the lower-ranked rules, then allow the higher-ranked rules to override them, to determine the final effective set of permissions.

Module Configuration

The MLDAP ESM Module has a number of configurable parameters. Its configuration is administered with the Micro Focus Directory Server (MFDS). Currently, ESM Module configuration is found in the Options section, in the "Security Managers" tab under the "Security..." tab, but this may change in future releases.

You can create multiple "Security Manager" objects in MFDS using the MLDAP ESM Module, in order to use the module with different configurations for different ES servers or for MFDS itself.

To select the MLDAP ESM Module for a Security Manager, set the Module field to mldap_esm.

MLDAP ESM Module Configuration Fields

The other fields of the Security Manager screen are used by the MLDAP ESM Module as follows:

Connection Path
This is the location of the LDAP server, specified as a hostname or IP address, optionally followed by a colon and a port. The default is localhost:389 (389 is the well-known port for LDAP).
Authorized ID
The username used to bind to the LDAP server. The format for this is server-dependent, but is usually a Distinguished Name. This user should have read access to the ES user, group, and resource objects in the LDAP repository, and needs to have modify access to user definitions if you wish to support letting users change their passwords from ES (for example from the CICS signon screen). The default is CN=MFReader,CN=ADAM Users,CN=Micro Focus,CN=Program Data,DC=local (though the last three components can be changed by setting the base DN; see below), which is the user object created for this purpose in the sample configuration.
Password
The password used to bind to the LDAP server. The default is the password used in the sample configuration.
Enabled
If this box is unchecked, ESF Manager will not load, initialize, or pass requests to this ESM Module. In a future release it will be possible to dynamically enable and disable ESM Modules while the region is running.
Cache limit
This parameter is currently ignored by the ESM Module.
Cache TTL
This parameter is currently ignored by the ESM Module.

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 ES 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 ES 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 ES 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 ES 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 ES 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.

[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.
For 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.

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 ES 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 ES 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 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 Customer Care may ask you to enable this tracing mode to diagnose certain unlikely problems.

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:

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:

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.