Published on MacDevCenter (
 See this if you're having trouble printing code examples

LDAP in Mac OS X Server

by Tony Williams

When you think of network services and their clients, you don't often think about the information that has to be stored about, or on behalf, of each of those clients. Your mail server and file server, for example, have to know the user name and password of every user. You may also have a web server that requires similar information. You may even want all the computers in your network to be able to use the same login information to authenticate users.

These are typical of the problems that "directory services" were developed to solve. In this article I'm going to explain how we can solve them using Mac OS X.

The granddaddy of directory services was X.500. Unfortunately the X.500 standard proved difficult to implement and overkill for most real-world requirements.

So a simpler version was developed: the Lightweight Directory Access Protocol or LDAP. OS X has the OpenLDAP server and utilities installed. Mac OS X has a number of utilities from Apple that make controlling, configuring, and adding data to your LDAP server easier. These are half the key components (Kerberos and some parts of Samba provide the other half) of what Apple calls Open Directory v2 in OS X 10.3. For more technical information and a copy of Apple's Open Directory Administration Guide, I recommend Apple Support's Open Directory page.

Related Reading

Running Mac OS X Panther
Inside Mac OS X's Core
By James Duncan Davidson

People often confuse an LDAP server with a database, indeed most LDAP servers use a database (in our case Berkeley DB) to store the information, but LDAP uses a different model of the data. LDAP uses a tree model called the Directory Information Tree (DIT) and we can imagine each entry as either a fork or a leaf on the tree (an inner or outer node in geek speak).

An entry contains one or more objectClasses. An objectClass has certain required or optional attributes. Attributes (or more specifically, their types) have a particular encoding and rules that determine things like how they should be searched and the type of data they contain. This is defined in a schema. Open Directory uses both Internet standard schemas and a number of extensions from Apple.

Getting LDAP Running

OpenLDAP is running by default in Mac OS X Server, so we only have to make sure that it came up OK and change the settings for our purposes. Open the Server Admin application and connect to your server. In the list of services in the left-hand pane click on Open Directory and it will open to the Overview pane on the right. This should list all the parts of Open Directory as Running; for our purposes we need the LDAP server and the Kerberos KDC running.

You may discover that the KDC is not running; if so, this is probably due to the base paranoia of Kerberos. If the Kerberos realm name does not return the same IP address as the machine, and if the KDC does a DNS lookup, then the KDC will not run as a daemon and will exit. By default the Kerberos realm name will be the full host name of the computer. For this, and similar reasons, I always give my servers a specific name (such as and make sure this is properly added to my DNS before I start installing the OS software on a new server. If you have changed something so that this is no longer true, then add the host name of the server to your DNS and reboot to get KDC running.

Once we've done that, it's time to get all the settings correct, so click on the Settings button. We'll now see the General pane. Set the Role to Open Directory Master, making sure that the Kerberos realm is set right and the search base is set to dc=company,dc=com. Click on the Protocols button, and you should see that the search base is the same and everything else has sane settings.

The final pane is Authentication where you set such things as password and account timeout. Set these according to your own institutional paranoia and we are all set. Click the Save button and exit from Server Admin.

Our first task now is to populate our LDAP server with the account information we need to authenticate our users and provide them with a served home directory and mail address.

The easiest way to do this (and that's using "easiest" loosely) is with Apple's Workgroup Manager. Unfortunately this application has a fair number of peculiarities, but we can easily work around them. Open the WorkGroup Manager and connect to your LDAP server.

Before we can add our users we need to make sure they can get to their home folders. Click on the Sharing icon in the top bar. Then in the left pane select the Users folder. In the General pane click on "Share this item and contents." As I can be a little paranoid, I then select the Protocol pane and make sure "Allow AFP guest access" is selected in AppleShare and that none of the other protocols are active.

Now click on the Accounts button. Even if you are importing your users from another computer, you should start by creating a user by hand so that you can create a Preset.

The first decision you have to make is what the "short name" of your users will be. The short name is used for both the users home folder and their email address. If you have existing users that are being imported from AppleShare IP, then the users' "Internet names" will be used by the import process. At my company we use the person's full name with spaces replaced by underscores.

Since I'm creating this user to create a Preset, I give him a user name that is obviously fake, such as a full name of Bugs Bunny and a short name of bugs_bunny.

Then move on to the Home pane. Click on the plus symbol to add a new item to the list of home folders. Adding a home folder so it can be shared is not well documented, but this is what works for me. In the server/share point URL enter afp:// as you might think from the URL. The path, as suggested, should be the short user name. The software insists that something should be in the Home box; logic, on the other hand, might suggest that the URL and path we specified have all the information required. Having tried various possibilities, I've discovered that entering just "/" works best here. Don't bother clicking on Create Home Folder, since 1) It doesn't seem to work for shared home folders, and 2) There is a good script we can run to add them all at once when we have finished all our users.

Set the Print and Windows panes as you desire. Now click on Save to save your user, and then select Save Preset in the preset popup, giving it an obvious name such as plain user.

Now you're ready to import your users and groups. Select Import... from the File menu. Once you've selected the file to be imported, choose your preset in the User Preset popup and let the import run.

I've found that every time I import there's a problem or two. The first is that the mail server in the Mail pane is always set to the LDAP server I'm using, not the mail server name. The second is that some of the time the user's home folder is not set properly.

Thankfully, there's an easy fix to both of these as the Workgroup Manager allows operations on multiple user records at the same time. So select all our imported users and go to the Mail pane. Enter the correct server name in the Mail Server box and click on Save.

Fixing the home folder is almost as easy. With all the users still selected, go to the Home pane and click on "None" in the folder list, then click on the proper home folder. You will notice that the line in the dialog that starts "Home:" will change to afp://, and you can then click Save again. It seems that both these bugs in import are problems with the Preset system, since you will have the same problems when you use a preset to create a user by hand.

Now we can create those home folders. Apple's documentation says that if there is no shared home folder when a user first logs in it will be created, but I've never actually trusted this process, so I create them using the createhomedir script. Go into the Terminal and enter sudo createhomedir -a, and you should find that the directories will be created for you.

The moment of truth is now upon us. Time to connect a Mac OS X client.

Connecting a Client

Go to your client and run Directory Access, which can be found in the Utilities folder. You'll have to start by clicking on the padlock to authenticate yourself, then click on the LDAPv3 box. The configuration dialog will pop up, so click on New... to create a blank entry.

Name the configuration and put in the domain name of your server. Then select Open Directory Server in the LDAP Mappings popup and another dialog will pop up asking for the Search Base Suffix, which is the same dc=company,dc=com back when we were setting up our server. That has connected the client to the server so now we just have to tell it where to use them.

Go to the Authentication pane and click on Add... and you will see a list of the methods available to you that are currently unused. Click on the LDAP line and click the Add button. Do the same in the Contacts pane. Now you've set up directory access.

To test this, try logging into the client.

LDAP for Mail

We can also use the LDAP directory to build a shared address book for our company. Once again we'll run into some problems due to Apple's poor implementation.

For example, when you add a user into your LDAP directory, the WorkGroup Manager will set the sName attribute to 99 for all users. This means you have to go in and edit all those entries. Personally I use phpLDAPadmin as it is easy to install and not only allows you to cruise your entire LDAP tree, but also allows you to easily examine the schema.

Installing it is as easy as downloading it to the Mac you use for managing your network, unpacking the tar file somewhere accessible from the web server (I put it in my Sites folder), and editing the config file. One note, I set the authtype to form so that I get a login form rather than saving my password in the config file. I do this so that I can easily change the password of the admin user on the server without having to change it in places like this.

To fix the aftermath of Apple's bug you need to change the sn attribute to the user's surname and add the attribute givenName with the user's given name(s). Doing this is a fairly tedious job if you have a number of users, so I find a junior staff member and after 10 minutes of training get him or her to do it.

After all of this, you now have your local users ready for use in email. Adding other addresses can be fairly easy. If they are in your Address book then Alex Hartner has written an excellent tool, AddressBook2LDAP, which allows you to easily shift addresses to your server. The hard part of configuring this tool is specifying the logon field. You'll find that the easiest way to set it is uid=admin_user,cn=users,dc=company_name,dc=com where you replace the admin_user and company_name with your details. Then just enter the correct password into the password field.

If you have addresses stored in some other system that can export an LDIF (LDAP Data Interchange Format) file, then you can import that using phpLDAPadmin. If they can't export as LDIF, you're out of luck.

One of the shortcomings between Address Book and the LDAP server is that not all fields in the Address Book can be saved on your LDAP server so that Address Book can get them back. Fortunately the most important ones, such as email address, physical address, and phone numbers are supported, but only one of each for a single entry.

In order to use these addresses, you have to make some minor additions in Address Book. At the moment the Address Book can find your users through Directory Services but not the addresses you have added to the server. To allow this, you have to set the Address Book to access the LDAP server directly.

Open the Address Book preferences and click on the LDAP button. Click on the "+" button at the bottom of the window and a pane will open to add the details of your LDAP server. The only field not obvious is the "Search base:" -- set this to cn=people,dc=company_name,dc=com.

You can now search your LDAP server from the Address Book. I've had problems (on some clients) getting auto-completion to work in Mail. The fix for this is to go into Mail preferences and in the Composing pane you'll see a "Configure LDAP..." button. Click on this and you will see a pane identical to the one in Address Book. Enter your server and Mail will auto-complete perfectly, but a little slower than addresses in your local book.

Final Thoughts

As we have seen, Apple's integration with LDAP in Panther is not without problems. We can hope for better in Tiger. Despite these shortcomings however, we can use the LDAP server in Mac OS X to share authentication and addresses around our network easily. Once you've mastered those basics, it's time to think about single sign-on with Kerberos and using your LDAP server with other services such as webmail.


A great deal of the information in the introduction of this article was found in LDAP System Administration by Gerald Carter. I would also like to thank the folks at the AFP548 eBBS for their help with getting the best out of LDAP on Mac OS X.

Tony Williams is currently a desktop support consultant at a major Australian university, specializing in Macintosh computers. He describes himself as a "professional Mac geek."

Return to

Copyright © 2009 O'Reilly Media, Inc.