How to get started using Apple Open Directory

AppleInsider

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 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.

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.

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:

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.

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

rob53

Wow, a historical piece. I haven't seen anyone even mention Apple's Open Directory for more than two decades. Microsoft, in one of its many anti-competitive practices, more or less forced all US government and corporate entities to use AD. Since the US government uses it they are never going to look at any Microsoft service, especially AD, as breaking any anti-trust laws. They'll go after Apple for providing very good products and services but never Microsoft. The courts slapped Microsoft's hands a tiny bit years ago but haven't done anything to them since. I ran a shop with OSX Services using Apple Directory but it was shut down when I left that organization and everything was a mess when converting to AD.

InspiredCode

Set that Time Machine further back to the Apple II. We can’t be hacked if our computers are not even online. Those were the days.

VictorMortimer

What the article doesn't mention is how incredibly unstable Open Directory was.

It had an incredibly annoying tendency to eat itself.  I had so many client using it, and inevitably ended up migrating them to other solutions even before Apple destroyed Mac OS X Server/the Server app.  And I had so many hours wasted trying to fix it when it inevitably broke.  Replica directory?  Sure, it had that feature.  But it almost never worked right, and when the primary ate itself, the replica either refused to allow itself to be promoted to primary or just went ahead and ate itself too.

Literally the ONLY positive thing about Broken Directory was how much money I made from it.  And that was supposed to be a Micro$loth thing with IT, but Apple really made a mess with that thing.  It could have been so much better.  It's not like Apple doesn't have people who can do databases well, but they're all over at Claris, overcharging us for FileMaker.

humbug1873

The best thing about OpenDirectory was it's plug-in Architekture.
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.