Lesson 3. Accessing Mac OS X Server Directory Services

Time

This lesson takes approximately 2 hours to complete.

Goals

Understand how data is structured and how entries are distinguished in an LDAP database Use command-line and GUI tools to search for a specific entries in a given LDAP database Use Directory Access to add a Mac OS X server providing directory services for user authentication Troubleshoot problems with Open Directory records retrieved from an LDAP database Interpret entries in a network user account to determine why a user is unable to log in correctly

Data is valuable only if it can be stored and accessed. With multiple vendors of directory services solutions competing for your business, you may worry that their disparate systems will not be able to interoperate and that it will be difficult for clients to support multiple vendors. Lightweight Directory Access Protocol (LDAP) addresses these concerns by providing a protocol that all vendors can support while still being able to differentiate themselves on the basis of additional features, over and above what a simple data access protocol dictates.

This lesson introduces you to the LDAP specification and explains Mac OS X support for this nearly universal protocol. In Lesson 2, “Accessing Local Directory Services,” you saw how Open Directory provides a means of retrieving information from a local data store to identify and authenticate user accounts on the local computer. Now you’ll learn how to request and retrieve identification information stored in an LDAP directory on the network, in particular, the LDAP directory on Mac OS X Server.

By accessing the directory in Mac OS X Server on your network, you can take advantage of features such as automounting share points, preferences management, and mobile user accounts.

Understanding LDAP

LDAP is an industry-standard method of accessing data from within a directory. If your organization already has a network directory service in place, it is likely that the directory is based on LDAP or is accessible via LDAP. LDAP is many things, and can be described in different ways. It is:

• An information model. It defines how data is accessed.

• A namespace. It defines how to distinguish one piece of data from another, similar to a URL.

• A protocol. It defines how a client can read, write, and search for data.

• A distribution model. LDAPv3 defines how to distribute the logical information model physically. This means that data can be partitioned and stored on multiple hosts, while still being one logical directory.

• A way to standardize access to directory data, regardless of how or where that data is stored. This standardization, while simple in in concept, is quite complex in implementation, requiring standardized naming (the namespace) and standardized searching.

• Extensible. It can be customized to fit any organization’s directory services needs.

LDAP Information Model

The basic unit of LDAP is an entry, or an instance of related attributes. It consists of one or more attributes and the values for those attributes in the following format:

attribute=value

LDAP uses the schema to define attributes, among other things. An object class specifies which attributes are required when populating the LDAP directory and which attributes will be allowed when populating the LDAP directory. This attribute definition provides data integrity.

Object classes are defined in the schema. Because LDAP is so customizable, the schema can be tailored to meet the needs of many different deployments.

The LDAP Tree

An LDAP directory is arranged in a hierarchy called a tree. In a tree, each entry can have entries beneath it. One useful aspect of LDAP is that the structure of an LDAP hierarchy is not strictly defined, so it is open to different implementations depending on the site. This can lead to confusion when attempting to understand someone else’s deployment, because the hierarchy has been customized.

The attributes are usually an abbreviation or mnemonic for a typical characteristic. For instance, dc stands for domain component and cn stands for common name. These abbreviations can be used in several locations within the tree and may not be specific to each entry within each entry.

LDAP Namespace

Because the structure of an LDAP directory can be different at each site, you have to tell any LDAP client where to find an entry. To request a particular entry, the client uses the logical path to the entry or the distinguished name (dn). This is similar to an absolute path in the Mac OS X file system. Here is an example of the dn for Warren Peece:

dn:uidNumber=501,cn=users,dc=mainserver,dc=pretendco,dc=com

The structure of the LDAP hierarchy is defined by the distinguished names.

In addition, one or more attributes in an entry can be used as the name of the entry itself. This is the entry’s relative distinguished name (rdn), which is similar to a relative path in the Mac OS X file system. For example

rdn:uidNumber=501

refers to all the attribute/value pairs in that entry.

LDAP Search Parameters

When a requestor (such as a login window) asks for data, some parameters must be defined.

Search Base

The search base is the point in the tree where the requestor starts the search. For instance, the client might want to start searching at the entry cn=users. If this is the case, then the search base would be defined as

cn=users,dc=mainserver,dc=pretendco,dc=com

Scope

The scope defines how deep to go in the search. For instance, the search could be limited to the same level the search started, limited to the same level and one level below, or open to all levels below the one where the search started. This becomes important when searching a large LDAP database or using applications that frequently query the database. Walking down the entire tree consumes processor cycles and RAM, which can be avoided by refining the scope of the search.

Filter

Finally, a filter specifies the item that is being searched for. In Mac OS X, the filter is automatically constructed by the LDAPv3 plug-in. Filters, like scopes, can decrease the load on the directory by not searching entries that do not fit certain criteria. For example, a request might be made to find any cn entries under cn=users. However, since the information under cn=users may or may not be only user information, you can narrow the search to save time, which you’re about to learn how to do.

LDAP Search Transactions

When searching the LDAP directory with a tool such as ldapsearch, you would limit the request by specifying the search base and filter. The following figure demonstrates how to search for the mount entries in the LDAP directory on mainserver.pretendco.com.

Breaking down the line of code in the figure above, you can see it does the following:

• The -LLL option specifies that you want the output to be in standard LDAP Interchange Format (LDIF).

• The -x option tells ldapsearch to make a simple (non-SASL) bind to the directory.

• The -H option is used to specify the server (by URL) hosting the LDAP directory.

• The -b option is used to specify the search base. In this figure, the filter specifies that you are looking for any entries where the objectClass attribute is equal to apple-group.

At the end of the search command, you can specify which attributes you want displayed from the resulting entries. In this case, the attributes are the common name and the objectClass. By default, the search is performed at the level indicated by the search base and in all subtrees.

The results of the search are a listing of all the group entries (the dn, cn, and objectClass attributes listed) at the dc=mainserver,dc=pretendco,dc=com level and below. The information is displayed in standard LDIF.

You can also use the ldapsearch command to display information about the root or base dn of an LDAP tree. For example,

ldapsearch -h "10.1.0.1" -x -a never -s base supportedSASLMechanisms namingContexts
supportedLDAPVersion

will display the names of the SASL mechanisms, the naming contexts, and the versions of the LDAP protocol that are supported by the server named 10.1.0.1.

Using the LDAPv3 Plug-in

Due to LDAP’s broad adoption by most directory-service vendors, the Mac OS X DirectoryService LDAP plug-in allows Mac OS X to integrate with most directory-service environments. Mac OS X supports connecting to an LDAP server using version 2 or 3 of the LDAP protocol; however, the LDAPv3 plug-in supports only full read/write access to an LDAPv3 directory. The figure below illustrates that the directoryservice process uses the LDAPv3 plug-in to access an LDAP data store via the LDAP protocol.

Directory Access is the primary tool for configuring the LDAPv3 plug-in. Within Directory Access, there are two ways to configure the LDAPv3 plug-in to access an LDAP server running on Mac OS X Server.

The first method is to use a DHCP-supplied LDAP server. To use this option, the LDAP configuration must be included with the information that your DHCP server provides. If an LDAP server’s address and search base are provided by the DHCP server and pushed down over the appropriate option, Mac OS X will automatically bind to the server, and applications will have access to the directory’s data through Open Directory without any additional configuration.

However, the server is not automatically added to the authentication or contacts search path by default. To be able to log in using user accounts on an LDAP server provided by DHCP, you must enable the checkbox for the “Add DHCP-supplied LDAP server to automatic search policies” option or manually add the server in the Authentication and Contacts panes, both of which can be accessed by editing the LDAPv3 plug-in using the Directory Access application.

You can also create a configuration for the LDAPv3 plug-in and manually set the connection, search and mapping, and security parameters. If you’re connecting to an LDAP server running on a Mac OS X server, you only need to provide the server address in the Connection pane and click one button to have Mac OS X automatically bind to the LDAP server.

If a more customized schema is used, you can choose to map record types and attributes to LDAP object classes and attributes. In the Search & Mappings pane, the “any” and “all” choices in the “Map to...items in list” pop-up menu (under the Edit menu of the LDAPv3 plug-in when selecting a configured LDAP server to which you are going to bind) define which object classes or attributes are necessary when returning a result. The default is “all,” which means a search will return only those entries that contain all of the values listed on the right. If you choose “any,” the search will return entries that have any of the values.

Whereas LDAP supports limiting the scope of a search to the base object (base) and one level down (one) or to all subtrees (sub), Directory Access does not offer all of these options. Directory Access will limit the scope of the search to all subtrees (sub) or to first level only (one), as shown in the figure below.

In the list of LDAP configurations, you can use Secure Sockets Layer (SSL) for the connection between your computer and the LDAP server by selecting the SSL option next to the LDAP configuration in the LDAPv3 plug-in. Other security options for an LDAP configuration can be selected by choosing the LDAP configuration you want to modify, and clicking the Edit button. Click the Security tab (as shown in the figure below) to see additional security options. The options that are available depend on the configuration and capabilities of the LDAP server.

If you select the “Use authentication when connecting” option, the LDAPv3 connection authenticates with the directory when it connects by providing a dn and password. The security options are explained further in Lesson 7, “Hosting OpenLDAP.”

Troubleshooting the LDAP Connection

The components of a successful remote connection to an LDAP database include:

• An active connection to the server where the LDAP database is located

• A successful binding to the LDAP database

• An appropriate LDAP plug-in configuration

If you are experiencing problems with your LDAP connection, you should isolate it to one of these three areas.

First establish that you have an active connection to the server. Check your network connection, and make sure that you have configured the LDAP plug-in with the correct server address information. If you’re using DHCP to receive this information from the server, use ipconfig to verify the configuration.

If you’re not using DHCP to receive this information, use Directory Access to configure the LDAPv3 plug-in with the server address and search base. Verify that “Access this LDAPv3 server using Open Directory Server” is selected, and don’t remap any of the record types and attributes.

If your connection to the server is working but you’re still having problems, you should verify that the information you need is actually in the database. You can use:

• ldapsearch to make a request directly from the LDAP directory

• dscl to check if the attributes and associated values are correct

• Third-party tools, such as LDapper (http://www3.baylor.edu:80/~Carl_Bell/stuff.html) or LDAPManager (http://sourceforge.net/projects/ldapmanager)

• Directory Access to make sure Mac OS X will bind to the correct directory service.

Use these tools to search the directory for entries with objectClass=mount. This search will list the volumes that should be automounted. If the search returns the results you expect, then you have verified that the directory contains the correct information and that your client is receiving it correctly.

If the directory does not return correct information for mounts, verify that the file servers are functioning properly and that your user account has authorization to use the server (as well as enough user licenses).

If the requests are returning incorrect information or no information, tell your directory administrator to modify the directory using Workgroup Manager.

Mapping Open Directory Records to LDAP Entries

Open Directory contains predefined record types that are automatically mapped to LDAP entries on Mac OS X Server. When Open Directory receives requests for information, such as users or mounts, using the LDAPv3 plug-in builds the search at that time for that information based on the mappings. This is because Open Directory record types are also mapped to LDAP search bases and object classes. When the LDAP plug-in requests a particular piece of information, it knows where in the LDAP directory to find it based on the search base and one or more object classes. The plug-in also parses the results based on those same mappings. This presents a unified request for data from requestors to Open Directory, and thus the LDAP mappings are transparent to the requestor (or application) that originated the request.

Mapping Open Directory Records to LDAP Attributes

Although the search base tells Open Directory how to query an LDAP server for a given type of entry, Open Directory must be told how to use the information found in the entry. For this reason, Open Directory attributes are mapped to LDAP attributes. The mapping tells Open Directory which LDAP attributes hold the specific data Open Directory is looking for.

Workgroup Manager defines all attributes as either Standard or Native attributes. Standard attributes are Open Directory attributes, and Native attributes are OpenLDAP attributes. You can choose to see either or both sets of attributes by clicking the Options button within the Inspector tab of Workgroup Manager. Each set of attributes can also be preceded by their respective prefixes; however, viewing the prefixes is not absolutely necessary to obtain a better understanding of the automatic mapping of attributes.

Default Initial Attribute Names in Mac OS X Server

Understanding Similar LDAP Attributes

Although some LDAP attributes seem similar to Open Directory attributes, their uses are very different. The following definitions refer to a default configuration of the LDAPv3 plug-in on Mac OS X and a default configuration of the LDAP directory on Mac OS X Server:

• uid: This attribute in an LDAP directory refers to the short name of a user account. In Open Directory, this is one of the attributes mapped to RecordName. This attribute should not be confused with the user’s ID used in the Mac OS X file system.

• uidNumber: This attribute is mapped to the UniqueID attribute in Open Directory, and the value is the same as the user’s ID used in the file system. Much of the process of associating files to user accounts and determining authorization is done using the user’s ID.

• apple-generateduid: This attribute is unique to Mac OS X. It maps to the Open Directory attribute GeneratedUID, and its value is a 128-bit value.

For user accounts, there are two available attributes for home folders in LDAP:

• homeDirectory: This LDAP attribute maps to the Open Directory attribute NFSHomeDirectory. The value of this attribute is the local file-system path to the user’s home folder (for example, /Users/johnsigna).

• apple-user-homeurl: This attribute maps to the HomeDirectory attribute in Open Directory. The value of this attribute is a tagged entry that specifies the URL and share point for the location of a home folder, regardless of whether it is an Apple Filing Protocol (AFP) or SMB-based home folder.

It is critical that these attribute differences be understood. It’s just human nature to see what we want to see, and mistakenly assume that UID stands for a user’s ID value rather than the short name for a user account.

Networked User Attributes

LDAP and Open Directory make it possible to use network user accounts to store and administer account information in a remote data store, thus removing the need to handle many local accounts.

Network user accounts offer the following benefits:

• Network home folders enable administrators to provide users with a consistent, controlled interface while providing access to their documents from any computer.

• Administrators can manage clients by controlling permissions on mobile computers and reserve certain resources for specific groups or individuals.

• Administrators can secure computer usage in “open” environments, such as administrative offices, classrooms, kiosks, or computer labs.

In addition to the standard attributes for user accounts, network user accounts make use of the following attributes:

• HomeDirectory: The location of an AFP-based home folder in UTF-8 XML text. The value for this attribute must be accurate for network users to log in.

• MCXSettings: The managed preferences for the user, stored in a multivalued UTF-8 XML plist.

• MCXFlags: Determines whether the MCXSettings attribute is loaded, stored in a single valued UTF-8 XML plist.

Managed Client Attributes

The configurations for managed client and mobile account options are stored in the LDAP directory using the apple-mcxsettings and apple-mcxflags attributes. Each user, group, or computer account that has managed preferences enforced would have a base-64 value assigned to those attributes in the entry. The information is stored as encoded XML code that will be interpreted by the client computer when it binds to the LDAP server. The results are placed on the client based on the type of settings. Depending on the number of preferences managed, the mcxsettings value can be quite large. While this is not a problem, it does permit the administrator to paste the value into any text editor and manually edit any values he or she wants, then paste the string back into the value field.

The managed preferences, when passed down to Mac OS X, can reside in several places:

• Managed preferences for the current user are placed in ~/Library/Preferences and include mobile account settings for the user.

• Managed login preferences are placed in /Library/Managed Preferences/username, where username is the name of the logged in user.

• Managed startup (boot) preferences are placed in /Library/Managed Preferences.

Managed group preferences are applied when the login window appears, and managed computer and mount settings are applied when the computer boots.

The data is also stored in mcx_cache in the local NetInfo database (/var/db/netinfo/ local.nidb) for offline use. This information can be removed from the database using NetInfo Manager or Workgroup Manager running locally.

Working With Mount Records

Mac OS X computers using network user accounts need to access networked volumes at startup (prior to logging in). Open Directory specifies a mount record, which contains information about these network volumes so a startup process can automatically mount them, regardless of which user logs in.

Mac OS X computers prepared for use with network user accounts typically don’t store this information in their local NetInfo database, as that information can become out-dated and each Mac OS X computer’s NetInfo database would need to be updated manually. At startup, the automount daemon queries Open Directory for mount records. In response, directoryservice plug-ins that have been preconfigured with remote server information search the databases on those servers for mount records. The automount daemon uses the information from any mount records that are returned to mount the appropriate volumes. This type of automount is supported for AFP and network file system (NFS), but not for SMB.

The following table lists a mount record’s attributes.

For some types of servers, you may not be able to rely on the mount record being stored on the server. You can add mount records to the client’s local NetInfo database using dscl, NetInfo Manager, or Workgroup Manager.

If the computer won’t boot to multiuser mode after you modify the mounts record, delete the record in single-user mode, restart the computer, and enter the data again.

If you can browse a computer but you cannot connect, try the following:

• Look for network problems. Check physical connections and try to ping the server. Try other services from the same server. If more than one protocol is affected, you should troubleshoot your network connection.

• If you get a login dialog but can’t mount the volume, the connection is good and authentication is the most likely problem. Verify the user name and password. A good way to do this is using id and su from the command line.

• If you have a problem mounting from the Finder, try mounting from the command line. You may get more information from error messages.

• Verify the permissions of the folder you’re mounting on.

• Verify that the URL you are using is correct.

Try connecting from a different computer. If the service appears on that computer, find out what is different. Look at Network preferences and Directory Access settings, for example.

Troubleshooting Home Directories

The majority of problems encountered come from users not being able to connect. This happens primarily at login, so a good idea is to check the directory-service binding first. Use dscl to verify that the Mac OS X computer is binding to the server and is able to access the data. If it is not binding, use an LDAP browsing utility such as LDapper or LDAPManager to verify that you have the correct server address and search base.

1. Make sure the client is bound to the correct directory.

Your organization may be using two different LDAP servers: one for user account information and one for contact information (this is often the case). If the computer is binding to the server providing contact information, users will not have access to their user accounts. Use an LDAP browsing tool again to verify that the server to which the computer is binding is providing user accounts.

2. Try a different user account.

If the problem is isolated to just one account, compare the values of the two accounts to isolate the cause of the problem.

3. Verify the file server is accessible.

If a user is able to log in but unable to access the correct home folder, the file server might not be accessible, the mount record for the share point is absent or invalid, or the home directory attributes are incorrect.

You can also run lookupd -q mount -a allMounts to help discover directory data issues with the mounts.

What You’ve Learned

• Lightweight Directory Access Protocol (LDAP) is an industry-standard way to access data from within a directory. It runs on Mac OS X Server.

• You can use the command-line tool ldapsearch to search for a specific entry in a given LDAP database, or use a GUI tool, such as LDapper, to search for a specific entry in a given LDAP database.

• Requestors need identification and authentication information that can be stored on Mac OS X Server.

• The LDAP directory on Mac OS X Server is accessed from a client using the LDAPv3 plug-in.

• Directory Access can be used to configure a Mac OS X client computer to bind to an LDAP server using address and search base values provided by DHCP or a Mac OS X server providing LDAP service.

• The dscl command-line tool verifies that a Mac OS X client computer is bound to a Mac OS X server providing directory services.

• Directory Access can add a Mac OS X server providing directory services to the list of servers used for user authentication so that a user can log in to the client computer using a user account stored on the server.

• The ipconfig command verifies that a client computer is receiving LDAP configuration information from a DHCP server.

• Directory Access can add a Mac OS X LDAP server to the list of directory servers for user authentication.

References

Administration Guides

“Mac OS X Server Open Directory Administration”: http://images.apple.com/server/pdfs/Open_Directory_v10.4.pdf

“Mac OS X Server User Management”: http://images.apple.com/server/pdfs/User_Management_Admin_v10.4.pdf

“Mac OS X Server Command-Line Administration”: http://images.apple.com/server/pdfs/Command_Line_v10.4.pdf

Apple Knowledge Base Documents

The following Knowledge Base document (located at www.apple.com/support) provides further information about accessing LDAP data stores.

Document 107695, “Mac OS X Server v10.3 or later: Avoid spaces and long names in network home directory name, path”

Books

Carter, Gerald. LDAP System Administration (O’Reilly, 2003).

URLs

The application LDapper author’s website: Carl Bell: http://carl-bell-2.baylor.edu/~Carl_Bell/stuff.html

The main OpenLDAP website: www.openldap.org

Lesson Review

1. What is the basic unit of an LDAP directory, and how are these units arranged?

2. What process allows Mac OS X to use the LDAP directory on Mac OS X Server?

3. Which command would you use to view the DHCP packet that the client accepted from the DHCP server?

4. What does the LDAP plug-in do? What tool in Mac OS X can you use to configure the LDAP plug-in?

5. If a client computer is having problems accessing an LDAP server provided by DHCP, what would be an appropriate early troubleshooting step to take?

6. What attribute in an LDAP user record maps to the Open Directory RecordName attribute?

7. What attribute in an Open Directory user record maps to the uidNumber attribute in an LDAP user record?

8. What are some of the advantages of a network user account?

9. Which attribute stores the managed preferences for network user accounts?

Answers

1. The basic unit of the LDAP directory is an entry, and entries are arranged in a hierarchy called a tree.

2. DirectoryService through the LDAPv3 plug-in

3. getpacket

4. The LDAP plug-in allows Mac OS X to integrate with LDAP directories. Use Directory Access to configure the LDAP plug-in.

5. Use ipconfig and verify that the LDAP url parameter provided by Option 95 contains the correct value for the server.

6. uid

7. UniqueID

8. Administrators can use network home directories to provide users with a consistent, controlled interface while providing access to their documents from any computer. You can control permissions on mobile computers and reserve certain resources for specific groups or individuals.

9. MCXSettings and MCXFlags