IETF LDAPEXT Working Group Roland Hedberg
Internet-Draft Catalogix
Expires: January 12, 2000 July 12, 2000
Referrals in LDAP Directories
<draft-ietf-ldapext-refer-00.txt>
Status of this Memo
This document is an Internet-Draft and is in full conformance with
all provisions of Section 10 of RFC2026.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that
other groups may also distribute working documents as
Internet-Drafts.
Internet-Drafts are draft documents valid for a maximum of six
months and may be updated, replaced, or obsoleted by other documents
at any time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt
The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html.
This Internet-Draft will expire on January 12, 2000.
Copyright Notice
Copyright (C) The Internet Society (2000). All Rights Reserved.
Hedberg Expires September 30, 2000 [Page 1]
Internet-Draft LDAP Knowledge references July 2000
Abstract
This document defines two reference attributes and associated "referral"
object class for representing generic knowledge information in LDAP
directories [RFC2251].
The attribute uses URIs [RFC1738] to represent knowledge,
enabling LDAP and non-LDAP services alike to be referenced.
The object class can be used to construct entries in an LDAP directory
containing references to other directories or services. This document
also defines procedures directory servers should follow when supporting
these schema elements and when responding to requests for which the
directory server does not contain the requested object but may contain
some knowledge of the location of the requested object.
1. Background and intended usage
The broadening of interest in LDAP directories beyond their use as front
ends to X.500 directories has created a need to represent knowledge
information in a more general way. Knowledge information is information
about one or more servers maintained in another server, used to link
servers and services together.
This document is based on the following basic assumptions:
- several naming domains
The usage of LDAP as a access protocol to other than X.500 servers has
created islands of directory service systems containing one or more
LDAP servers. Each of these islands are free to pick their own naming
domain. And that they also do; some use the old country,organization,
organizationalUnit naming scheme[X.521], some use the newer domain name
based naming scheme but these two are in no way the only ones in use. The
existence of several naming domains are in itself no real problem as
long as they produce unique names for the objects in the directory.
Still naming schemes like the domain name based one, might easily create
non-continues naming structures because some toplevel domain names
might no find organizations that are interested and/or willing
to manage them. Therefor tree transversal might not longer be possible
except in parts of the whole tree.
- authoritive structure vs directory structure
In some instances even if a part of the tree is delegated to one
organization, the organization doing the delegation might want to
remain as the authority for the baseobject of the delegated tree.
- support for onelevel searches
At points in the tree where the responsibility for all or almost all
of the children of a object is delegated to different organizations
and resides in different directory servers a one-level search is not
very efficient if not supported by special facilities in the directory
as such.
Hedberg Expires September 30, 2000 [Page 2]
Internet-Draft LDAP Knowledge references July 2000
-- directory server discovery
LDAP servers that do not use dc nameing or are not registered with
SRV records in the DNS are very hard to find.
This document defines a general method of representing knowledge
information in LDAP directories, based on URIs.
Two types of knowledge reference are defined: refer and subRefer.
The key words "MUST", "SHOULD", and "MAY" used in this document are to
be interpreted as described in [RFC2119].
2. Knowledge references
2.1 The refer attribute
( 1.2.752.17.1.100
NAME 'refer'
DESC 'URL reference'
EQUALITY caseExactIA5Match
SYNTAX 1.3.6.1.4.1.1466.115.121.1.26
USAGE distributedOperation )
The refer attribute type has IA5 syntax and is case sensitive.
It is multivalued. Values placed in the attribute MUST conform to the
specification given for the labeledURI attribute as defined in [RFC2079].
The labeledURI specification defines a format that is a URI,
optionally followed by whitespace and a label. This document does not
make use of the label portion of the syntax. Future documents MAY enable
new functionality by imposing additional structure on the label portion
of the syntax as it appears in a refer attribute.
If the URI contained in a refer attribute refers to an LDAP
server, it must be in the LDAP URI format described in [RFC2255].
When returning a referral result, the server must not return the label
portion of the labeledURI as part of the referral. Only the URI portion
of the refer attributes should be returned.
The refer attribute can be further specified by the use of options as
defined in section 4.1.5 of [RFC2251]. This document defines five
options and their use. Future documents might defined other options.
The options defined are:
"me", "sup", "cross", "nssr" and "sub" .
'refer;me' is used to hold the reference of this server, and is always
held in the root DSE
'refer;sup' is used to hold the reference of a server superior to this
one in this global LDAP naming domain e.g. a server holding the dc=com,
dc=se, or the c=se node. The 'refer;sup' is always held in the root DSE.
Hedberg Expires September 30, 2000 [Page 3]
Internet-Draft LDAP Knowledge references July 2000
'refer;cross' indicates that this is a cross reference pointing to another
naming context within or outside this global LDAP naming domain.
'refer;sub' indicates that this is a subordinate reference pointing to
a subordinate naming context in this global LDAP naming domain.
'refer;nssr' indicates that this is a non-specific subordinate reference
pointing to a subordinate naming context in this global LDAP naming domain.
3. Use of the knowledge attribute
Except when the manageDsaIT control (documented in section 6 of this
document) is present in the operation request, the refer attribute is not
visible to clients, except as its value is returned in referrals or con-
tinuation references.
If the manageDsaIT control is not set, and the entry named in a request
contains the refer attribute, and the entry is not the root DSE, the
server returns an LDAPResult with the resultCode field set to "referral"
and the referral field set to contain the value(s) of the refer attribute
minus any optional trailing whitespace and labels that might be present.
If the manageDsaIT control is not set, and an entry containing the ref
attribute is in the scope of a one level or subtree search request, the
server returns a SearchResultReference for each such entry containing
the value(s) of the entry's refer attribute.
When the manageDsaIT control is present in a request, the server will
treat an entry containing the refer attribute as an ordinary entry, and
the refer attribute as an ordinary attribute, and the server will not
return referrals or continuation references corresponding to refer
attributes.
4 Behaviour specification
4.1 Name resolution for any operation
Clients SHOULD perform at least simple "depth-of-referral count" loop
detection by incrementing a counter each time a new set of referrals is
received. (The maximum value for this count SHOULD be twice the number
of RDNs in the target object less one, to allow for ascending and
descending the DIT.) Clients MAY perform more sophisticated loop
detection, for example not chasing the same referral twice.
Case 1: The target entry is not held by the server and is
superior to some entry held by the server.
If the server DSE contains a "refer;sup" attribute then
the server will return an LDAPResult with the result code field set
Hedberg Expires September 30, 2000 [Page 4]
Internet-Draft LDAP Knowledge references July 2000
to referral, and the referral field set to contain the value(s) of
the "refer;sup" attribute minus any optional trailing whitespace and
labels that might be present.
Case 2: The target entry is not held by the server and is
subordinate to some entry, held by the server, that contains a
refer attribute.
The server will return an LDAPResult with the result code field set
to referral, and the referral field set to contain the value(s) of
the refer attribute minus any optional trailing whitespace and labels
that might be present.
Case 3: The target entry is held by the server and contains a
refer attribute without the 'nssr' option.
The server will return an LDAPResult with the result code field set
to referral, and the referral field set to contain the value(s) of
the refer attribute minus any optional trailing whitespace and labels
that might be present.
Case 4: The target entry is not held by the server, and is not
subordinate or superior to any object held by the server.
If the server contains a "refer;cross" attribute
in the root DSE with a baseobject that is either the same or
superior to the target entry then
the server will return an LDAPResult with the result code field set
to referral, and the referral field set to contain the value(s) of
these refer attributes minus any optional trailing whitespace and labels
that might be present.
4.2 Search evaluation
For search operations, once the base object has been found and
determined NOT to contain a refer attribute without the 'nssr'
option, the search may progress.
4.2.1 base-level
If the entry matches the filter and does NOT contain a refer attribute
it will be returned to the client as described in [RFC2251].
If the entry matches the filter contains a refer attribute without
the 'nssr' option it will be returned as a referral as described here.
If a matching entry contains a refer attribute and the URI
contained in the refer attribute is NOT an LDAP URI [RFC2255],
the server should return the URI value contained in the refer
attribute of that entry in a SearchResultReference.
Hedberg Expires September 30, 2000 [Page 5]
Internet-Draft LDAP Knowledge references July 2000
If a matching entry contains a refer attribute in the LDAP
URI syntax, the server will return an SearchResultReference
containing the value(s) of the refer attribute minus any optional
trailing whitespace and labels that might be present.
The URL from the refer attribute must be modified before it is
returned by adding or substituting a "base" scope into the URL. If the
URL does not contain a scope specifier, the "base" scope specifier must
be added. If the URL does contain a scope specifier, the existing scope
specifier must be replaced by the "base" scope.
4.2.2 One-level
Any entries matching the filter and one level scope that
do NOT contain a refer attribute are returned to the client normally as
described in [RFC2251]. Any entries matching the filter and one level
scope that contains a refer attribute without the 'nssr' option must
be returned as referrals as described here.
If a matching entry contains a refer attribute and the URI
contained in the refer attribute is NOT an LDAP URI [RFC2255],
the server should return the URI value contained in the refer
attribute of that entry in a SearchResultReference.
If a matching entry contains a refer attribute in the LDAP
URI syntax, the server will return an SearchResultReference
containing the value(s) of the refer attribute minus any optional
trailing whitespace and labels that might be present.
The URL from the refer attribute must be modified before it is
returned by adding or substituting a "base" scope into the URL. If the
URL does not contain a scope specifier, the "base" scope specifier must
be added. If the URL does contain a scope specifier, the existing scope
specifier must be replaced by the "base" scope.
4.2.3 Subtree search evaluation
Any entries, held by the server, matching the filter and
subtree scope that do NOT contain a refer attribute or contains
a refer attribute with the 'nssr' option are
returned to the client normally as described in [RFC2251].
Any entries matching the subtree scope and containing a refer
attribute must be returned as referrals as described here.
If a matching entry contains a refer attribute and the URI
contained in that attribute is NOT an LDAP URI [RFC2255],
the server should return the URI value contained in the refer
attribute of that entry in a SearchResultReference.
Hedberg Expires September 30, 2000 [Page 6]
Internet-Draft LDAP Knowledge references July 2000
If a matching entry contains a refer attribute in the LDAP
URI syntax, the server will return an SearchResultReference
containing the value(s) of the refer attribute minus any
optional trailing whitespace and labels that might be present.
N.B. in subtree search evaluation a entry containing a
refer attribut with the 'nssr' option might appear twice in the
result, first as a entry and then as a reference. A client
following all references might therefore end up with a resultset
containing two representations of the same entry, one from the
server getting the original query and one from the server
that the 'nssr' reference points to.
5. The referral object class
The referral object class is defined as follows.
( 1.2.752.17.2.10
NAME 'referral'
SUP top
STRUCTURAL
MAY ( refer ) )
The referral object class is a subclass of top and may contain the
refer attribute. The referral object class should, in general,
be used in conjunction with the extensibleObject object class to support
the naming attributes used in the entry's distinguished name.
Servers must support the refer attributes through use of the
referral object class. Any named reference must be of the referral
object class and will likely also be of the extensibleObject object
class to support naming and use of other attributes.
6. The manageDsaIT control
A client MAY specify the following control when issuing a search, com-
pare, add, delete, modify, or modifyDN request.
The control type is 2.16.840.1.113730.3.4.2. The control SHOULD be
marked as critical. There is no value; the controlValue field is
absent.
This control causes entries with the knowledge reference attributes to be
treated as normal entries, allowing clients to read and modify these entries.
Hedberg Expires September 30, 2000 [Page 7]
Internet-Draft LDAP Knowledge references July 2000
7. Superior Reference
This document defines two types of knowledge references that point to
parts of the naming context that is above of beyone the part held by a server.
The 'sup' option when referring to a LDAP server that holds a
naming context that is closer to the root of the same naming context and
'other' when referring to a LDAP server that holds a naming
context that belongs to a different naming domain then the one the
server belongs to.
Thus if the server receives a request for an operation where the
target entry is a entry closer to the root than the naming
context held the server and if the server holds a 'refer;sup' attribute
in the DSE, then the server MUST return an LDAPResult with the result
code field set to referral, and the referral field set to contain the
value(s) of the 'refer;sub' attribute minus any optional trailing
whitespace and labels that might be present.
On the other hand if the server receives a request for an operation
where the target entry is a entry that belongs to a other naming domain
and if there is any 'refer;other' attributes in the DSE with a base entry
that belongs to the same naming domain as the target entry and is
closer to the root then the target entry, then the server SHOULD return
an LDAPResult with the result code field set to referral, and the referral
field set to contain the value(s) of the 'refer;other' attribute minus
any optional trailing hitespace and labels that might be present.
8. Security Considerations
This document defines mechanisms that can be used to "glue" LDAP (and
other) servers together. The information used to specify this glue
information should be protected from unauthorized modification. If the
server topology information itself is not public information, the
information should be protected from unauthorized access as well.
9. References
[RFC1738]
Berners-Lee, T., Masinter, L., and McCahill, M., "Uniform Resource
Locators (URL)", RFC 1738, CERN, Xerox Corporation, University of
Minnesota, December 1994,
[RFC2079]
M. Smith, "Definition of an X.500 Attribute Type and an Object Class
to Hold Uniform Resource Identifiers (URIs)", RFC 2079, January
1997.
Hedberg Expires September 30, 2000 [Page 8]
Internet-Draft LDAP Knowledge references July 2000
[RFC2119]
S. Bradner, "Key Words for use in RFCs to Indicate Requirement Lev-
els", RFC 2119, March 1997. (Format: TXT=4723 bytes) (Also BCP0014)
(Status: BEST CURRENT PRACTICE)
[RFC2251]
M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access Protocol
(v3)", RFC 2251, December 1997. 1997.
[RFC2255]
T. Howes, M. Smith, "The LDAP URL Format", RFC 2255, December, 1997.
(Format: TXT=20685 bytes) (Status: PROPOSED STANDARD)
[X500]
ITU-T Rec. X.501, "The Directory: Models", 1993.
[X521]
ITU-T Rec. X.521, "---------------------", 1993.
12. Acknowledgements
This draft is heavily based on the previous drafts on knowledge
references in LDAP written by Christopher Lukas, Tim Howes,
Michael Roszkowski, Mark C. Smith, Mark Wahl and David Chadwick.
Peter Valkenburg and Henny Bekker has also made valueable
contributions.
13. Authors Address
Roland Hedberg
Catalogix
Dalsveien 53
0775 Oslo
Norway
EMail: Roland@catalogix.se
Hedberg Expires September 30, 2000 [Page 9]
Internet-Draft LDAP Knowledge references July 2000
Appendix A
Example of usage.
Information stored in a server.
dn:
objectclass: referral
refer;me: ldap://hostCAT/dc=cat,dc=se
refer;sup: ldap://hostSE/dc=se
refer;cross: ldap://hostNO/dc=no
refer;cross: ldap://hostNL/c=nl
dn: dc=cat,dc=se
objectclass: domain
dc: cat
dn: dc=one,dc=cat,dc=se
objectclass: extendedObject
objectclass: referral
refer;nssr: ldap://hostCAT1/dc=one,dc=cat,dc=se
ou: one
l: umea
dc: dc=two,dc=cat,dc=se
objectclass: referral
objectclass: extendedObject
refer;sub: ldap://hostCAT2/dc=two,dc=cat,dc=se
dn: dc=three,dc=cat,dc=se
objectclass: referral
objectclass: extendedObject
refer;cross: ldap://hostCAT3/dc=cat,dc=nl
dc: dc=four,dc=cat,dc=se
objectclass: domain
objectclass: extendedObject
ou: four
l: umea
Hedberg Expires September 30, 2000 [Page 10]
Internet-Draft LDAP Knowledge references July 2000
==========================================
A number of descriptive cases
==========================================
case 1: One-level search, target object on the server
search
baseobject: dc=cat,dc=se
scope: onelevel
filter: (objectclass=*)
attributes: ou
returns
searchResultEntry {
dn: dc=one,dc=cat,dc=se
ou: one
}
searchResultReference {
ldapurl: ldap://hostCAT2/dc=two,dc=cat,dc=se
}
searchResultReference {
ldapurl: ldap://hostCAT3/dc=cat,dc=nl
}
searchResultEntry {
dn: dc=four,dc=cat,dc=se
ou: four
}
searchResultDone {
resultCode: success
}
case 2: Subtree search, target object on the server
search
baseobject: dc=cat,dc=se
scope: subtree
filter: (objectclass=*)
attributes: ou
returns
searchResultEntry {
dn: dc=one,dc=cat,dc=se
ou: one
}
searchResultReference {
ldapurl: ldap://hostCAT1/dc=one,dc=cat,dc=se
}
searchResultReference {
ldapurl: ldap://hostCAT2/dc=two,dc=cat,dc=se
}
Hedberg Expires September 30, 2000 [Page 11]
Internet-Draft LDAP Knowledge references July 2000
searchResultReference {
ldapurl: ldap://hostCAT3/dc=cat,dc=nl
}
searchResultEntry {
dn: dc=four,dc=cat,dc=se
ou: four
}
searchResultDone {
resultCode: success
}
case 3: base search, target entry contains a 'refer;nssr' attribute
search
baseobject: dc=one,dc=cat,dc=se
scope: base
filter: (objectclass=*)
attributes: ou
returns
searchResultEntry {
dn: dc=one,dc=cat,dc=se
ou: four
}
searchResultDone {
resultCode: success
}
case 4: base search, target entry contains a 'refer;sub' attribute
search
baseobject: dc=two,dc=cat,dc=se
scope: base
filter: (objectclass=*)
attributes: ou
returns
searchResultDone {
resultCode: referral
matchedDN: dc=two,dc=cat,dc=se
referral: ldap://hostCAT2/dc=two,dc=cat,dc=se
}
Hedberg Expires September 30, 2000 [Page 12]
Internet-Draft LDAP Knowledge references July 2000
case 5: one-level search, target entry contains a 'refer;nssr' attribute
search
baseobject: dc=one,dc=cat,dc=se
scope: onelevel
filter: (objectclass=*)
attributes: ou
searchResultDone {
resultCode: referral
matchedDN: dc=one,dc=cat,dc=se
referral: ldap://hostCAT1/dc=one,dc=cat,dc=nu
}
case 6: Search on area above the baseobject of the server
search
baseobject: dc=pi,dc=se
scope: subtree
filter: (objectclass=*)
attributes: ou
returns
searchResultDone {
resultCode: referral
matchedDN: dc=se
referral: ldap://hostSE/dc=se
}
case 7: Search on area beyond, but not below the baseobject
of the server
search
baseobject: o=surfnet,c=nl
scope: base
filter: (objectclass=*)
returns
searchResultDone {
resultCode: referral
matchedDN: c=nl
referral: ldap://hostNL/c=NL
}
Hedberg Expires September 30, 2000 [Page 13]
