How to Use Apple Open Directory on macOS

Apple Directory Tool.

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

In most organizations, this need is met by Lightweight Directory Access Protocol (LDAP) servers or, in the case of Windows Server, Microsoft’s LDAP-based directory services, Active Directory.

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

Along with NetInfo, Apple provided an application called NetInfo Manager, which was later renamed Catalog tool. This allowed users to access NetInfo servers to obtain information about users and groups.

Collectively, these services are known as Directory ServicesThe idea behind directory services is to consolidate all user and device information in one place and use these services to authorize users to access network resources.

NetInfo was unpopular with users and administrators, and was removed from Mac OS X in version 10.4 Tiger. Instead, Apple began migrating to LDAP as it became the standard for directory services.

After Apple sent Mac OS X Serverwhich included an LDAP server, as well as other services, Mac OS X Server was later consolidated into a companion application simply called “Server”. The application can be downloaded from the Mac App Store and added to the retail version of macOS.

Original Mac OS X Server retail packaging.

OS X Server allows organizations to run their own LDAP server to store user information and authorize users. The server was later retired in 2022.

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

Apple Open Directory also introduced a ticket-based Kerberos authentication server.

In macOS, Apple Open Directory is managed in the background demon named opendirectoryd.

At that time, Microsoft developed its own directory services server called Active directory service (AD), which was introduced in Windows Server 2000.

Active Directory is one of the most widely used directory services in corporate and organizational networks.

AD offers a range of services, including LDAP, Windows Domain Services, Group Policy, encryption, certificates, and Federation Services. Microsoft also currently offers a cloud-based directory and user information service called Microsoft Entra ID.

All of these directory services can be used to search for and authenticate users and user information to use network resources, as well as to find individual users’ contact information.

In directory services, the database of stored user or device objects is called Domain.

For development purposes, Apple provides two frameworks that you can add to any Xcode project and associate with your Mac app: DirectoryServices.framework and OpenDirectory.framework.

To add these structures to your Xcode project, go to the target in your Xcode project and then click “+” button in the Frameworks, Libraries and Embedded Content panel in General tab. From the displayed sheet add Directory Services.frameworkAND OpenDirectory.framework

For additional access to UNIX directory services, you must also add code_directory_lib.tbd static library.

The Apple Open Directory API is surprisingly simple: it consists of only 9 classes and one protocol (QDQueryDelegate). Using ODNode, QDQuery, QDRecordAND ODSession objects, you can start a session from OD, configure it (ODConfiguration), and then queries the directory server to manipulate the FROM records.

Once a query is sent to OD, the results are returned via QDQueryDelegate protocol that consists of one method:

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

- query:foundResults:error:

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

Adding directory service structures in Xcode.

Once the FROM query has completed, this method will contain the original query object, any results from that query, and the returned error, if any.

Apple originally shipped the Directory Utility app in the /Utilities folder in macOS.

Currently, however, the application is hidden in /System/Library/Core Services/Applications – most likely due to the pressure to move organizations to the cloud.

If you want to use the Directory Tool, do not attempt to copy or move it to another location as the copied versions will not work.

Instead, create an alias for the app by dragging it to the Dock in the Mac Finder. You can also create an alias for the app by holding Command-Option and dragging the application to the desired location on the disk.

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

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

1. Services
2. Search Policy
3. Directory Editor

To use the Directory Editor features, you must have an administrator password for the services you want to edit.

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

Click Lock icon at the bottom of the window, and then select the option to access a specific type of server. Clicking the small Pencil The icon at the bottom of the window displays a sheet of directory services on available servers.

You can also create a new directory services configuration by clicking New button in the sheet.

Services tab in the Directory Tool.

In Search Policy tab allows you to view Authentication and Contacts information using the Automatic, Local, or Custom search path. The Search Policies tab allows you to view user information across directory domains.

This Directory Editor tab allows you to directly edit directory information, although as mentioned earlier, you need an administrator password to do this. Be careful with the Directory Editor tab, as it’s easy to edit important information.

You can view almost any directory service information you can imagine in the Editor tab, including settings for dozens of different daemons, services, and networks. If you’re not careful, you can make changes to services that can render parts of your Mac or server inoperable.

Catalog Editor tab in the Catalog Tool.

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