Ask Us logo

LDAP Directory Service - Details

Overview

This page is intended to provide more details than the normal user would be want to deal with.  So, programmers of directory enabled applications, more curious individuals, and the like are the intended audience.

LDAP URLs

The Internet standard, RFC 2255, The LDAP URL Format, describes the format of an LDAP uniform resource locator (URL). It is one way to specify all of the information needed to lookup some information in an LDAP directory.  Netscape Communicator 4.7 understands LDAP URLs and can display a Web page with the search results neatly formatted with names of the attribute values that easier to understand.  Internet Explorer and Windows Explorer on the Windows platform may pop up the Address Book client to display the search results.  Netscape 6 on the Windows platform will do the same.

Given the configuration information in the above section, we can use an LDAP URL like the following to lookup a person with a first name of Michael:

ldap://ldap.hawaii.edu/ou=people, dc=hawaii,dc=edu??sub?(givenname=michael)
You don't usually want to do something like this when searching for your friend Michael as there would
typically be a lot of people with a first name of Michael.  So, you would probably want to use both the
first and last name to look a person up, something like:

ldap://ldap.hawaii.edu/ou=people,dc=hawaii,dc=edu??sub?(&(sn=test)(givenname=michael))
This should  result in a few directory entries being returned. Please note the particular construction of the
search portion of the LDAP URL.  It includes an ampersand ( & ) to indicate the logical combination of
first and last names to searched for.

The format of an LDAP URL is:

ldap://host/search_base?attrs?scope?search_filter
where the parts are:

URL part
Value for UH Directory
Comments
host (optionally :port)
ldap.hawaii.edu
ldap.hawaii.edu:389 (with port number)
search_base
ou=people, dc=hawaii, dc=edu
People subtree
attrs
blank means return all attributes
attributes to be returned from search
scope
sub (entire subtree)
scope of search
search_filter
(&(sn=wong)(givenname=michael))
varies depending on what you're searching for

It is also possible to limit the scope of the search to a single level below the search base by setting the scope to one instead of sub, like so:

ldap://ldap.hawaii.edu/ou=people,dc=hawaii,dc=edu??one?(&(sn=test)(givenname=michael))
In this case, limiting the search scope to a single level works because the ou=people, dc=hawaii, dc=edu subtree is flat and doesn't have child subtrees within it.

Directory enabled applications such as email readers already know how to construct the search filter from the common usage of LDAP attributes such as email address, last name, etc. Some . A list of attributes in the UH LDAP Directory Service is found below .

Here's a screen shot of what Netscape 4.7 returns:

Netscape 4.7 search results


Here are screen shots of what Internet Explorer and Windows Explorer on Windows 2000 Professional return:

Internet Explorer search results - first screen

and the details:

Internet Explorer search results - second screen


Search Scope and Base

Search scope is the extent to which the directory tree or a portion of the tree (subtree) is searched.  Since the directory information is structured in a tree-like fashion, it is possible to limit the searching to a single level, one level below the search base level, or all of the levels below the search base level. The search base identifies either the entire directory tree or subtree that searches are to start at.

Search Scope
Extent of search
base
Limited to only the search base
one
Limited to the search base and one level below it
sub
Limited to the entire subtree of the search base

The search base is a distinguished name (DN) that identifies either the entire directory tree or a subtree of  the directory.  The UH LDAP directory tree is structure with people placed in a People subtree with a DN of ou=people, dc=hawaii, dc=edu . Here's a schematic of the directory tree:

UH LDAP directory tree  
For the most part, only the People subtree (ou=People, dc=hawaii, dc=edu) is of interest. The Specials subtree is used to hold groups and special DNs for controlling access to attributes.  This subtree would not normally be of interest to users.  It is how different views of the data are implemented to provide privacy for certain pieces of data.


Attributes in the LDAP Directory Service

The attributes that would typically contain information are:

Attribute
Description
Example
uid
ITS username
testfaculty
cn
full name in "first middle last" format
Faculty Madonna Testfaculty
givenName
first name
Faculty
sn
last name
Testfaculty
eduPersonAffiliation
affiliation
This is a multi-valued attribute, so it may have zero or more of these values:
student
staff
faculty
other(this value will eventually go away)
eduPersonOrgDn
campus
This is a multi-valued attribute, so it may have zero or more of these values:
uhm(Manoa)
uhh(Hilo)
uhwo(West O'ahu)
hawcc(Hawai'i)
hcc(Honolulu)
kcc(Kapi'olani)
kauaicc(Kaua'i)
lcc(Leeward)
mauicc(Maui)
wcc(Windward)
uhsystem(organization under the UH system itself, e.g.President's office)
uh(one of the above but don't have exact information)
rcuh(Research Corporation for the University of Hawai'i)
uhf(UH Foundation)
uhs(UH Lab School)
ewc(East West Center)
other
mail
email address(es)
test.faculty@somewhere.tbktu
uhPreferredMail
preferred email address
test.faculty@somewhere.tbktu
uhOrgAffiliation
affiliation with a campus
This is a multi-valued attribute, so it may have zero or more values formatted like this:

  eduPersonOrgDN=uhm, eduPersonAffiliation=faculty

with the exception that this attribute can also have the following values for eduPersonAffiliation:
financial-aid-applicant(self-explanatory)
accepted-applicant(self-explanatory)
ohana(anyone who has left the University but has opted to retain services we may provide to our 'ohana)
title
title
Asst Prof
ou
department, campus
English,
University of Hawaii at Manoa

physicalDeliveryOfficeName
office location
XC 9718
telephoneNumber
office telephone number
(808) 975-7170
facsimileTelephoneNumber
office fax number
(808) 975-7629

Please note that the ou or organizational unit attribute is multi-valued and contains both the department and campus. There is no distinction made between the two values so one would not know which one is which.  They are both treated as organizational unit values.  The same thing is true of the mail attribute.  It can hold many values.  To know which one is the person's preferred email address, you would have to look at the uhPreferredMail attribute.  The uhPreferredMail attribute is one of an extended schema that we have implemented for UH.  See the section below on Schema Extensions .

Why is LDAP is not structured like a relational database?

The data in LDAP is structured in a flat way in the sense that when you get a record for an entry you will have a list of attributes with values for that entry.  Each entry is a container of data about that entry which means that your query will return a list of attributes values for each DN matching your query.  An example is multiple affiliation at multiple campuses.  A query would return all the affiliations and all the campuses for each DN but not the relationship between affiliation and campus.  That is the problem we currently have with UNISON.  While most entries might have a single affiliation and a single campus, it creates a problem when applications try to use LDAP to authorize a person.  For example, suppose the Kapiolani Community College (KCC) Library subscribes to an online service but contractually can only provide the service to KCC students.  They would not be able to use LDAP if they got back affiliations = "student, staff" and ou = "KCC, LCC, UHM"
because the relationship between affiliation and campus is not specified.  We have created a UH-specific attribute that captures the relationship but UNISON (our metadirectory) does not currently relate affiliation with campus.  The next generation of UNISON, UNISON 2, is in progress and is intended to do so.  Another way to look at this issue (from a data modeling perspective) is that a relational database is typically structured to have tables with one or more records with no repeating data fields.  LDAP will yield results with repeating data fields.

Distinguished Name (DN)

A distinguished name (DN) is the unique identifier for each entry in the directory tree.  It typically takes the form of one or more attributes with a single value in the format of attr=value without spaces between the attr, =, and value. Here are some examples:

uhUuid=its_id, ou=People, dc=hawaii, dc=edu
uid=user_name, dc=hawaii, dc=edu
cn=full_name, ou=dept, o=university of hawaii, c=us


We use the format, uhUuid=its_id, ou=People, dc=hawaii, dc=edu , for entries about people.  The DN for the entire tree is dc=hawaii, dc=edu. For the most part, attributes are  case insensitiveand searching for most attributes is also ccase insensitive

LDAP Directory terminology

Term
Meaning or usage
attribute
Data field, holds data about the directory entry
bind
Connecting to the directory server
distinguished name
Primary key to entries in the directory
search base
Portion of  the directory tree that search will take place in
search scope
How deep into the directory subtree or tree should searches look
directory tree
The entire set of information in a directory is organized into a tree structure
directory subtree
Portion or subset of directory tree, such as ou=People
LDAP
lightweight directory access protocol


Schema Extensions

The eduPerson and uhEduPerson schemas have been added to the LDAP Directory Service. The eduPerson schema is defined by the Internet2 consortium.  The uhEduPerson builds along similar lines but is designed to accommodate UH-specific needs.

Using LDAP with Applications

If you think that you would like to use LDAP with applications or other systems, please contact the ITS IAM Group.   There are many possibilities so it is important to identify your requirements and review them with ITS Systems Engineering staff so that LDAP can be useful to the UH community.

To authenticate a user using their UH Username and password, see Authenticating Users.