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.
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.
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.
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.
esfadminutility) 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.
The MLDAP ESM Module supports two kinds of wildcards:
Wildcards can appear in two places:
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
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.
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:
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".
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.
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:
group(eg "ADMIN group")
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.
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
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.
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.
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).
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 permissions are a strict hierarchy of six levels:
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 (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.
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:
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.
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
The other fields of the Security Manager screen are used by the MLDAP ESM Module as follows:
localhost:389(389 is the well-known port for LDAP).
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.
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
Here are the various configuration sections, and the options that can be set in each section.
wldap32.dll, the Microsoft LDAP client. On Unix, the default is
openldap, which is the Micro Focus port of the OpenLDAP client library.
libldap.a, the LDAP client available from IBM for AIX.
version=2 | 3
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.
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 Resourcescontainers. Note: If your user, group, and resource containers are in separate branches of your LDAP repository, you can set
Baseto an empty string and use full DNs for
group container, and
user class=LDAP class name
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
Baseabove) 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
group class=LDAP class name
group container=partial DN
CN=Enterprise Server User Groups.
resource class=LDAP class name
resource container=partial DN
CN=Enterprise Server Resources.
bind=simple | negotiate | es-user
simplemethod 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.
negotiatemethod 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).
es-usermethod 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.
search scope=child | tree
childwill search only the first level within the specified user, group, and resource containers.
treewill search the entire LDAP hierarchy below the container. Using
treecan significantly impact performance, but is useful for directories that organize users or other LDAP records into separate containers.
one-level(the technical LDAP term for this scope) are synonyms for
subtreeis a synonym for
referrals=yes | no | default
search scopeabove) if referrals are enabled.
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.
default, for compatibility with earlier versions of the MLDAP ESM Module, unless you have
search scope=treealso configured, in which case the default is
maxgroups, unless Federation is explicitly disabled. This requirement is enforced by the module; you will get a warning if your configuration specifies different
maxgroupssettings for different instances of the MLDAP ESM Module.
bindverify 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-ExpirationDateattribute), 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).
microfocus-MFDS-User-Pwd-ExpirationDateattribute 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
esfadminutility with the
ALTUSERcommand and the
esfadmin -uADMIN -pADMIN -U"cn=..." -Pxxx altuser user=SYSAD passexp=20091231
required=list of classes
punctuation. Class names should be separated by whitespace and/or commas.
complexity=1would 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.
default=none | self
selfchanges the default behavior to allowing the creation and use of self-only passtokens.
mode=MF-hash | bind
MF-hashmethod retrieves the value of the
microfocus-MFDS-User-Pwdattribute, 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.
bindmethod 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.
password type=MF | AD | MD5 | plain | compatible
MFcreates a secure verifier (a salted cryptographic hash) of the password, and sets it as the value of the
microfocus-MFDS-User-Pwdattribute. This is suitable if you are using the microfocus-MFDS-User class for your ES users. It corresponds to the
MF-hashpassword-verification method described above.
ADsets the attribute
unicodePwdto 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
bindpassword-verification method described above, if you are using Active Directory.
MD5computes the MD5 hash of the password and sets it as the value of the
userPasswordattribute, using the syntax specified by RFC 2307, which is not standard but widely supported by LDAP servers. It corresponds to the
bindpassword-verification method if you are using an LDAP server which supports this password type, such as OpenLDAP.
userPasswordattribute 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
userPasswordan "alias" for
unicodePwd; if that option is enabled, this method can be used to set passwords in Active Directory or ADAM.
compatiblesetting first tries to set
unicodePwdusing the Microsoft syntax, then tries to set
MD5method. This will usually work when the ESM module is configured to use the
bindverification method: if the LDAP server is Active Directory, the
unicodePwdattribute setting will work, and if another LDAP server is being used, there won't be a
unicodePwdattribute so the more common
userPasswordattribute will be set instead.
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.
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.)
authrules, it can also be a group name followed by the word
group. Wildcards are allowed.
verify, there are no parameters
auth, this must be
classis a resource class name (eg "TCICSTRN"); wildcards are allowed
entityis a resource entity name (eg "CINQ"); wildcards are allowed
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.
verify:SYSAD:denywill trace Verify (signon) requests where the SYSAD user is denied
auth:SYSADM group:TCICSTRN:C*:allowwill trace Auth (authorization) requests where a member of the SYSADM group requests access to any resource in the TCICSTRN class with a name begining with C, and the request is allowed
Filtered tracing is useful in isolating issues on busy systems, where normal tracing would produce excessive output. It does affect performance somewhat, since each request must be examined to see if it matches a trace rule.
Be sure to use a double asterisk (
**) in wildcard specifications for dataset names, if you want them to match qualifiers. For example, use
auth:SYSAD:DATASET:**:deny to see all cases where SYSAD is denied access to a dataset.