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-User-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:

In the names of resource objects in the LDAP directory. When a resource object in the directory has a name with a wildcard (sometimes called a generic name), its ACL applies to all the resources with a name that matches that pattern, unless another resource definition with a more-specific name (see Match Rank) exists.

In user and group names in an Access Control Entry. Such an entry will apply to all users or groups with names that match the pattern, unless another ACE with a more-specific name (see Match Rank) exists in that ACL.

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 reosurce 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:

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.
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".
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:

setting is allow or deny
actor is the name of a user, a pattern with one or more wildcards (see Wildcards) that will be matched against the user's name, or a group name or wildcard pattern followed by a space and the word group (eg "ADMIN group")
action-1 through action-n are permission tokens:
- none
- execute
- read
- update
- add
- delete
- control
- alter
- all

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.

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:

no access
execute
read-only (plus execute for programs)
update (adds ability to write)
control (adds the ability to delete, etc)
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:

execute (used for starting and stopping servers, etc)
read
update (change, but not add or delete)
add
delete
control (not currently used by MFDS)
alter (not currently used by MFDS)

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:

Higher-ranked rules override lower-ranked ones.
Within the same rank, user rules override group rules.
For rules of the same rank for the same actor (user or group), deny rules override allow rules.
For MTO resources:
- For allow rules of the same rank and actor, the highest specified access level applies.
- For deny rules of the same rank and actor, the lowest specified access level applies (because higher levels implicitly include lower ones; so if read access is denied, update access must also be denied).
For MFDS resources:
- Allow rules of the same rank and actor are combined (set union).
- Deny rules of the same rank and actor are combined.

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:

if this entry applies to this user
- if this is an allow rule
  - if this is a higher-ranked rule than any we have processed so far
    - reset the current allowed-access level and permission set for the user
  - for each action specified in the entry
    - if this specifies a higher level of access
      - update the user's allowed-access level
    - add the specified action to the user's allowed-permissions set
- else (this is a deny rule)
  - if this is a higher-ranked rule than any we have processed so far
    - reset the current denied-access level and permission set for the user
  - for each action specified in the entry
    - if this specifies a lower level of access
      - update the user's denied-access level
    - add the specified action to the user's denied-permissions set
if this entry applies to an applicable group
- do the same as above, but updating group-allow and group-deny variables

After processing all of the ACL:

if no applicable entries were found, continue on with the next rule
if this is an AUTH (MTO resource, mainframe-style access levels) request
- if group entries were found but no user entries, use the group entries
- if user entries were found but no group entries, or the user entries are at the same or higher rank than the group entries, use the user entries
- if this is an access request
  - if there are deny entries at the same or higher rank than the allow entries, and the deny level is less than or equal to the requested level
    - deny the request
  - else if the requested level is greater than the allowed level
    - deny the request
  - else
    - allow the request
- else (this is a permissions query)
  - if there are deny entries at the same or higher rank than the allow entries
    - reduce the allowed level to one below the lowest denied level (eg if update is denied, reduce the allowed level to read)
  - return the allowed level
else (this is an XAUTH, MFDS resource, permissions-set request)
- compare the ranks of user-allow, user-deny, group-allow, and group-deny permissions
- the highest of the four determines whether user rules outrank group rules, or vice versa (if user and group are equal rank, user wins)
- compute the final set of permissions as
  - add lower-ranked allowed permissions
  - remove lower-ranked denied permissions
  - add higher-ranked allowed permissions
  - remove higher-ranked denied permissions
- if this is an access request
  - if the requested permissions are all in the result set
    - allow the request
  - else
    - deny the request
- else (this is a permissions query)
  - return the result set

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. (In principle, you should be able to create multiple MLDAP-ESM configurations for the same server, for example if you use one LDAP server for user authentication and another for resource access rules. Unfortunately this does not work correctly in the current product, but should be fixed in an upcoming release.)

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.

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.

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

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

[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 of these.) 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".