Configuring Active Directory for Enterprise Server Security

This document guides you through the process of configuring Microsoft Active Directory (AD) for Micro Focus Enterprise Server (ES) security. It shows you how to extend the AD schema (the definition of LDAP object classes and attributes) to hold the information ES uses to verify users and authorize access to resources, and how to add the objects used by ES security to AD's LDAP directory.

UNIX appears in bold at the start of a paragraph that applies to performing the procedure using a Server Express product rather than Net Express.

1. Prerequisites - Software

• ldifde.exe, the Microsoft LDAP utility that is shipped with ADAM. Note that Windows Server includes ldifde.exe, but it's an older version that may not have the necessary features. You want the version that's in %WINDIR%\ADAM, so set your PATH accordingly.
• A Net Express 5.0 or Server Express 5.0 environment at Websync 03 or later, for MFDS and the cas-to-ad utility.

  UNIX The cas-to-ad step is optional; if you don't need to import existing MTO users, you can use a UNIX SX5.0 WS03 or greater environment instead, and run the ldifde commands on the domain controller.

• The following LDIF (LDAP data) files, which should be provided by Micro Focus with these instructions, if they are not in your WS03 product installation:
  • mf-partition.ldf
  • mf-ad-containers.ldf
  • ms-user-plus-mto.ldf
  • es_default_ldap.ldf and es_default_ldap_msuser.ldf (only one of these will be used)

Command Window and PATH

Since some of the commands listed below are part of Net Express, we recommend starting with a Net Express Command Prompt Window.

After opening the window, add the ADAM installation directory to your path:

path %windir%\adam;%path%

The mfds and cas-to-ad commands need to be run from a system with Net Express installed. The ldifde command can be run on the domain controller instead, if you find that more convenient.

UNIX To use Server Express instead of Net Express for this procedure, you will need a terminal session with the appropriate environment settings to run Server Express binaries. The cas-to-ad command is not currently supported in Server Express; if you have CICS SNT users you wish to import into Active Directory, contact Micro Focus Support for more information.

Establishing a Work Directory and Copying Files

We recommend using a creating and using a new work directory for this procedure, as that makes it easier to keep track of the files you use and create:

mkdir mf-ad-setup
cd mf-ad-setup

After creating your work directory, you will need to copy the LDIF files into it. These files are in the Base\Bin directory of your Net Express product installation (by default, %SystemDrive%\Program Files\Micro Focus\Net Express ver.)

UNIX If these files are not included with the product, please contact Micro Focus Support.

ldifde Notes

Several of the steps in this process use the Microsoft ldifde utility, a relatively complex command-line utility with many options. You may want to read the documentation for ldifde that comes with ADAM.

Here are some tips for using ldifde:

• We use ldifde to read an LDIF file (with a .ldf extension) and update AD with the objects listed in the file. LDIF files are text files and can be edited in Notepad.
• Many of the ldifde command lines shown below use the "-c" option, which takes two strings as parameters, and changes the first string to the second wherever it appears in the input. So "-c DC=X DC=mydom,DC=com" will change "DC=X" in the .ldf file to "DC=mydom,DC=com". That lets us customize the information in the .ldf file for your installation.
• You can copy the .ldf files to your AD server and run ldifde there, or you can run it on a system with Net Express installed and update AD remotely.
• ldifde has to bind (log on to) AD in order to make changes to the directory. If you are not logged on as an authorized AD user, you can add "-b username domain password" to the ldifde command line.
• When we show ldifde command lines below, we use the "-s servername" option to tell ldifde the hostname of the AD server. If you're running on the AD server, or if your AD server is the domain controller for the domain that you are running in, you can leave off the "-s servername" option.
• Each time you run ldifde (with the "-j ." option), it will create an ldif.log file in the current directory. If there are errors or warnings, it will create an ldif.err file as well. If the files already exist, they will be overwritten. We recommend you rename the log file after each ldifde run (eg to ldif-1.log, ldif-2.log, etc) so you can send them to Micro Focus Support if you have problems. If an ldifde command fails, you can check the log and error files for more information.

A typical ldifde command will have these parts:

2. Prerequisites - Information

You will need to know:

• A user account authorized to make AD schema changes (shown as username and password below).
• The location of the AD server (shown as servername below).
• The user class you will use. This can either be microfocus-MFDS-User (supplied by Micro Focus), if ES users will be separate from Windows users, or user (supplied by Microsoft and modified by Micro Focus) to use your Windows user accounts for ES. (Shown as userclass below.)
• The DN of the AD domain (shown as domain-DN below). Normally, this will be the fully-qualified domain name of the AD host, minus the hostname, with each segment of the name listed as a separate DC element, so for example server.dept.mydom.com would use DC=dept,DC=mydom,DC=com. If you are using ADAM, you may want to use the default domain DN for ES LDAP data, which is "CN=Micro Focus,CN=Program Data,DC=local".
• The DNs of the containers for users, ES user groups, and ES resources, if you are going to use something other than the default values. ES groups and resources are used only by ES, so we recommend you use the defaults (located in "CN=Micro Focus,CN=Program Data") for their containers. If you are using the Micro Focus user class (microfocus-MFDS-User), you can use the default ES user container ("CN=Enterprise Server Users,CN=Micro Focus,CN=Program Data", below the domain-DN) as well.

  On the other hand, if you want to let existing Windows users sign on to ES without creating separate ES user accounts for them, you will need to configure ES to use your existing user container in AD (usually "CN=Users"). Use that for your user container (shown as user-container below) in the following commands as well.

3. Prerequisites - Backups

Before you make any AD modifications we recommend you back up your AD schema and Directory Information Tree (DIT). You may already have standard procedures for this. If not, you should make a backup of the contents of the %WINDIR%\ntds directory to another location. This way you can drop the server (assuming Server 2003) into "Directory Server Recovery" mode and restore your previous AD data if you ever have to.

Note that the contents of that directory are in use when the server is running, so ordinary copy commands generally will not work. Some ways you can back up your AD information:

• make the backup in Directory Server Recovery Mode (press F8 while booting the AD host to enter Recovery Mode)
• use a backup utility such as the Backup applet that comes with Windows, or the ntbackup command-line equivalent (this does not require a reboot)
• use a utility to schedule a copy when the system is rebooted, such as SysInternals movefile (and then reboot to effect the copy)

Consult your Windows documentation for more information.

You may also wish to export your current LDAP hierarchy to an LDIF file for later reference, using a command like:

ldifde -f export-file -s servername -r "(objectclass=*)" -d "CN=Schema,CN=Configuration,domain-DN"

4. Extend the AD Schema

Create the Micro Focus AD format schema extension LDIF file (enter this and all other commands on a single line):

mfds -L "CN=Schema,CN=Configuration,domain-DN" 1 mfds-schema.ldf

This will create the file mfds-schema.ldf. Use the latest WS03 build MFDS (1.06.11 or later) for this operation to ensure you have the latest schema definitions.

Import MF schema extensions into AD:

ldifde -i -f mfds-schema.ldf -s servername -k -j .

If you are updating a remote AD server, this command may take a minute or two. When it's done, remember to rename the log files, as described above.

ldifde -i -f ms-user-plus-mto.ldf -s servername -k -j . -c "DC=X" "CN=Schema,CN=Configuration,domain-DN"

5. Create LDAP Objects

Containers

Create the "Micro Focus" partition. You will need to edit the mf-partition.ldf file first if you do not want to use CN=Micro Focus,CN=Program Data as the container for the ES definitions.

ldifde -i -f mf-partition.ldf -s servername -k -j . -c "DC=X" "CN=Program Data,domain-DN"

You can copy the .ldf files to your AD server and run the command there, or run it from a system with Net Express.

Next create the standard MF containers. If you want to use a different container for users, user groups, or resources, you may need to edit the mf-ad-containers.ldf file first. You may also have to edit some of the other .ldf files or make changes to some of the commands that follow.

We recommend using the standard containers, with one exception: if you are using Windows users for ES users, you will want to use the existing AD user container. You don't need to do anything different in this step for that.

The command to create the standard MF containers is:

ldifde -i -f mf-ad-containers.ldf -s servername -k -j . -c "DC=X" "CN=Micro Focus,CN=Program Data,domain-DN"

ES/MTO Objects

Import the predefined ES/MTO users, user groups, and resource access control definitions from the default LDAP configuration into your AD repository. (Predefined and existing MFDS users will be imported in a separate step below.) The LDIF file you use depends on the user class you have chosen.

Run only one of the following two commands.

• If you are using the default, ES-only microfocus-MFDS-User class:

  ldifde -i -f es_default_ldap.ldf -s servername -k -j . -c "DC=X" "domain-DN"

  es_default_ldap.ldf uses the default Micro Focus containers for ES users, groups, and resources.

• If you are using the Microsoft user class, so that Windows users can also be ES users:

  ldifde -i -f es_default_ldap_msuser.ldf -s servername -k -j . -c "DC=X" "domain-DN"

  es_default_ldap_msuser.ldf uses the default Micro Focus containers for ES groups and resources, and the default AD user container (CN=Users) for users.

When you run this command, you will probably get warnings about objects that do not exist. You can ignore these warnings. They are generated because these .ldf files try to delete any existing instances of the objects they create.

Existing ES/MTO Users (Optional)

Import existing ES/MTO users from a CAS RDO (Resource Definition Online) file. You can skip this step if you have not defined any MTO users in the CICS Sign-On Table (SNT) in ESMAC, or if you plan to migrate those users manually. You can also perform this step later.

To import those users, use the Micro Focus cas-to-ad utility. This program reads a CAS RDO file, adding each user it finds to AD. (It will also try to add the CAS system users such as CICSUSER, but they were already added in the previous step.) The basic command is:

cas-to-ad -u - -d "domain-DN" -c "user-container" -l servername -U userclass

Be sure to enter the options just as shown above - they are case-sensitive. Ignore any warning messages about users that already exist.

The user-container parameter will typically be either "CN=Enterprise Server Users,CN=Micro Focus,CN=Program Data" if you are using microfocus-MFDS-User, or "CN=Users" if you are using Windows users (the Microsoft user class).

The servername parameter can also be specified as a URL, as in "-l ldap://servername". If your LDAP server uses a non-default port, you can specify that as well.

You can also use LDAP-over-SSL by using an "ldaps" URL: "ldaps://servername". (Requires cas-to-ad 1.4.0 or later.) This will only work if your server supports LDAP-over-SSL (this is usually true with Active Directory running on newer Windows domain controllers). Also, the LDAP client library will have to verify the Active Directory server's certificate, which may fail if your server uses a certificate signed by an unusual Certification Authority. If you want to use LDAP-over-SSL but cas-to-ad fails to connect to AD, contact your AD administrator for a copy of the signing certificate and instructions for installing it in your client system's trusted root certificate store.

cas-to-ad will look for the RDO file (dfhdrdat) in the directory specified by the environment variable TXRDTP. If that environment variable is not set, cas-to-ad looks in the current directory, then in Base\files\sys under the Net Express installation directory. To specify a different location, add "-r path" to the command line.

If cas-to-ad complains that it can't open your RDO file, it may be in use. Copy dfhdrdat.* to a temporary directory and use the -r path option to tell cas-to-ad to use the copy.

The "-u -" option binds (logs on) to AD as the current Windows user. If you are not logged in as a user with the necessary authority, or if you are running cas-to-ad remotely from a system in a different domain, you will need to specify a different user ID. You will also be prompted for a password, unless you specify it on the command line with the -p option. For example:

cas-to-ad -u domain\Administrator

or

cas-to-ad -u "CN=Administrator,CN=Users,domain-DN"

or to avoid having to enter the password when prompted:

cas-to-ad -u domain\Administrator -p password

Run "cas-to-ad -h" for a usage message to see other options.

Note that in some cases AD may not let you set passwords on unencrypted connections, so this command may fail if you use the -u option. This should be fixed in a future release; for now, if you encounter this problem, run cas-to-ad on a system in the same domain as the AD server. You can also get an encrypted connection by using LDAP-over-SSL, as described above.

Create MFDS Objects LDIF File

Extract MFDS users, groups, and resources from your existing MFDS configuration:

mfds -e "domain-DN" "user-container" "CN=Enterprise Server User Groups,CN=Micro Focus,CN=Program Data" "CN=Enterprise Server Resources,CN=Micro Focus,CN=Program Data" 1 mfds_users.ldf userclass

Set domain-DN, user-container, and userclass as in previous commands. Be careful not to confuse user-container (CN=...) and userclass (microfocus-MFDS-User or user), which is easy to do.

(If you are using ADAM rather than AD, you can specify "0" instead of "1" before mfds_users.ldf. This will produce a slightly different .ldf file that will tell ADAM that the passwords for the MFDS users do not expire.)

This command will create mfds_users.ldf.

Set MFDS User Passwords

If you are using the microfocus-MFDS-User object class for your users, MFDS will set their password attribute (microfocus-MFDS-User-Pwd) in mfds_users.ldf using the password hashes it has for those users. This means MFDS users will continue to have the same passwords.

If you are using the user object class for your users, currently MFDS does not set user password attributes, which means the newly-imported MFDS users have no passwords. Until this is fixed, you will either need to edit the mfds_users.ldf file before importing it and add the appropriate password attributes, or you will have to set the passwords manually after the users are imported:

• To set a password in the LDIF file, add this attribute to the user: userPassword: password (AD will automatically encrypt this password.)
• To set a password manually, you can use the Microsoft ADSIEdit utility (%WINDIR%\ADAM\ADAM-ADSIedit.msc): right-click on a user and choose "Reset Password".
• You can also use normal Windows system administration mechanisms to set user passwords, since the user class uses standard Windows passwords.

At a minimum, you will need at least one MFDS administrative user with a password (such as schemaadmin), so you can log on to MFDS. Typically, you will also want at least one user with "modify" authority for use by ES and MFCS; this will usually be an MTO user as well, since it will need MTO authority to start and stop the region (if security is configured for the ES server). The SYSAD user is usually used for this purpose, at least during initial installation and verification. (You can delete these users later.)

If you want to continue using unsecured ES regions, you will need to set the passwords for the mf_cs and mf_mdsa predefined users.

By default, the passwords for MFDS predefined users are the same as their usernames.

Once you have successfully configured ES LDAP-based security for MFDS, you may also be able to use MFDS to set passwords, depending on details of your configuration.

Import the MFDS Objects

ldifde -i -f mfds_users.ldf -s servername -k -j .

Note that since you specified your domain-DN when creating mfds_users.ldf, you do not need a -c option for this command.

6. Final User Tasks

Some user attributes may need to be set manually (using AD administration tools or hand-written LDIF files) after importing the ES definitions. This document doesn't describe those in detail, but here is an overview.

The companion document Configuring Active Directory Users as ES Administrators (LDAP-ES-Admin-Setup.rtf) explains some of this process in more detail.

Set MTO Attributes for Windows Users

If you are using your existing Windows users as ES users, you will probably want to set some of the new MTO-specific user attributes for at least some of them. For example, the microfocus-MFDS-User-MTO-Timeout attribute sets the MTO timeout for that user. See the ES/MTO documentation for more information.

You will also probably want to add existing users to MFDS and MTO user groups to reflect their roles (developers, administrators, etc). Note these are ES user groups, not Windows user groups, so you change them by modifying your AD repository with an LDIF file or a tool such as ADSIEdit. The ES/MTO documentation includes information on ES user groups. For example, you can add Windows users to the #DSAdmin group in Enterprise Server User Groups to make them MFDS administrators; to give a user permission to start and stop ES regions, set their default group attribute microfocus-MFDS-User-DefaultGroup to SYSADM.

You can make these changes manually using a tool for administering AD data, such as ADSIEdit. For bulk changes, though, you will probably want to create LDIF files to update multiple users, groups, or resources at once.

Enabling ES Predefined Users

If you use the Microsoft user object class, AD will probably disable the new predefined ES users. If you want to use ES predefined users such as SYSAD (for starting and stopping ES regions) and schemaadmin (for MFDS administration), you will need to enable them. On your AD server, open the AD user manager (Active Directory Users and Computers) console. Select one or more users in the right pane, then choose Action > Enable Account from the main menu.

Disable Password Expiration for ES Users

The Microsoft user object class uses Windows passwords, which means normal Windows password rules in the domain security policy apply, including password expiration. Some administrators would prefer that the passwords for the predefined ES users (such as mfuser and SYSAD) not expire, since these are not normal login accounts. You can edit these users using standard Windows user administration tools and set the "Password does not expire" option for them.

Remove Predefined Users

Some administrators may choose to delete the predefined ES users after installation, and use only existing Windows user accounts for administering ES and signing on to MTO. We recommend doing this only after verifying basic ES operation with security enabled, since that will make it easier for Support to diagnose any problems.

You should not remove the default user accounts CICSUSER, JESUSER, IMSUSER, and mfuser, unless you specify different default accounts in the ES configuration (see the ES/MTO documentation for details). You can disable these accounts in Windows to prevent anyone from using them to log on to Windows.

If you remove the mf_cs and mf_mdsa users, you will not be able to run nonsecured ES servers using the default options.

Be sure you have another account for MFDS administration before removing the schemaadmin user.

Also, if you used "CN=Users" as your user container above, you can remove the empty "CN=Enterprise Server Users" container.

7. Configure ES Security

To use the ES security information in LDAP, you will need to configure ES security:

• Create one or more Security Managers to connect to your LDAP server. You need to set various attributes for these managers:
  • The module name to mldap_esm
  • The connection path to ldap://servername (or ldaps://servername to use an SSL-secured connection, if your LDAP client and server support SSL)
  • The authorized ID and password to the name (usually a DN) and password of an account that has at least read permission for the ES objects in the directory
  • In the Configuration Information area, you will probably need to add a number of directives to alter the default behavior, for container DNs, user class, and so forth. For example, when using Windows users for ES, a typical configuration would be:

    [LDAP]
    base=domain-DN
    user container=CN=users
    group container=CN=Enterprise Server User Groups,CN=Micro Focus,CN=Program Data
    resource container=CN=Enterprise Server Resources,CN=Micro Focus,CN=Program Data
    user class=user
    
    [Verify]
    mode=bind
    password type=AD
    

• Alter the security configuration for MF Directory Server, ES Default Security, and/or specific ES servers to use your new Security Manager

See the product documentation for more information. (In particular, see the documentation for the MLDAP ESM Module for information on configuring the module to match your AD setup.)