Many ES/MTO users are interested in using Microsoft Active Directory (AD) as an ESM. The simplest way to use AD with ES is to treat it as just an LDAP directory. MTO user account information is stored as microfocus-MFDS-User objects in the directory, and user group and resource access control rules are also stored as objects defined by the Micro Focus schema. MFDS and ES are configured to use the "MLDAP" ESM module, which will process Verify and Auth requests by retrieving the appropriate records from AD and comparing them with the request data. For example, during a user sign-on request, the password will be compared against the password hash stored as the microfocus-MFDS-User-Pwd attribute of the microfocus-MFDS-User object for that user.
This configuration is relatively easy to set up (the MLDAP ESM defaults can usually be used, for example) and use. (For more information see the Initial Setup of Enterprise Server Security with Microsoft Active Directory.) However, customers often want tighter integration between ES and AD. In particular, many customers find it more useful to use their existing Windows user definitions in AD as ES/MTO users.
If you want to use your Windows user accounts for ES/MTO users, and you use Active Directory to store the Windows user information for your domain, you can use the configuration described here to enable ES security with Windows users.
More specifically, with this configuration:
For many installations, this provides the best of both worlds: mainframe-compatible security for ES/MTO, but there is only one set of user accounts, and they're managed with standard Windows tools.
The essence of this configuration is two ESM modules. Both use Active Directory, but through different interfaces, and they perform different tasks. The OS ESM module will process user sign-on (Verify) requests by calling standard Windows APIs for user login and (if requested) password change. Windows will handle these calls by communicating with the domain controller, which will read and update Active Directory. The MLDAP ESM module will make LDAP requests to AD to get MTO user attributes and resource access control rules.
Like most ESF security configurations, this one can be used for some or all ES servers and/or for MFDS.
The OS ESM module uses the Windows OS as an external security manager. It is quite simple, with only a handful of configuration options (for passtoken support), and it only supports ESF Verify (user signon) requests. It uses the Windows LogonUser function to check whether the user has supplied the correct password and is allowed to log into the system. Windows security policy rules such as restricted logon hours will be applied automatically, and if a user's password has expired and they have not supplied a new password, the request will be rejected with a must-change-password status. In other words, an MTO signon using this ESM will behave much like a conventional Windows login.
If the user requested a password change, the ESM module will call the Windows NetUserChangePassword function to attempt to change the password. Again, this is essentially the same as a conventional Windows login where the user specifies a new password.
Note that currently MTO restricts the length of usernames and passwords (see the ES documentation for details). Also, usernames or passwords that use non-ASCII characters may not work correctly.
The MLDAP ESM module lets you use an LDAP server as an external security manager. It is relatively full-featured and has a number of configuration options. By default, it implements ES security using LDAP object classes defined by Micro Focus; these objects are used only by ES, and not integrated with security for the OS or other applications.
However, the MLDAP ESM module can be configured to use other LDAP object classes (and containers, so it does not require the default directory hierarchy). By itself, this is not sufficient to completely integrate with Windows security, because the MLDAP ESM module cannot use Microsoft user password attributes; so if you used just the MLDAP ESM with Microsoft user classes, users would have separate passwords for Windows and MTO. In conjunction with the OS ESM, however, the MLDAP ESM will ignore the user password attribute (and other attributes used only for user signon) defined by Micro Focus, if the OS ESM has already verified the user using Windows.
An ESF configuration is defined (in MFDS) as one or more security managers, arranged in a list or stack. A security manager is an ESM module plus its configuration information, and a stack specifies which security managers will be used, and in what order they'll be called.
The configuration presented here will include a security manager using OS ESM and another manager using MLDAP ESM, configured to use the Microsoft user LDAP object class for users (rather than the default Micro Focus user class). These managers will be stacked so that the OS ESM is called first.
Figure 1: Security manager stack
For Verify requests, ESF will call the OS ESM, which will use Windows to authenticate the user, as described above. Then (if the user is successfully verified) ESF will call the MLDAP ESM, which will load the user's MTO attributes from AD.
For Auth requests, ESF will only call the MLDAP ESM, since the OS ESM does not implement Auth. The MLDAP ESM will apply the access control rules defined in AD.
With this configuration, ES will use a combination of Microsoft and Micro Focus object classes in Active Directory.
Figure 2: Objects and attributes
The Windows APIs invoked by OS ESM during Verify requests operate (indirectly) on the Windows security principals defined in AD. (More information on Windows security principals is available from the Microsoft Developer Network and similar resources.) These principals typically use LDAP object classes defined by Microsoft, such as user. Those classes have attributes such as cn (common name), which is the (base) username, and password, which contains the Microsoft hashed password.
In this configuration, the object class used for users will be extended to include attributes defined by Micro Focus. These attributes (which begin with "microfocus-MFDS-") are ignored by Windows, but ES will use them to set session characteristics when a user logs in, such as timeout and operator class. When a user signs on to MTO or MFDS, the MLDAP ESM will retrieve the values of those attributes from the user object.
Also during signon, the MLDAP ESM module will consult the ES user group lists. These are specified with microfocus-MFDS-User-Group objects, and they allow a user to belong to multiple MTO groups. Note that at this time ES does not use Windows user groups to control access to MFDS and MTO resources, even with this configuration.
Since OS ESM is handling the actual user credential verification, some of the attributes that Micro Focus defines for ES users are not used:
Attribute Name | Description |
---|---|
microfocus-MFDS-User-Pwd | Micro Focus user password hash |
microfocus-MFDS-User-Pwd-ExpirationDate | password expiration |
microfocus-MFDS-User-Pwd-MustChange | password must-change flag |
microfocus-MFDS-User-AllowLogon | allow-logon flag |
microfocus-MFDS-User-ExpirationDate | user expiration |
microfocus-MFDS-User-CreateToken | passtoken creation authority (if tokens are enabled in OS ESM) |
microfocus-MFDS-User-UseToken | passtoken signon authority (if tokens are enabled in OS ESM) |
Instead, the Windows password, expiration date, etc will be used. Note that the two passtoken attributes are used unless passtoken support is explicitly configured in OS ESM.
For resource access (Auth) requests, the MLDAP ESM will retrieve MF resource object access control data from microfocus-MFDS-Resource objects in AD.
This section describes one set of configuration options for ES and AD to enable integrated user accounts, with the same user information used for Windows and ES/MTO logins. Many other variations are possible, so you may want to adapt this to the needs of your installation.
You will need a suitable user object class defined in your Active Directory schema. This can be any class that can be used to define Windows security principals. For this example, we will use the user class defined by Microsoft (in the LDIF file MS-user.ldf, included with Active Directory).
You will also need to have populated your Active Directory repository with some users. You may have already defined your Windows domain users in Active Directory, or you may want to define just a few users for a trial implementation.
You will need to have updated the Active Directory schema with the Micro Focus object class definitions for user groups and resource access rules, and created the containers for those objects. Generally, you will also want to have installed the user group and resource access definitions included with the default ES/MTO security configuration, which you can edit later to suit your requirements. Usually all of this is done by installing the default security configuration included with ES/MTO, which is contained in es_default_ldap.ldf and installed using the es-ldap-setup.cmd script. This script is provided as a sample, and may need to be modified for your installation, particularly if you are using the full Active Directory (rather than ADAM) as your LDAP server for Enterprise Server.
The default configuration includes a number of built-in user accounts ( CICSUSER, SYSAD, etc). If you want to use the default configuration, you will need to add these users to Active Directory in a separate operation, as described below in the "Active Directory" section.
This configuration can also be set up with ADAM (Active Directory Application Mode), a reduced-function version of AD provided free of charge by Microsoft and installed with ESF-enabled versions of ES. This may be useful if you are not currently running the full Active Directory, or if you want to test the configuration locally before deploying it to your domain controller.
If you use ADAM rather than AD, user signon will still go through the normal Windows login process, so passwords set for users in ADAM will be ignored. (Users will sign on to MTO or MFDS using their Windows passwords.) However, you will be able to set MTO user attributes using user-class objects in ADAM and see how the ESM modules' configuration options work.
To configure ADAM, see the document "Setting-Up-LDAP-Security-with-Enterprise-Server.html", which is included with ESF-enabled versions of ES. After you have installed the default ADAM configuration, you can create additional users in the "ADAM Users" container with the same names as your Windows users, and use those in the place of AD users in the instructions below.
If you use ADAM, you may have to make some changes to the following instructions. For example, you will have to specify the additional parameters "-s localhost:389" when running the ldifde command to import LDIF files.
For this configuration, you will need to make the following changes to your Active Directory installation:
The first two steps are normally accomplished by running the es-ldap-setup.cmd command script, just as if you were using the default Micro Focus LDAP security configuration (with MTO users defined using the microfocus-MFDS-User class). See "Setting-Up-LDAP-Security-with-Enterprise-Server.html" for more information.
To update the definition of the user class in the Active Directory schema with the MTO user attributes, you can import the LDIF file ms-user-plus-mto.ldf, which should have been included with this document. Typically, you'll use a command line like the following:
ldifde -i -f ms-user-plus-mto.ldf -k -v -j . -c "DC=X" #schemaNamingContext
(Specify this command all on one line.)
For those unfamiliar with the ldifde command, the parameter #schemaNamingContext is a symbolic constant that will be replaced with the DN of the schema in your LDAP directory. The parameter DC=X is a placeholder in the LDIF file that will be replaced with the value of #schemaNamingContext by ldifde as it processes the file. So where the LDIF commands in the file specify "DC=X", they will actually update the LDAP schema.
If you are using a class other than user for your Windows users, you'll have to modify this LDIF file before importing it. See your Active Directory documentation or other LDIF reference material for more information on LDIF files.
If you want to use the predefined users from the default LDAP configuration supplied by Micro Focus, you can import the LDIF file mto-users.ldf, which should have been included with this document. Typically, you'll use a command line like the following:
ldifde -i -f mto-users.ldf -k -v -j . -c "DC=X" user-container
(Specify this command all on one line.) user-container should be the distinguished name (DN) of the LDAP container that holds your Windows users.
If you are using a class other than user for your Windows users, you'll have to modify this LDIF file before importing it. See your Active Directory documentation or other LDIF reference material for more information on LDIF files.
You may want to set MTO user attributes, such as operator class or MTO user timeout, for some of your Windows users. Currently, this must be done manually using an AD administrative tool such as ADSIEdit, or by writing and importing a custom LDIF file. The MTO user attributes are listed briefly below; see the product documentation for more information.
Attribute Name | Description |
---|---|
microfocus-MFDS-UID | Micro Focus user unique identifier; currently unused |
microfocus-MFDS-User-MTO-Priority | MTO user priority |
microfocus-MFDS-User-MTO-Timeout | MTO user timeout |
microfocus-MFDS-User-MTO-OperatorClass | MTO operator class |
microfocus-MFDS-User-MTO-OperatorID | MTO operator ID |
microfocus-MFDS-User-MTO-GroupPrefix | MTO group prefix |
microfocus-MFDS-User-CustomText | MF custom text field; currently unused |
microfocus-MFDS-User-DefaultGroup | MTO default group |
microfocus-MFDS-User-UseToken | passtoken signon authority (if tokens are not enabled in OS ESM) |
microfocus-MFDS-User-CreateToken | passtoken creation authority (if tokens are not enabled in OS ESM) |
Micro Focus plans to provide additional tools to maintain MTO user attributes in future releases.
MTO resource access is typically controlled by rules that apply to user groups rather than to individual users, so you will probably want to add your Windows users to MTO user groups (SYSADM, etc) as appropriate. See the product documentation for more information about MTO user groups and how groups are used.
MTO user groups will be defined in the user group container that was created as part of the initial ES LDAP setup process. Usually this container is called "Enterprise Server User Groups".
Adding a user to a group is simply a matter of adding that user's common name (CN), which is the user's Windows login name (without any domain prefix or suffix), to the microfocus-MFDS-Group-Member attribute of the appropriate group. This is a multi-valued attribute, so it can have any number of user names specified for it. You will need to use an AD administration tool such as ADSIEdit or a custom LDIF file to make this change.
Once you have completed ES configuration, you may be able to use the MFDS user group administration screens to add or remove users from groups. (This depends on appropriate configuration in MFDS, appropriate permissions granted to the user account used by the ESM module, and other factors, so it may not work for all installations.)
Micro Focus plans to provide additional tools to maintain MTO user groups in future releases.
You will need to go to the MFDS Administration Console and create a Security Manager (under Configure Security Options) that uses the OS ESM module ( osesm). OS ESM has very few configuration options, so typically this will just use the defaults for most of the fields:
Figure 3: Configuring security options screen
Note that we've named this manager "Windows", to indicate that it verifies users using Windows. Of course you can use any name you like; you may also want to enter an explanatory Description.
Currently, the only configuration option for the OS ESM module is to enable passtoken support, which can be done by adding these lines to the "Configuration Information" text area:
[Passtoken] Enable=self
Passtokens are useful for providing single sign-on capability between the MFDS and ESMAC administrative consoles, among other things. However, in the configuration described in this document, we will let the MLDAP ESM module manage passtokens, because it can control passtoken permissions on a per-user basis. (The OS ESM module only can enable or disable passtokens globally.) By not enabling passtokens for OS ESM, which is the default, we will let it defer passtoken operations to the MLDAP ESM.
You will also need to configure a Security Manager using the MLDAP ESM module (mldap_esm).
Here you will need to set a number of configuration options, since the defaults are designed for the simple LDAP configuration using ADAM and the Micro Focus user class:
[LDAP] base=DN-suffix user class=user-class user container=user-container group container=group-container resource container=resource-container
DN-suffix | The common part of the DN for your user container, MTO group container, and MTO resource rules container. For example, if your users are in CN=users,DC=somecorp,DC=com, and your MTO containers are in CN=MF,DC=somecorp,DC=com, you could set base to DC=somecorp,DC=com. |
user-class | The LDAP object class used for your users; in this example, it would be user. |
user-container | The DN of the container for user objects, without the "base" suffix, eg CN=users. |
group-container | The DN of the container for MTO user group objects, without the "base" suffix, eg CN=Enterprise Server Groups,CN=MF. |
resource-container | The DN of the container for resource access class containers (which in turn hold resource access definition objects), without the "base" suffix, eg CN=Enterprise Server Resources,CN=MF. |
Your MLDAP ESM Security Manager might look like this:
Figure 4: Security options screen example
Note that we have named this Security Manager "Active Directory", to indicate that it is our general AD-based security manager.
Now you need to create a security configuration for an Enterprise Server region to test the security managers and LDAP installation. You can use the "Default ES Security" configuration for this, but you may wish to set this security configuration just for a single test server initially.
To create the default ES security configuration, which will be used for all ES servers defined by that MFDS that do not have an individual security configuration, go to the "Default ES Security" tab under Configure Security Options. To create a security configuration for just one server, edit that server and select the "Security" tab, then uncheck the "Use default ES Security Manager configuration" option.
Your security configuration will specify the Security Managers you created in the previous two steps, with the OS ESM manager first:
Figure 5: Enterprise server security configuration
To create this configuration, uncheck Use default ES Security Manager configuration (if it is checked) and click Apply. Then click the Add... button under Security Manager List to get the list of security managers. Choose the security manager you just defined for OS ESM (we called it "Windows" above) and click Add. Repeat the process to add the security manager you just defined for MLDAP ESM (called "Active Directory" in the previous step).
Make sure that the OS ESM manager is first in the list. If the security managers end up in the wrong order, use the down-arrow button to the right of the list to switch them.
Set any additional options that are appropriate for your requirements. See the Enterprise Server Security documentation for details.
Click OK to save the security configuration.
To test the security configuration, try to start the ES server you just configured. If it fails to start, look for errors in your MLDAP ESM Security Manager configuration, which is the most likely source of trouble.
When the server starts, try to sign on to CICS or ESMAC with your Windows username and password. You should also be able to change your password from those signon screens. (Remember that you will be changing your Windows domain password!)
You may also want to test resource access control. For example, the CICS transaction CENV should be available to all users (assuming the default ES/MTO security configuration rules are being used), but the CINQ transaction is only available to members of the OPERATOR and SYSADM groups. So with two test users (or one user that signs on using different signon groups, if you are not using the "Use all groups" option), you can confirm whether group permissions are being applied correctly.
Once you are satisfied with your security configuration, you may want to make it the default configuration for all ES servers (if it isn't already), or make it the security configuration for MFDS as well.
To make it the default ES security configuration, go to the Security options in MFDS, then to the Default ES Security tab, and follow the instructions listed above for creating the security configuration.
To make it the MFDS security configuration, you can either do the same on the MF Directory Server security tab, or, if you have made it the default ES security configuration, go to that tab and select the Use default ES Security Manager List option. Note that MFDS security is somewhat more complex than ES security, and consequently you're more likely to run into configuration issues with MFDS.
In this initial release, there are a number of restrictions and usability issues with this security configuration. Most of these should be remedied in later releases. Also, check the Readme file and other materials, as additional utilities may have been included after this document was written.
This release of ES does not include a tool for migrating existing MTO users, defined in the Resource Definition (RDO) file dfhdrdat, to LDAP user classes other than microfocus-MFDS-User. The cas-to-ad tool that is used by es-ldap-setup can only create Micro Focus user objects.
If you have a significant number of MTO users (who are not already Windows users) to migrate, you may want to use the casrdtex utility to export the RDO definitions to a text file, which could be processed into an LDIF file using a scripting language such as Perl.
MFDS includes some administration capabilities for LDAP external security managers, if it is configured appropriately. (MLDAP must be using the ESM in question for its security, and the ESM must be configured with a user ID that has update authority for the LDAP objects. See the MFDS documentation for more information.)
With the configuration described in this document, MFDS can usually be used to administer MTO user groups and resource access definitions. Also, some user administration operations will succeed. However, other operations, such as changing the user's password, will either fail or have no effect, because they will update one of the user attributes which are not used in this configuration.
The OS ESM module uses the Windows LogonUser function to verify a user's credentials (username and password), in the following manner:
If a user is defined in multiple places on that search list, the OS ESM module only tries to authenticate the user in the first one it finds. Normally this will have the expected behavior (much like logging on to Windows conventionally), but in a complex domain configuration situation it could produce confusing results.
Currently there is no provision for forcing a particular domain or changing the search order. Those options may be added in later releases.
ESF does not make any use of Windows user groups. All group-related resource access control is performed using MTO user groups.
Note, though, that Windows security policies which contain group rules that affect user login, such as restricting logins to particular hours of the day, will still have effect for users in those groups, just as they do for Windows login.
For additional information about Active Directory or LDAP, consult your Microsoft documentation.
If you have questions, please contact Micro Focus Support.