Skip to end of metadata
Go to start of metadata

The University of Washington maintains several LDAP directories for highly reliable, platform-independent access to institutional data. The most well known is the White Pages directory of contact information for people at the UW, which is widely used by email address book software, but the other directories have more specialized contents, and if your application uses these directories, you may have to implement your own LDAP query functions. On this page, we take an elementary look at what what an LDAP client does. Some operations that may be obscure or relatively UW-specific are covered in special detail, with examples in C.

Software platforms

LDAP V3 functionality is available in just about any popular programming language, either implemented "from the ground up" as has been done in Java and Perl, or built on a C library like OpenLDAP. Whatever the software environment, the key question will typically be, whether it supports SSL and SASL "EXTERNAL" authentication, which will be required for access to directories other than the White Pages.

Some implementations support debug output, with a flag that controls the types of debugging output that will be produced. This information can save a lot of time when developing and installing an application, so where feasible it's worth the time to add a debugging configuration option to your application. Of course it's also important to print out all the diagnostic error information after an LDAP error.


Each of the directories we're talking about is actually supported by at least two independent host computers. Your LDAP connection addressed to the generic DNS name for the directory will take you to one of these computers chosen at random. You can make as many queries as needed during this connection, but you don't need to economize on connections, and in fact your connection will be terminated automatically after a short time if it stays idle.

The access privileges you enjoy during this session will depend on the name you bind with. This normally means a SASL bind with the EXTERNAL mechanism, and in that case your bind name will automatically be derived from your UW Services Certificate Authority X.509 SSL client certificate.

Because this is involves SSL, you have to establish SSL encryption before you try to bind. Our LDAP servers support two SSL options: a special SSL service port (usually 636) for clients that wish to negotiate SSL at the moment of connection, and a TLS option for clients that connect to the standard LDAP service port (389) and initiate TLS afterwards. For software that likes a URL, the SSL port will be ldaps:// rather than the normal ldap:// before the host name. If either is supported, TLS is more flexible in some ways.

Debugging output could be invaluable during this step!


LDAP directories are hierarchical - they have a branching tree structure that allows you to selectively focus your query. The structure of our directories is actually not very interesting, so it's kind of a formality for us, but a query must specify a base DN. (DN, or Distinguished Name, is a string built of names that describe the location of an entry, from the entry itself on the left to the root at the right.) The standard base DN is documented for each directory.

The query also has a scope relative to the base DN. We usually specify subtree scope, which may be the default for your software.

The final required parameter (unless you specified base scope) is the LDAP filter. This string specifies the attributes of entries that you want the query to return. It can be as complex as you want, or it can be as simple as "(uwNetID=somename)".

Most implementations support specify attribute constraints, a list of the attributes you want to be returned, so your program doesn't have to wade through as many irrelevant attributes.

If your query returns a lot of entries, it may run into limits imposed by the LDAP server. These limits are fairly generous, and we don't expect normal queries to come close to encountering them. If your application does exceed the entry limit, it will receive its results truncated to the limit, along with an error code indicating the problem. Of course this will likely be a disappointing result, but if it isn't a regular occurrence and it doesn't break your application, then it may just call for some provision in your application to communicate to the users that their search terms are too expansive. If your application can't work within the limit in normal use, then please contact us!

If the query returns no results, then it may not be authorized to get the data you requested. Insufficient authorization is not an LDAP error condition, and the result is identical to the result you would get if the data didn't exist at all.

Data Conventions

While our LDAP service technically supports UTF-8 character values, the actual data is all 7 bit US-ASCII. Searches are case-insensitive, with respect to attribute names, values, and distinguished names. The schema document for each directory outlines its objects and attributes.

There is no "missing value" value - attributes are simply omitted if they have no values.

  • No labels