How to get started using Apple Open Directory
Directory Services provides a central place to store users and passwords for corporate and enterprise users. Here's how to use it on macOS.
![Apple's Directory Utility app.](https://photos5.appleinsider.com/gallery/60273-124096-du-lede-xl.jpg)
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.
Mac OS X Server
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.
![Mac OS X Server retail.](https://photos5.appleinsider.com/gallery/60273-124100-server-xl.jpg)
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 Open Directory
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.
Microsoft Active Directory
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.
Frameworks and development
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)!)
Or in Objective-C:- 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.
![Directory Services frameworks in Apple's Xcode IDE.](https://photos5.appleinsider.com/gallery/60273-124099-frame-xl.jpg)
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.
For more info on the OpenDirectory.framework, see the Apple Developer Documentation.
Directory Utility
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.
Using Directory Utility
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:
- Services
- Search Policy
- 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.
![The Services tab in Apple's Directory Utility.](https://photos5.appleinsider.com/gallery/60273-124098-du1-xl.jpg)
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.
![The Directory Editor tab in Apple's Directory Utility.](https://photos5.appleinsider.com/gallery/60273-124097-du2-xl.jpg)
Directory Editor tab in Directory Utility.
For full information on how to use the Directory Utility app, see the Apple Directory Utility User Guide.
If you need to access a Windows Active Directory server, Apple also has a page titled Integrate Mac Computers with Active Directory in the Apple Platform Deployment guide.
LDAP is quite a complex topic and may take some time to master. For a somewhat concise overview, check out the LDAPWiki.
Read on AppleInsider
Comments
It didn't take long until some unterground project (Apple Sales allowed a CE to spend some time with it)) developed the Active Directory plugin, because even in those days AD was the only thing used in corporations (and almost nobody really cared for OD). Eventually people higher up in the food chain decided to integrate the AD Plugin in the OS delivery ... ah I see Gordon Shukwit still works for Apple.
Apple totally missed this in the 90's, where Windows Server took over almost everywhere. The abject failure and (almost maliciously stupid) mishandling of the 'Apple Workgroup Servers' in the 90's - where they sold expensive Servers based on a proprietary version of AIX Unix and then dumped their support leaving the IT department with a very expensive brick - didn't help at all.
Even Mac friendly IT departments never trusted the Apple Server Strategy under OS X Server and Apple never could sell those pizza boxes in big enough numbers. At least this time, customers didn't fall that hard, when Apple stopped selling these things, as they first started to make Mac OS X a good client in a Windows system environment.
Strange days the early 00's - been there as a member of the AppleCare Enterprise team or as I used to call it in the end the 'Apple Zombie Support' as these products where essentially the undead rests of NeXt Enterprise Services soon to lay to rest for good in favor of the iPhone.