New Developer Features in Novell eDirectory 8.7.1

Articles and Tips: article

01 Aug 2003

Adapted from a Novell DeveloperNet Webinar http://developer.novell.com/training

Novell eDirectory 8.7.1, which ships with NetWare 6.5, contains numerous new features and enhancements that are of interest to developers. This AppNote summarizes these new features.

Topics	Novell eDirectory 8.7, directory-enabled applications
Products	Novell eDirectory 8.7 and 8.7.1
Audience	developers
Level	intermediate
Prerequisite Skills	familiarity with Novell eDirectory
Operating System	n/a
Tools	none
Sample Code	no

Introduction

In early 2003 Novell released eDirectory 8.7, a major update to its industry-leading cross-platform directory service. This highly scalable, high-performing, secure directory service can store and manage millions of objects, such as users, applications, network devices, and data. Novell eDirectory provides centralized identity management, infrastructure, Net-wide security, and scalability to all types of applications running behind and beyond the firewall. It natively supports the directory standard Lightweight Directory Access Protocol (LDAP) v3.

Novell eDirectory 8.7 introduced a number of new features, such as Web-based and wireless management capabilities, extensible match search filters, Simple Network Management Protocol (SNMP) monitoring, and enhanced backup and restore capabilities. It also provided support for Transport Layer Security (TLS) services based on the OpenSSL source code.

This AppNote covers some of the features of eDirectory 8.7 that are of interest to developers, with emphasis on those that are new since eDirectory 8.6.x. It also lists the new features in eDirectory 8.7.1, an updated version which ships with NetWare 6.5.

Dynamic Groups

Dynamic groups have been supported since eDirectory 8.6, but this feature has been further enhanced in eDirectory 8.7 and 8.7.1. As a review of how groups work in directory services, suppose you have an application for which you want to assign rights to multiple users. You can create a group, add the users to that group, and then assign rights to the group instead of having to assign the rights to each individual user. Every user who is a member of the group will automatically have the rights necessary to run the application. So groups are a useful tool in managing rights for applications, files, printers, and whatever you might want to secure using directory services.

Traditionally, groups have been static in nature. In other words, the "member" attribute had to be populated manually. As an example, suppose you created a static group called "Managers" to give rights for certain restricted applications to your organization's managers, directors, and vice presidents. You have added each manager individually as a member of this group. But then a temporary manager comes in just for a couple of months. You'd have to assign him as a member of the Managers group, and then remember to remove him from the group when his temporary managership ended. If not, he would continue to have access to the manager-only applications after he no longer required it.

As the name implies, dynamic groups allow membership in a group to be determined dynamically, in additional to explicitly assigning members. A dynamic group can use an LDAP search filter in URL form (as specified in RFC 2255) to assign all users with a certain attribute value to its membership list. So in the example above, instead of having a Managers group that is defined statically, you could add an attribute called "Title" to all User objects. If a user is a manager, you would populate the Title attribute with a string such as "Manager". Then the LDAP search filter would look for all users that have the Title of "Manager" and automatically make them members of a dynamic group. They would then gain all the rights necessary to run the manager applications. When a person is no longer a manager, all you'd have to do is change the Title attribute on that person's User object, and the user would immediately lose the rights he or she had as a member of the dynamic group.

If you look at the schema for eDirectory 8.7, you'll see that there are two new classes that describe dynamic groups. The first one, dynamicGroup, is a structural class. You would use this structural class when you want to create a new group that you want to be a dynamic group. Within the dynamicGroup class are three attributes.

The memberQueryURL attribute specifies the search filter to use to describe the dynamic group. In the above example, you would have a search query URL that had the Title attribute in it. When users want to access the group, the LDAP server would search for members based on this search filter in the memberQueryURL attribute.
The excludedMember attribute allows you to specifically exclude certain objects from the group. You would use this if you had, for example, User objects that are not supposed to be in a dynamic group, but for some reason match the search filter.
The uniqueMember attribute allows you to specifically include certain objects in a group. This would be useful if had User objects that should belong to a dynamic group, but for some reason don't match the search filter. Reading the uniqueMember (or "member") attribute returns specifically identified objects, as well as objects which satisfy the query.

The second object class, dynamicGroupAux, is an auxiliary class. This class allows you to convert static groups that you have already established into dynamic groups. You do this by simply adding dynamicGroupAux to the objectClass attribute of an existing group, and then setting a search query in memberQueryURL.

You can obtain a member list of a dynamic group in the same way as for a static group, by simply running a query on the "member" attribute. By default, the implicit search is limited to the local server.

A new feature added in eDirectory 8.7 is a Web-based utility to help manage dynamic groups. The Novell iManager utility includes a Dynamic Group Management role to create and modify Dynamic Group objects.

Extensible Match

Another new feature in eDirectory 8.7 is partial support for extensible match searching. The LDAP v3 core protocol specification defined in RFC 2251 requires LDAP servers to recognize a search element called an extensible match filter. An extensible match allows an LDAP client to specify the following items in a search filter:

An attribute name (optional)
A matching rule (optional)
A flag to indicate if the DN attributes should be considered part of the entry
The value to be used for the match

LDAP v3 supports multiple matching rules for the same types of data. This would allow you to implement new rules such as "sounds like." However, eDirectory 8.7 currently supports only an exact value match and thus ignores this field. eDirectory 8.7 does allow DN (Distinguished Name) elements to be used in the search criteria. The inclusion of DN attributes in the search via the extensible match filters allows matching to be done on specific values in the DN of an object.

To show you how this can be valuable, consider the example task shown in Figure 1. Within this sample tree here are several OUs, and some of these OUs have Administrative Assistants in them. The task is to find all of the Admin Assistants in the Sales OUs. So you want to find Terry, Sam, Alice, and Bill, but not Hilda because she's in the Finance OU.

Figure 1: Sample tree for the task of finding all Admin Assistants in Sales OUs.

Using a traditional LDAP search, you'd have to first search for all the Sales containers in the tree. Then using each Sales container as a base, you would have to do a subtree search for users in the Admin Assistant container. This method requires four separate searches to find the four Admin Assistants you want and to make sure you do not find Hilda. Even then, it may not provide complete results.

Thanks to eDirectory's support for extensible match, you can include the DN of "Sales" in your search criteria. You'd simply search for all Admin Assistant containers in the tree whose DN contains a Sales container. Here is what the extensible match search filter would look like:

(&(ou:dn:=Sales) (organizationalRole=adminAssistant))

This filter indicates that you're looking for everyone who has "Sales" in their DN and who has their organizationalRole equal to "adminAssistant". So by using extensible match, you only have to do one search to get the results you want.

SDK Sample Code references: extmatch.c, extmatch.java

eDirectory Events

Novell eDirectory has an event service that enables applications to be notified of significant events that occur within the directory. Some of these events are general events that can pertain to any directory service; other events are specific to eDirectory and its special features. In previous version of eDirectory, this event service was accessible only on the NetWare platform. With eDirectory 8.7 and above, it is accessible on all of the platforms that eDirectory runs on.

Some of the tasks you can do with eDirectory events include:

eDirectory monitoring
Auditing
Automation of infrastructure changes
Automated business logic

All of these things can be done only with eDirectory. They don't exist in the same form in other directory products. As a developer, you can use these events to watch for changes in the directory. When you store information in the directory, you're going to want to be able to find out when that information is changed and who changed it, so that your applications can react to changes on key information.

eDirectory defines several directory-related events which can be used for debugging, auditing, and management purposes, including:

Operations on individual entries and their attributes
Partition and replica operations

In eDirectory 8.7, Novell added access rights control for events. If you are registered for an event and you do not have the required privileges, either the request will fail or you will not be able to see the event.

Novell has provided access for developers to register eDirectory events across all supported platforms. eDirectory events are exposed to applications through two different LDAP mechanisms: the Persistent Search Control and the Monitor Events extension. Why two mechanisms? Persistent Search is an IETF specification that focuses on the ability to gather events on objects and data within the directory. In eDirectory, however, the event system also provides access to information about events occurring on the directory itself, such as when a new partition or replica is created. This event information is not accessible through Persistent Search, so Novell created an LDAP extension to allow you to access it.

Persistent Search Control

Let's talk a little more about Persistent Search and how it works. Persistent Search is a control added to an LDAP search that basically allows the search operation to keep going after the initial set of matching entries is returned. It moves the burden of checking for updates within a search result set from the client to the server. Persistent Search is an alternative to implementing some type of polling mechanism to detect changed information.

In an LDAP search operation, the client can apply a search filter to describe what type of objects are being requested and other parameters such as the location in the tree from which the search is to begin, whether to search just one level or the entire subtree, and so on. Normally, the request is made to the LDAP server and the server issues a SearchResultDone message when all of the matching results are returned. With the Persistent Search Control applied, the search operation maintains a connection so that the client can be updated each time an entry in the result set changes. This allows the client to maintain a cache of the entries it is interested in, or trigger some logic whenever an update occurs.

In specifying in the control what type of results you would like, you can specify whether you want to know about just additions, deletions, modifications, or renames, or put them all together and get notification about all types of events. The changeTypes (IN) is a bit-wise OR integer containing the following flag values:

LDAP_CHANGETYPE_ADD
LDAP_CHANGETYPE_DELETE
LDAP_CHANGETYPE_MODIFY
LDAP_CHANGETYPE_MODDN
LDAP_CHANGETYPE_ANY

Another thing you can specify in this control is whether you want to receive the current data set along with any changes that occur in the future, or just the changes only. This is done via the changesOnly (IN). If it is set to zero, the results of the initial search are returned and then the control will block, waiting for additional events to occur. When they do, entries that are subsequently changed are returned to the client. If it is set to a non-zero value, no initial results are returned, but all subsequent changed entries are returned.

Monitor Events Extension

The second mechanism for eDirectory event notification is called Monitor Events, an extended LDAP operation that is specific to eDirectory. This extension allows an LDAP client to be notified of the occurrence of various events on an eDirectory server. It uses the LDAP v3 extended operation extension mechanism, and is available on all platforms supported by eDirectory 8.7. It also uses an intermediate response Protocol Data Unit (PDU) as described in the IETF draft (http://www.ietf.org/draft-rharrison-ldap-intermediate-resp-00.txt).

If you just want access to data within the directory, Persistent Search is the preferable method. If you want to monitor changes to the directory itself, whether for debugging, auditing, or management purposes, the Monitor Events extension would be a good way to do that.

Transport Layer Security

Novell eDirectory 8.7 added support for Transport Layer Security (TLS) 1.0 to provide privacy and data integrity between LDAP clients and LDAP servers, so you can make sure your connections are secure. TLS is very similar to Secure Socket Layer (SSL), which was developed by Netscape. When the IEFT subsequently took ownership for that standard, the result was TLS. There's really only a few minor header changes between SSL and TLS.

TLS allows for connections to be encrypted in the Session layer. The entire packet is encrypted so that sniffers are unable to decode data sent across the network. This ensures that the connection is private and reliable. With TLS, user identities can be authenticated using asymmetric or public key cryptography. The negotiation of shared secrets is done entirely between the client and the server; there is no "middle man." The reliability of the negotiation is ensured via an attacker detection mechanism.

An LDAP client can either start a TLS session by connecting to secure port 636 (the implied TLS port on an LDAP server) or connect to the clear-text port and later use TLS to upgrade the connection to an encrypted connection. As an example of this, say you're using LDAP to connect to a Web site. As you're surfing through the public portion of the site looking at non-secure information, you have an open connection through a clear-text port. But then you decide you want to order something from the site using your credit card. In the past, you had to drop the connection and reauthenticate over the SSL port. But with TLS you can send a startTLS extended request along with the query to read your credit card information and TLS will switch you over to a secure connection without you having to reauthenticate.

You can configure the eDirectory LDAP server to do the TLS handshake in three different ways:

Server certificate only
Request client certificate
Require the client certificate

You configure this in the new Novell iManager utility that comes with eDirectory 8.7 and above.

After your order has gone through and you no longer need to have a secure connection, either the client or server sends a stopTLS request and the connection automatically reverts to a public connection. When you stop TLS, the LDAP service removes any authentication previously established and your authentication state changes to Anonymous. Therefore, if you want a state other than Anonymous, you must reauthenticate.

SDK Sample Code references: strt_tls.c, tbd.java

New LDAP Authentication Methods

Traditionally, with eDirectory and LDAP, users have been able to log in by providing a username and password. In eDirectory 8.7, Novell has added support for Simple Authentication and Security Layer (SASL), an authentication negotiation framework that allows the use of various other authentication methods. These methods must be registered with the Internet Assigned Numbers Authority (IANA). The server lists registered authentication mechanisms in the registeredSASLMechanisms attribute of the root DSE. The client chooses the authentication method and the server implements the appropriate authentication policy.

SDK Sample Code references: getdse.c, getdse.java

Supported Authentication Methods

The eDirectory 8.7 LDAP server supports the following three authentication methods:

EXTERNAL
DIGEST-MD5
NMAS_LOGIN

These mechanisms are installed on the server during an eDirectory installation or upgrade. The LDAP server queries SASL for the installed mechanisms when it gets its configuration, and automatically supports whatever is installed. Because these mechanisms are registered, you must enter them using all uppercase characters. Otherwise, the LDAP server won't recognize them.

The LDAP bind protocol allows the client to use various SASL mechanisms for authentication. When the application uses the LDAP bind API, it would either need to choose the simple bind and supply a DN and password, or choose the SASL bind and supply the SASL mechanism in uppercase, and any associated SASL credentials required by the mechanism.

EXTERNAL. The EXTERNAL mechanism is based on certificates. In other words, the TLS handshake establishes client identity by means of certificate-based client authentication. An LDAP bind request using the SASL EXTERNAL mechanism instructs the server to do the following:

Ask an EXTERNAL layer what the credentials were
Authenticate the user as those credentials and user

During the handshake and identification portion of establishing a connection, the server requested credentials from the client and the client passed them to the server. The LDAP server received the certificate that was passed from the client and authenticated the user as whatever DN was supplied in the certificate. LDAP then uses that identity for the user connection.

SDK Sample Code references: saslext.c, tbd.jav

DIGEST-MD5. The SASL DIGEST-MD5 mechanism does not require TLS; the LDAP server supports DIGEST-MD5 over clear and secure connections. DIGEST-MD5 allows you to send your password securely over a clear-text connection. This requires that the server maintain a clear-text copy of your password. The way this is done in eDirectory 8.7 is to put a copy of the clear-text password in the NMAS encrypted store. This store can be hashed using data provided in the bind and then compared to hashed data that is sent to the server.

SDK Sample Code references: saslmd5.c, tbd.java

NMAS_LOGIN. The NMAS_LOGIN mechanism provides the LDAP server with the full functionality of Novell Modular Authentication Services (NMAS) applied to LDAP binds. As with the other methods, the login policy is maintained by the LDAP server. NMAS allows multiple levels of authentication and identification. This means you can use any NMAS-compatible method such as certificates, smart cards, and biometric devices, such as fingerprint readers, alone or in combination with username-password methods. Since NMAS is a modular authentication service, it can support all sorts of different devices. Developers can even write their own authentication method to work with NMAS.

One of the limitations of NMAS in the past has been that it requires the Novell NetWare Client to be present. Thus NMAS could only be used on clients that were connecting to a NetWare server. With the SASL NMAS_LOGIN method in eDirectory 8.7, the connection is now done over LDAP so you can use your NMAS devices to connect to LDAP servers wherever eDirectory is running.

For more information about NMAS, see http://www.novell.com/products/nmas.

SDK Sample Code references: saslnmas.c, tbd.java

SOAP Access to eDirectory

Integrating eDirectory into the Web services world is now easier than ever with Directory Services Markup Language (DSML), an OASIS specification that enables developers to express LDAP functions and retrieve data in XML. Support for DSML v2 is available for eDirectory 8.7 and above. Although the DSML v2 Server provides no new eDirectory functionality, it makes it very easy for developers familiar with using XML and SOAP to integrate with the directory using the tools you know.

With DSML for eDirectory, you can now use SOAP to access eDirectory. A full DSML v2 SDK is available for eDirectory 8.7 and above. It provides a DSML SOAP connector that connects to eDirectory and any LDAP directory, including prior versions of eDirectory that are running the LDAP service. Also included is the ability to use authentication information from the HTTP header.

Figure 2 illustrates the architecture of the DSML connector. This implementation conforms to the JNDI Service Provider specification from Sun.

Figure 2: Architecture of the DSML connector for eDirectory 8.7.

DSML bridges the gap between developing to Web services and developing to a directory by allowing traditional LDAP directory operations and their results to be represented as XML request/response operations. Common DSML operations include searching for specific directory objects and returning selected attribute values. Using SOAP, such XML-based information sent by the client is picked up by the Web service. Through DSML, the XML information is interpreted, turned into an LDAP request, and sent to eDirectory. When the response is returned, it's converted back into XML format and is sent on to the Web service.

Also in the SDK is sample code showing how to use DSML to access eDirectory in the JNDI environment (if you're familiar with the JNDI provider), in the Microsoft .NET environment, and with the Novell exteNd Web services engine, jBroker Web.

Other New Features in eDirectory 8.7.1

For your reference, here are brief descriptions of some other new features included in eDirectory 8.7.1.

Clientless install (Windows only). This provides the ability to install eDirectory on a Windows NT or 2000 server with the Novell Client.
Novell iMonitor 2.1. This new version of iMonitor provides SSL support on all platforms, object statistics reports, enhanced obituary processing reports, server advertising reports, enhanced tracing functions, and event monitoring and statistics.
Novell iManager 2.0. This utility provides a single Web-based management console for the administration of Novell products on NetWare 6.5. iManager standardizes all Novell Web-based administration utilities into a single management framework. It also provides an architecture for easy development of Web-based administration and management modules through open standard application interfaces. This utility uses Roles to delegate eDirectory administration, management, and services tasks.

Novell iManager consists of two pieces: eDirectory Management Framework (eMFrame) and eDirectory Management Toolbox (eMBox). Novell eMFrame plug-ins communicate over standard directory access protocols to perform routine management tasks and also communicate with eMBox. EMBox is the server-side piece that works with iManager to access functionality in various eDirectory utilities. The eDirectory utilities available in Novell iManager include DSRepair, DSMerge, Backup and Restore, LDAP, WAN Manager, and the Novell Import Convert Export utility. These are the same utilities that shipped in eDirectory 8.6.2, with fixes in DSRepair to accommodate Extensible Match. A new SNMP management utility is also included.
Universal Password. In the past, administrators have had to manage multiple passwords (simple password, NDS RSA passwords) because of password limitations. Administrators have also had to deal with keeping the passwords synchronized. Universal Password addressed these problems by creating a single password that can be used by all protocols to authenticate users.

In addition, all Novell utilities are now UTF8 encoded. When a password is reset by a user or an administrator, the Secure Password Manager (SPM), an NMAS components, will take the unicode password and convert it to a Universal Password (UTF8-encoded) and reset the NDS password. It will also reset the simple password if there is one.
Backup and Restore. eDirectory 8.7 introduced a new focus for backup and restore, called "hot continuous backup." With the new Backup eMTool, you back up the eDirectory database for each server individually, and you can do it while eDirectory is running. This tool is great for restoring an individual server after a hard drive failure or for moving a server's data to a new machine. It's much faster than using the Target Service Agent (TSA) for NDS to back up the tree. (The legacy TSA for NDS backup still works as documented in eDirectory 8.6; both TSA for NDS and the new backup tool can be used if necessary.)

In eDirectory 8.7.1, backup of server-specific information has been implemented using the Backup eMTool.
Novell eGuide 2.11. eGuide provides a Web-based GUI for searching, viewing, and editing information stored in Novell eDirectory and other directory data sources. Because eGuide is highly customizable for any type of environment, administrators can configure it to their own specifications. Users access eGuide via a standard Web browser.

Conclusion

This AppNote has provided an overview of the new features included in Novell eDirectory 8.7.1 from a developer's perspective. For more information about eDirectory, including a free evaluation version and redistribution kit, visit http://www.novell.com/products/edirectory.

* Originally published in Novell AppNotes

Disclaimer

The origin of this information may be internal or external to Novell. While Novell makes all reasonable efforts to verify this information, Novell does not make explicit or implied claims to its validity.