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://ldap1.its.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://ldap1.its.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)
|
ldap1.its.hawaii.edu
|
ldap1.its.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://ldap1.its.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:
Here are screen shots of what Internet Explorer and Windows Explorer
on Windows 2000 Professional return:
and the details:
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:
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.
