LDapper 3.0b1 - by Carl W. Bell
Copyright © 1997-2012 Baylor University.

Wait...what? There's a new version of LDapper? Maybe the world really is going to end in 2012...

Disclaimer: Although LDapper seems to work fine, it is distributed "as is". Use at your own risk.

Note: This is a "beta" test version of LDapper and probably has bugs, especially when running on Snow Leopard. If you encounter any, please report them.

Note: If you got here using a web search engine, you can find the program here.

LDapper is a simple LDAP (Lightweight Directory Access Protocol) client for finding email addresses. You can look up people by name, department, or another arbitary attribute. Once you have a list of people, you can copy/paste or drag addresses into a new email message. Depending on your email client, you may be able to automagically add them to a new message by selecting the "Mail To:" command in the LDAP menu. You can export addresses directly into the Mac's Address Book or files that can be imported into other applications. You can also browse a directory in a hierarchical fashion.

Unlike older versions of LDapper which used the LDAP framework and OpenLDAP libraries directly, this version is really a "wrapper" around the built-in LDAP utility ldapsearch that is included by default with Mac OS X. You can think of LDapper as a GUI "front-end" to ldapsearch. Many of the options and preferences you specify simply modify the command line arguments to the ldapsearch command. This version of LDapper uses separate preferences than previous versions so you can continue to use an older version if you wish. The first time you run this version, LDapper will import any directories from the old version. Any subsequent changes to those directories will only affect the new version. This version of LDapper is 64 bit only and requires Mac OS X 10.6 (Snow Leopard) or later.

Directories

You will need to set up at least one directory before you can do a search. Open up Preferences and click the add (+) button. If you hold down the option key while clicking the add button, a copy of the current directory will be added. Click the edit (pencil) or delete (-) buttons to edit and delete directories. You can rearrange the directories in the list by dragging them. This will affect the order that they appear in a Search/Browse window's directory menu.

When editing a directory you can specify the directory's name (which can be whatever you want, but must be unique), the LDAP server's URI (e.g., "ldap://ldap.example.com/"), and an optional (but sometimes not so optional) search base. You can specify a TCP port if it is different from the normal LDAP port (389) by adding a ":port#" to the end of the URI. Although LDAP URIs can contain many things, LDapper only uses the server and port. If your directory supports StartTLS, you can have LDapper request (or require) TLS. By default, LDapper assumes that an LDAP server is an LDAPv3 server but you can tell it that your server is LDAPv2 if necessary.

You can change the LDAP attributes that LDapper uses when searching. While editing the directory, click the "Attributes" tab. These attributes (and default values) are Last Name (sn), Full Name (cn), Department (ou), Email Address (mail), and an optional "Other" attribute. You can also specify the value for the objectclass attribute (person) which is used when restricting searches to people. Unless you know that you need to change these, you should leave these set to their defaults. To reset the values to their defaults, click the "Default Attributes" button. There is also an option to tell LDapper to use the Last Name or Full Name attribute when sorting the Address List by name.

Searching a directory may require authentication. While editing the directory, click the "Authentication" tab. LDapper supports several methods of authentication:

Anonymous - No authentication.

Simple - No Password Required - Uses an ID (probably your "disinguished name") but no password.

Simple - With Password - Uses an ID and a password. Although the ldapsearch command supports specifying the password on the command line, this is a potential security risk. Instead, LDapper will use ldapsearch's -W option which tells ldapsearch to prompt for the password. You may see the prompt included in the Command Output text.

SASL - Simple Authentication and Security Layer. For SASL authentication, LDapper simply passes any options you specify, e.g., SASL mechanism, or properties, to the ldapsearch command.

Most users will probably use "Simple - With Password". LDapper can store the directory's password in the Mac OS X keychain so you won't be required to enter it every time you search. LDapper can also run the ldapwhoami command that you can use to test your authentication/authorization credentials.

Searching

Select the "New Search Window" command in the File menu to open a new search window with the default settings. You can change several of the settings, e.g., the directory and types of searches, before doing a search.

To perform a search, use the popup menu(s) to choose which attribute(s) you want to search for, the search type (is, is similar to, contains, starts with, ends with, is anything, is missing), enter some text in the search field(s), and then click the Search button or select the Search command in the LDAP menu or just press return. If required, you will be prompted for a password. If your password is stored in your keychain but you don't want to use it for some reason, or if you need to specify/change your identification, press the Option key while starting a search and you will always be prompted.

LDapper will build the ldapsearch command using the options you specify and then run ldapsearch. It will parse any output from the ldapsearch command and add the entries returned to the "Address List". If you just want to see the ldapsearch command and not actually run it, hold down the Control key when starting a search.

If you select a person in the Address List, their info will appear in the "Info" text at the bottom of the window. LDapper will save the actual output from the ldapsearch command. You can switch between the Info and the Command Output text by clicking on the Info/Output buttons. LDapper adds the ldapsearch command and its arguments at the top of the Command Output text. You should be able to copy the command and paste it in Terminal to run the ldapsearch command directly. If you just want to get the command but not actually perform a search, press the Shift key while starting a search. Also, any error text, i.e., stderr, will appear below the output. You can export the Info (or Command Output) text to a file.

Search Options:

Fetch attributes - which attributes should be fetched from the server? The choices are Minimal, All, Operational, All + Operational, and None. The default is to fetch All attributes. "Minimal" will fetch only the last name (sn), full name (cn), department (ou), email (mail), and "other" attributes specified for the directory. "Operational" returns attributes used by servers for administering the directory system itself. "None" will return just the "distinguished names" (dn) of any matching entries.

Max # hits - the maximum number of responses you want to receive from the LDAP server. Set this to 0 to indicate no limit. The default is 100. Note that there may be a limit set by the server. One interesting thing related to this value is that if your search uses too many resources on the server, e.g., searching on a non-indexed attribute, LDapper may receive a "max hits exceeded" error from the server even though there really weren't that many matches. This probably won't happen on normal searches.

Time limit - wait at most this long for a search to complete. Set this to 0 to wait forever. The default is 60 seconds.

Connect timeout - wait at most this long for the initial network connection to the LDAP server to complete. This is a separate timeout value than "Time limit" above. Note that if you have specified Request/Require StartTLS, this option is not used so if LDapper is unable to connect, you will probably end up waiting until the connection is timed out by the operating system, usually 75 seconds. I don't know if this is by design or a bug in ldapsearch.

Discard responses without email - should responses that are missing email addresses be ignored? If this is not enabled, entires in the list without email addresses will show "n/a" instead. You will not be able to include any of these (non-)addresses when preforming a "mailto" and they may be skipped when exporting as well. This option is ignored if you are fetching "Operational" or "None" attributes.

Search for people only - should LDapper limit a search to only people, i.e., those entries with an objectclass value of "person"? (This value can be modified when editing a directory.)

Show friendly attributes - specifies how attributes should be displayed in the "Info" field. If enabled, a more descriptive attribute is uses, e.g., "Last Name" instead of "sn". If disabled, the actual attribute is displayed.

Decode Base64 - should values that include Base64 encoded data, e.g., photos or text data with special characters, be decoded when adding to the Address List? Note that even if this is enabled, the Base64 encoded value will still appear in the Command Output text because it is meant to display the ldapsearch output verbatim.

Discard output - should output from the ldapsearch command be discarded instead of added to the Command Output text?

Copying/Dragging Addresses

Click one or more entries in the address list to select them. You can then copy/paste or drag them to your email application or to a text clipping in the Finder. Entries without email addresses will not be included. Different email applications handle copying (and dragging) of addresses differently. You will need to experiment with some settings to see what works best with your email application. You can specify in Preferences which delimiter you want to use to separate the entries. These include commas, new lines, tabs, semicolons, and spaces. If you have an application that uses some other delimiter, please let me know, and I'll add it to the list. If the "Include personal names" preference is enabled, you'll get "name <email>,name <email>". If disabled, you'll get "email,email". There is also a setting in Preferences to change the format from "name <email>" to "email (name)".

"Mail To:"

LDapper can automagically create a new email message pre-addressed with selected addresses if your email application supports this. This works the same way as if you had clicked on a "mailto:" URL in a web page so any program that can be set up as a mailto URL helper should work. LDapper will use your default email application. Select one or more entries in the address list, then select the "Mail To:" menu to send the address(es) to your email application. Double-clicking an address will do the same thing.

Note that sending addresses to your email application in this manner will not include personal names. If you want personal names, you must use copy/paste or drag and drop instead.

Exporting Info/Command Output

Depending on what is displayed in text at the bottom of the Search window, you can export the contents to a file. If you are exporting Info, you can save the text as plain text (.txt) or rich text format (.rtf) to get bold attributes. If the Info contains photos, you can save as rich text format with attachments (.rtfd) to include the photos in the file. Note that photos in the info are resized so that the maximum height or width is 256 pixels so it may be smaller that the actual image in the directory. (You can also drag images from the Info text and LDapper will create jpeg files.) Command Output text is always exported as plain text.

Exporting Addresses

You can export addresses by choosing an item in the "Export Addresses" menu. The current export formats are:

Address Book

This does not actually save to a file, but instead adds the addresses to the OS X Address Book. A group named "From LDapper" will be created and the addresses will be added to that group.

Address (Name)

address (name)
address (name)
address
address (name)
etc.

Name <Address>

name <address>
address
name <address>
name <address>
etc.

Pseudo LDIF

dn: the dn
attr: value
attr: value
attr: value
attr: value

dn: the dn
attr: value
attr: value
attr: value
attr: value

etc.

This is not a true LDIF file. Long lines are not folded, and images and binary values are replaced with the strings "<image data>" and "<binary data>". If you really need the original LDIF data, you can get it from the Command Output text or just run the ldapsearch command in Terminal.

Browsing

It is possible to "browse" an LDAP directory by choosing "New Browse Window" from the File menu. This will create a window with a hierarchical view of the currently selected directory. Click the small triangle to the left of an entry to expand the entry. This will display all of the entries one "level" down. Click the small triangle again to collapse the list. Selecting an entry will display its attributes and values in the text field below the list. Unlike a search window, you cannot copy/paste, drag and drop, export, or "mailto:" selected entries.

Browsing appends each command's output to the Command Output text rather than replacing it. As with Search windows, you can export the Info and Command Output text.

If you find yourself using LDapper to browse more often than search, you can use Preferences to switch the default document type to browse. Normally, LDapper uses Cmd-N to create a new search window and Shift-Cmd-N to create a new browse window. Switching the default document to browse swaps these. The default document type is also the type of window that is created when LDapper is first launched or when you switch to LDapper by clicking its icon in the dock (if there are no other documents open).

Release Notes

3.0b1 (26-Apr-2012) Initial beta release of "3.0" version.

Contact Info

If you have any questions, comments, (constructive) criticism, or bug reports, you can contact me at the address(es) below.

-cb

Carl_Bell@baylor.edu
Carl Bell's Web Page
Stuff I've Written

Snail Mail:

Carl W. Bell
Academic and Research Computing Services
Baylor University Electronic Library
One Bear Place #97148
Waco, TX 76798

Phone:

(254) 710-4065

Baylor's Boilerplate Fine Print

This software, data and/or documentation contain trade secrets and confidential information which are proprietary to Baylor University. Their use or disclosure in whole or in part without the express written permission of Baylor University is prohibited.

This software, data and/or documentation are also unpublished works protected under the copyright laws of the United States of America. If these works become published, the following notice shall apply:

Copyright © 1997-2012 Baylor University
All Rights Reserved

The name of Baylor University may not be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE, DATA AND/OR DOCUMENTATION ARE PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.

When permission has been granted to make copies of this software, data and/or documentation, the above notices must be retained on all copies.

Permission is hereby granted for non-commercial use and distribution of LDapper