Apr 6 ’11

Exploiting LDAP on z/VSE

by Editor in z/Journal

With the introduction of z/VSE Version 4.2, IBM provided a new feature called LDAP Sign-on Support. Lightweight Directory Access Protocol (LDAP) is an accepted standard that’s commonly used in Identity Management Systems (IMSs) to centralize storage of identity-related information. As part of the LDAP Sign-on Support, IBM has provided a full-function LDAP client that enables the z/VSE system to communicate using the LDAP protocol. This lets users sign on to the z/VSE interactive interface using “companywide” credentials that are stored on an LDAP server in an LDAP directory.

The userids and passwords used can be up to 64 characters each, and the LDAP server can enforce the requirement for complex passwords and other policies. IBM Tivoli Directory Server, z/VM LDAP Server, Novell eDirectory, Microsoft Active Directory, and OpenLDAP (an open source implementation of LDAP) are examples of some available IMSs. This article examines how you can exploit the LDAP client provided with the z/VSE operating system. For more information on LDAP Sign-on Support, view the z/Journal article by Ingo Franzki published in the April/May 2009 issue. This article, titled “Integrating z/VSE Into an Identity Management System Using LDAP,” is available at www.mainframezone.com/it-management/integrating-z-vse-into-an-identity-management-system-using-ldap/P2. There are many other sources of information on this topic, including IBM Redbooks.

z/VSE Before LDAP Support

Before the z/VSE operating system supported LDAP, z/VSE was limited to using local credentials stored in the z/VSE Basic Security Manager (BSM) (for access to the interactive interface) or in-house-developed methods for storing user’s credentials and controlling logon access to applications.

When using the z/VSE BSM, the system is limited to eight-character userids (or four characters when configured to access Interactive Computing and Control Facility [ICCF]), eight-character passwords, and can only enforce basic policies for the length or complexity of the passwords involved. Complexity is enforced by implementing a customized exit. The passwords are also limited to only uppercase, numbers, and a handful of special characters. Additionally, z/VSE security only provides a 20-character field for adding a description to the z/VSE BSM user profiles and doesn’t provide any place to keep other identity-related information.

These limitations may not be an issue for everyone, but in our environment, they prevented our z/VSE system from meeting company policies; this required us to file several exceptions with our corporate auditors. We had to put several compensating controls in place. For example, we had to maintain a cross-reference between z/VSE user profiles and our corporate employee ID numbers.

From an application perspective, we faced several security compliance issues that required us to modify our applications to store password hashes (instead of storing the actual password) and we had to maintain a local copy of much of the identity-related data associated with our users in our application. This included the user’s full name, email address, and other contact information. This data wasn’t actively synchronized with the data maintained in the corporate IMS, which was a constant source of discrepancies. For example, our z/VSE-based reports are distributed using email. If an employee’s name changed, their email address also changed and this could lead to failures in report delivery. If an employee left the company, we relied on reports from the Human Resources Department and human intervention to remove their access to the z/VSE system. These items didn’t please our corporate auditors and caused service delivery and support issues.

The LDAP Solution

The z/VSE LDAP client support is implemented primarily as part of the z/VSE interactive interface. The z/VSE interactive interface sign-on programs now support optional invocation of LDAP authentication of user-entered credentials against an LDAP server. Tools to define LDAP users to the z/VSE system were also provided. There’s a configuration member that must be tailored to define how the z/VSE system will communicate with the external LDAP server and several other options. Getting through this configuration requires knowing how your LDAP server was implemented, what methods are supported for authentication, what hierarchical directory structure your LDAP system administrators implemented, and more. You should be able to answer these questions:

If the search method is required, you should know answers to these questions:

Some specific performance and tuning options (i.e., caching options, timeout values, etc.) can be set to further improve and enhance z/VSE LDAP client functionality. A skeleton called SKLDCFG is provided in ICCF library 59 for this configuration. How to tailor this and enable the z/VSE LDAP client support is documented in Chapter 45 of the IBM z/VSE Administration V4R2 manual (SC33-8304-02), titled “Maintaining User Profiles in an LDAP Environment.”

STRICT_MODE is an option to keep in mind. If it’s enabled, then only user profiles that are set up in the LDAP mapping are enabled to log on to the z/VSE interactive interface. It’s recommended that this option not be enabled while testing; it prevents system logon using local (non-LDAP) credentials if they’re not set up in the LDAP mapping file.

Once you’ve completed the z/VSE LDAP configuration, two additional, optional components are needed to further exploit LDAP from your z/VSE system(s): the LDAP client sample sign-on program and the LDAP query callable module. Both are available free and can be downloaded from the z/VSE homepage downloads section (www.ibm.com/vse) or these locations:

The first component, the LDAP client sample sign-on program, is a sample of how to use the LDAP sign-on functions from within an application. The interface to perform this is documented in Chapter 45 of the IBM z/VSE Administration V4R2 manual (SC33-8304-02) but Figure 1, which shows a sample of this new LDAP sign-on screen, provides an example of how to use this support. In our environment, we implemented this sample code (with minor tailoring) to replace the CESN CICS sign-on transaction so users can use their LDAP credentials to sign on to our CICS regions that don’t have the z/VSE interactive interface implemented. This requires the LDAP mapping file (IESLDUM) be added to the CICS region, along with the provided program and BMS map. We decided to define a transaction ID of LDSN to invoke this LDAP-enabled CICS sign-on program. The BMS map provided mimics the CICS-supplied CESN transaction’s interface but allows entry of the 64-character userid and password.

The second component, the LDAP Query Callable Module, provides a callable interface for performing LDAP queries against the LDAP directory. A powerful C Application Programming Interface (API) is provided as part of the z/VSE client support (see member IESLDAPH.H in VSE sublibrary PRD1.BASE), but you can only use it if you have the C language available on your z/VSE system. The LDAP Query Callable Module provides the callable interfaces needed to perform an LDAP query from any LE-conforming language (i.e., COBOL for VSE).

This package also includes a CICS COMMAREA-based interface module that can be accessed using a CICS LINK command. The PASSAREA to the callable interface and the COMMAREA used on the CICS LINK operation have identical formats. Because the CICS environment handles the language environment details, the CICS COMMAREA-based interface can also be accessed by REXX for CICS and any other language CICS supports. The downloaded package also includes two COBOL-based sample programs that show how to use this callable interface. Figure 2 shows a simple example written in REXX for CICS that retrieves the mail attribute (where our LDAP directory stores the email address) for a specific user and displays it.


The Possibilities

In our environment, we’ve configured the z/VSE LDAP Client Support to provide sign on to the z/VSE interactive interface and our other CICS regions. This allows the sign on to our systems to be integrated with the corporate LDAP environment where password complexity policy is enforced to conform to company policy. We also have a self-service password reset function available through an intranet portal that allows an end user to reset his or her forgotten password based on security questions. With the z/VSE LDAP Client Support, the z/VSE system can now leverage this functionality, reducing and/or eliminating service desk password reset calls. There are also automated human resources processes that disable the LDAP account in the LDAP directory when an employee has left the company or when they’re out on extended leave. With the z/VSE LDAP Client Support, this is automatically applied to the z/VSE system sign-on and eliminates the audit issues we used to have surrounding deactivating accounts, etc.

Using the LDAP Query Callable Module, we’ve integrated many of our applications with the corporate LDAP directory. For example, our report distribution via email now uses an LDAP query to obtain a user’s email address from the LDAP directory to avoid the discrepancies we used to have that cause email delivery issues. We’ve also used the LDAP interfaces to automate a quarterly User Account Validation process we’re required to perform. This new, LDAP-based automated process uses the LDAP directory to obtain a user’s full first and last name, their email address, their manager’s full first and last name, their manager’s email address, etc. to build automated emails sent quarterly to confirm that a user still requires his or her account and access.

The possibilities don’t stop there. With the proper permissions in the LDAP environment, you can use this interface to query any of the available LDAP attributes stored in the LDAP directory. Since this is typically the IMS for the company, this could contain a large amount of data. For example, in our environment, this contains hierarchal links that let you extract organizational chart-related information. Our entire company’s corporate directory information is available. You could take this further and use attributes that might be available in your environment to determine base-level permissions in your applications. For example, a user’s title and department might be stored in the LDAP directory, which your application could use to grant permissions to certain functions in your applications. You could even work with your LDAP system administrators to add to the LDAP directory custom attributes specific to your application needs. These could then be used for whatever purpose you require.

Also note that the LDAP Query Callable Module can be implemented without enabling z/VSE LDAP sign-on support. You’ll still need to perform the configuration steps described previously, but there’s a flag option in the LDAP configuration member called LDAP_AUTH_ENABLED that you can set to 0 (it’s a bit setting of the FLAGS field). This will allow the LDAP Query Callable Module (and the C APIs) to perform LDAP functions even though the z/VSE interactive interface will only use local z/VSE accounts for sign-on. When the configuration is set this way, the z/VSE interactive interface sign-on screen will only display the eight-character userid and password fields and will only authenticate against local user profiles.


This article has provided insight into the possibilities available with the z/VSE LDAP client support. Integration into your company’s corporate IMS could allow sign on to both your z/VSE system and z/VSE-based applications to use the same credentials used by your site’s other platforms and applications. This can help z/VSE comply with company policies and other regulations that might require longer userids and more complex passwords. It can provide tighter integration with human resources and other processes that use the corporate LDAP directory to control access and permissions, etc. It lets your z/VSE system, and the applications hosted there, leverage the data attributes maintained in the LDAP directory. Depending on your LDAP environment, the possibilities could be of great value to extend the capabilities of your applications on z/VSE.