Enterprise Server External Security Facility (ESF) Manager

Version 2.0.0

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:

• Providing the ESF API, which other components invoke to perform security tasks such as verifying user credentials and authorizing access to protected resources.
• Loading and invoking ESM Modules, which are plug-ins that communicate with actual ESMs.
• Managing a cache of security query results.
• Maintaining configuration information for ESM Modules and the ESF Manager itself.
• Abstracting infrastructure APIs so that ESM Modules work identically in CAS and MFDS.

Supplied ESM Modules

ESF Manager is shipped with some ESM Modules:

• The CAS ESM Module (casesm) uses the pre-ESF ES CICS security definitions as the equivalent of an external security manager.
• The OS ESM Module (osesm) uses the host operating system to verify users; it does not provide resource access control (but can be combined with other ESM modules that do).
• The MLDAP ESM Module (mldap_esm) uses an LDAP directory as its external security manager.

Public APIs and Interfaces

The ESF Manager provides a number of public APIs:

• The ESF API is used by ESF consumers to make security requests, such as authorization checks.
• The Manager API is used to control the ESF Manager; it includes an initialization function, configuration update notification support, and so forth.
• The ESM Module API is a set of services used by ESM modules for infrastructure functions like retrieving configuration information and allocating shared storage.
• Various User Exit Points are provided.

It defines one public interface:

• The ESM Module Interface is an interface specification that ESM Modules implement in order to be invoked by the Manager.

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:

• The Manager's APIs have an assortment of return codes and other output parameters, which are discussed in the detailed descriptions of those APIs.
• The ESF API includes a STAT function which solicits current status information from the Manager and its loaded ESM Modules.
• ESF Manager logs a number of status and error messages through a facility specific to its execution environment: the CAS Console Log or the MFDS Journal. See ESF Manager Messages for more information.
• ESF Manager also reports security-relevant events to the ES Audit Facility.

Private APIs

For internal use only.

Private APIs and modules, used internally, are:

• The Request Processor handles requests made to the ESF API.
• The Processing Environment API is a set of cover routines for services that depend on the environment (eg CAS or MFDS) in which ESF Manager is executing.
• The Cache API handles internal result caching for ESF requests.

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.

Passtokens

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.

• To improve performance, the manager caches security results. Queries are first checked against the cache; if a valid result is cached, the manager returns it rather than invoking the ESM Modules. (Cache entries have a configurable time-to-live, after which they're ignored and opportunistically discarded. Cache entries can also be invalidated by administrative action.) See ESF Caching for more information.

• The ESF Manager design specifies User Security Exits will be provided at appropriate points in request and response processing, though at this time none of those points has been determined.

  See also:

  saf-exit.c

Peripheral Components

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

• A number of support functions are provided by the operating environment.

  See also:

  saf-env.c

• The ACEE (Access Control Environment Element) structure is a z/OS data structure that is partly emulated under MTO. It contains security information for the executing task, such as the current MVS-style username. The contents of the ACEE are not used by ESF in making security decisions, but an opaque object called the "ACEE User Token" is used by the ESF API to associate a security request with the current security context. The ESF Manager and ESM Modules allocate, populate, and free ACEEs, though the actual ACEE table management may be delegated to the operating environment.

• The ESF Manager provides a management interface (safmgr.c) for intialization, etc. It also includes an API that lets the caller notify the manager that an ESM's configuration has been updated, which might necessitate invalidating cached results, special processing by ESM Modules, or other actions. An ESF caller can provide an Administrative Update Service of some sort to let system administrators or ESMs themselves notify ESF Manager of updates using this API.

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.

Initialization

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

Termination

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

ESF API Calls

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.

Author:

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