Enterprise Server External Security Facility (ESF) Manager

Version 1.22.2

Enterprise Server implements user- and role-based access control (including user authentication and authorization and resource access control) using a tiered, distributed architecture. Security consumers make security requests to a layer called the ESF, modelled after the IBM mainframe z/OS SAF, which uses plug-in modules to relay those requests to whatever External Security Managers customers may have deployed as repositories of security rules. ESMs could be directories or databases, or they could be the security mechanisms built into the OS, or they could be something else entirely.

This design accomodates both mainframe-style security for migrated applications and the wide array of security systems found in distributed environments, and custom security solutions as well. It also lets administrators configure multiple security sources (often useful during migration, or to separate user and resource definitions).

The ESF Manager runs in CAS SEP processes and in the MFDS process. It provides the interface between ES components and External Security Managers (ESMs). Its responsibilities include:

Supplied ESM Modules

ESF Manager is shipped with some ESM Modules:

Public APIs and Interfaces

The ESF Manager provides a number of public APIs:

It defines one public interface:

Message Logging and Error Reporting

Since the ESF Manager is a subsystem that runs within other processes, it reports results through the mechanisms provided by its execution environment. ESF Manager uses four channels for providing status and error information to the outside world:

Private APIs

For internal use only.

Private APIs and modules, used internally, are:

ESF Manager Design and Implementation

Overall Design

ESF has three top-level components: the ESF API, the ESF Manager, and the ESM Modules. The API is the public interface for security requests, the ESM Modules communicate with external security managers to satisfy requests, and the Manager provides glue, ancillary functions, and enhancements such as result caching.


The ESF Manager is a loadable object (DLL or CSO). It's loaded (implicitly or explicitly) by a caller, which may be a SEP process in CAS or MFDS. Note that under CAS each SEP has its own instance of the ESF Manager; for performance, these share a single cache. The caller initializes the ESF Manager by calling safmgr(), setting the operating environment and configuring the manager and its ESM Modules.

Once the manager has been initialized, ESF consumers (functions or subsystems in the ESF caller) can use the ESF API. The ESF API is the public interface for making security requests, such as validating credentials and establishing a security context (eg checking a username and password and assigning a user account to the current process), and checking to see whether a type of access to a protected resource is allowed in the current context (eg checking to see if the active user account has write access to a given file).

ESM Modules are loadable objects which the manager loads and invokes to make the actual security decisions. Typically they relay security requests to an external security manager (which could be an OS facility, a repository of security rules such as an LDAP directory or SQL database, or any other source of security decisions or rules).

Length and Character Set

Many ESMs support long usernames, and usernames with non-ASCII characters. Currently, ES/MTO is limited to mainframe-style usernames, with no more than 8 characters, and only plain ASCII characters are allowed.

Micro Focus plans to introduce a feature called "name mapping" in a future release of ES which will let ESM Modules and customer-written user exit handlers convert between long / non-ASCII usernames and the 8-character usernames required by MTO. Customers who are interested in this feature should contact their Micro Focus Support representative.

User Groups and the Signon Group

The request that is passed to an ESM Module's Verify procedure to authenticate a user includes the user's credentials, which are usually a username and a password. It may also receive an optional signon group string, which is a short (up to 8 character) string that names a user group the user belongs to. This will become the user's signon group for the session, if authentication succeeds.

User groups are simply lists of users. (Their actual definition is a matter for the ESM that controls the user accounts in question.) They're useful for assigning access rights to many users at once, and for implementing role-based security, where users are assigned "roles" such as developer, administrator, and so on, and access rights are associated with roles rather than individual users.

Typically, ESMs let users belong to more than one group, and each user has a default group which is that user's primary group. With some ESMs, users always have all of the rights of all the groups they belong to. This is how group membership works in Windows and Unix. With these ESMs, the signon group is irrelevant.

Other ESMs, however, may only give a user the access rights of one group at a time. This mimics some mainframe security configurations, and also may provide a performance benefit. With these ESMs, users have only the rights of their default group unless a different signon group is specified in the Verify call. (Sign-on facilities such as the MTO CESN transaction provide a field where an interactive user can specify a non-default signon group.)

The MLDAP ESM Module supports both modes of operation. See the documentation for configuring the module for more information.


Some ESM Modules support a feature called passtokens, which let one ES component pass a user's identity to another component without sending the user's full credentials (such as a password). With passtokens, a user can sign on with their password once and then have their authenticated identity transferred automatically to another security domain.

ES currently can use passtokens when an administrator is switching between the MFDS and ESMAC user interfaces, and for CICS Transaction Routing and Function Shipping between ES regions.

The passtoken feature is not supported by all ESM Modules. It can be disabled for enhanced security.

The chapter ESF Passtokens discusses passtokens in more detail.

Secondary Components

There are some secondary components in the ESF Manager worth noting.

Peripheral Components

The ES security subsystem includes some secondary components outside the ESF Manager proper:

Manager Architecture Detail


Administrative actions such as initialization and administrative update go to the ESF Management API; security requests to the ESF API. Within the manager are components for request processing, result caching, and the ESM interface, plus support functions which isolate the manager from differences in its operating environments.

ESF Manager Call Flows

Management Calls

The most important management calls into the ESF Manager are the initialization, termination, and administrative update functions.


Before using ESF Manager, the caller must initialize it. During initialization:

  1. The caller invokes the safmgr() function, passing configuration information (SafInit structure)
  2. safmgr processes the configuration items that apply to the manager (as opposed to individual ESM Modules)
  3. safmgr calls the initialization functions for various components, including the cache (SafCacheInit()) and environmental services (SafEnvInit())
  4. safmgr calls the ESM interface to load each of the configured ESM Modules
  5. The ESM interface calls each ESM Module in turn to initialize it
  6. Each ESM Module processes its configuration data and performs any appropriate initialization of its own, such as contacting its associated ESM

When a thread or process that has been using ESF Manager is about to exit, it should notify ESF Manager so that it can perform any necessary cleanup:

  1. The caller invokes the safterm() function, indicating whether it is the current thread or the process which is terminating
  2. For process termination, safterm invokes each ESM Module's Exit procedure
  3. safterm informs the Cache Manager and Environmental Support components of the termination event
Administrative Update

The administrative update call is used to inform ESF Manager that the security configuration has changed. This may be a change in the configuration of the ESF Manager itself (for example, enabling or disabling an ESM Module), or it may be a notification that an administrative update has been made to an ESM (such as a new user being added).

For an administrative update:

  1. Some external action tells the caller to notify ESF of an ESM administrative update. This might be an "update service" provided by the caller, or it might be an action performed in the caller's UI (if it has one), or something else.
  2. ...


The two most common ESF API calls are VERIFY, which validates security credentials and assigns a security context (this is typically a user login), and AUTH, which tests whether a task has authority to perform an action against an object (typically, whether it has a particular type of access to a protected resource such as a file).

For a VERIFY call:

  1. The consumer calls the ESF API with the credentials to be verified.
  2. The ESF API module relays the request to the manager's Request Processing component.
  3. Request Processing checks the cache to see if there is a cached response which has not expired or been marked invalid. If so, it updates the use count on the associated ACEE, if one exists, and returns the cached response.
  4. If there is no valid cached response, Request Processing forwards the request to the ESM Interface.
  5. The ESM Interface will invoke each of the configured ESM Modules in turn until one returns a definite response (Allow, Deny, or Fail, which is treated as a denial; a module can also return Unknown, which is a don't-care response and causes the ESM Interface to continue with the next ESM Module). If no ESM Module returns a definite response, the request is denied.
  6. Typically, each ESM Module will communicate with an external security manager to determine its response.
  7. If an ESM Module decides to allow the request, it may create an ACEE for the user if none currently exists. Some ESM Modules do this in order to set private data in the ACEE for their later use in AUTH processing.
  8. If it got a definite response, Request Processing will add a cache entry for it. If it got an Allow response, Request Processing will create an ACEE for this user (if none currently exists; otherwise it will increment the use count).
  9. Request Processing will return the result to the ESF API, which will return it to the consumer.

The AUTH call is similar except that no ACEE creation is involved.

Michael Wojcik
Randy Witek
Stu Childre
Micro Focus (IP) Limited