How to Use Apple Open Directory in macOS

Apple Directory Utility.

Many enterprises today have a need for a central place to store information about users, passwords, groups, computers, and other networked entities.

In most organizations, this need is filled by the use of either Lightweight Directory Access Protocol (LDAP) servers or, in the case of Windows Server Microsoft’s directory services built on LDAP, Active Directory.

When Apple bought NeXT in 1997 and released Mac OS X in 2000, it offered its own directory services included with OS X called NetInfo.

Along with NetInfo, Apple shipped an app called NetInfo Manager which was later renamed to Directory Utility. This allowed users to access NetInfo servers for user and group information.

Collectively these services are known as Directory Services. The idea behind directory services is to consolidate all user and device info in one place and use those services to authorize users for network resource access.

NetInfo was not popular with users or administrators, and it was removed from Mac OS X in version 10.4 Tiger. Instead, Apple began to migrate towards LDAP as it had become the standard for directory services.

After Apple shipped Mac OS X Server, which included an LDAP server as well as other services, Mac OS X Server was later consolidated into an add-on app simply called “Server.” The app be downloaded from the Mac App Store and added to the retail version of macOS.

The original Mac OS X Server retail package.

OS X Server allowed organizations to run their own LDAP server to store user info and authorize users. Server was later discontinued in 2022.

Apple’s implementation of LDAP is called Apple Open Directory and is a fork of the OpenLDAP project.

Apple Open Directory also includes an implementation of the Kerberos ticket-based authentication server.

In macOS, Apple Open Directory is managed by a background daemon called opendirectoryd.

During all this, Microsoft developed its own Directory Services server called Active Directory (AD), which it introduced with Windows Server 2000.

Active Directory is one of the most widely used Directory Services in corporate and organization networks.

AD provides a number of services including LDAP, Windows Domain Services, Group policy, encryption, certificate, and Federation Services. Today, Microsoft also provides a cloud-based directory and user info service called Microsoft Entra ID.

All these Directory Services together can be used to query and authenticate users and user info for network resource use, and to look up contact info for particular users.

In Directory Services, a database of stored user or device objects is called a Domain.

For development, Apple provides two frameworks that can be added to any Xcode project and linked to a built Mac app: DirectoryServices.framework, and OpenDirectory.framework.

To add these frameworks to your Xcode project, navigate to a Target in your Xcode project, then click the “+” button in the Frameworks, Libraries, and Embedded Content pane in the General tab. From the sheet that appears, add DirectoryServices.framework, and OpenDirectory.framework

For additional UNIX Directory Services access, also add the libcodedirectory.tbd static library.

The Apple Open Directory API is surprisingly simple: just 9 classes and one protocol (QDQueryDelegate). Using the ODNode, QDQuery, QDRecord, and ODSession objects, you can start an OD session, configure it (ODConfiguration), then query a Directory Services server to manipulate OD records.

After submitting a query to OD, results are returned via the QDQueryDelegate protocol, which consists of a single method:

func query(ODQuery!, foundResults: [Any]!, error: (any Error)!)

- query:foundResults:error:

To add this functionality to your app, declare a class that conforms to the QDQueryDelegate protocol, then implement the query:foundResults:error method. Inside the method, your code can decide how to handle any data and errors returned.

Adding the Directory Services frameworks in Xcode.

When the OD query completes, this method will contain the original query object, any results for that query, and an error returned, if any.

Originally Apple shipped the Directory Utility app in the /Utilities folder included with macOS.

Today, however, the app is hidden away in /System/Library/Core Services/Applications – most probably due to the push to move organizations to the cloud.

If you want to use Directory Utility, don’t try to copy or move it to another location, as any copied versions won’t work.

Instead make an alias to the app by either dragging it to the Dock in the Mac’s Finder. You could also make an Alias to the app by holding down Command-Option and dragging the app to a location on your disk.

If you are using Kerberos services, there is another app in the same folder called Ticket Viewer. Ticket Viewer is simple and provides only the ability to add and remove Identities, set one Identity as the default, and change the password.

Directory Utility provides several services. You can connect directly to any supported Directory Services server by using the File->Connect menu item, or you can use one of three tabs at the top of the main window:

1. Services
2. Search Policy
3. Directory Editor

For the Directory Editor features, you must have an admin password to the services you want to edit.

The Services tab provides two simple options: Active Directory or LDAPv3.

Click the Lock icon at the bottom of the window, then select either to access a specific kind of server. Clicking the small Pencil icon at the bottom of the window displays a sheet for Directory Services on available servers.

You can also create a new Directory Services configuration by clicking the New button in the sheet.

Services tab in Directory Utility.

In the Search Policy tab you can view Authentication and Contacts info using an Automatic, Local, or Custom search path. The Search Policy tab allows you to view info for users in different directory Domains.

The Directory Editor tab allows you to edit Directory Services info directly, although as mentioned previously you’ll need an admin password to do so. Be careful with the Directory Editor tab as it’s easy to edit important information.

You can view just about any Directory Services info imaginable under the Editor tab, including settings for dozens of different daemons, services, and networking. If you’re not careful, you can make changes to the services which may render parts of your Mac or server inoperable.

Directory Editor tab in Directory Utility.

LDAP is quite a complex topic and may take some time to master. For a somewhat concise overview, check out the LDAPWiki.