1 IETF LDAPEXT Working Group Roland Hedberg
2 Internet-Draft Catalogix
3 Expires: January 12, 2000 July 12, 2000
9 Referrals in LDAP Directories
10 <draft-ietf-ldapext-refer-00.txt>
17 This document is an Internet-Draft and is in full conformance with
18 all provisions of Section 10 of RFC2026.
20 Internet-Drafts are working documents of the Internet Engineering
21 Task Force (IETF), its areas, and its working groups. Note that
22 other groups may also distribute working documents as
25 Internet-Drafts are draft documents valid for a maximum of six
26 months and may be updated, replaced, or obsoleted by other documents
27 at any time. It is inappropriate to use Internet-Drafts as reference
28 material or to cite them other than as "work in progress."
31 The list of current Internet-Drafts can be accessed at
32 http://www.ietf.org/ietf/1id-abstracts.txt
34 The list of Internet-Draft Shadow Directories can be accessed at
35 http://www.ietf.org/shadow.html.
38 This Internet-Draft will expire on January 12, 2000.
42 Copyright (C) The Internet Society (2000). All Rights Reserved.
55 Hedberg Expires September 30, 2000 [Page 1]
57 Internet-Draft LDAP Knowledge references July 2000
61 This document defines two reference attributes and associated "referral"
62 object class for representing generic knowledge information in LDAP
63 directories [RFC2251].
64 The attribute uses URIs [RFC1738] to represent knowledge,
65 enabling LDAP and non-LDAP services alike to be referenced.
66 The object class can be used to construct entries in an LDAP directory
67 containing references to other directories or services. This document
68 also defines procedures directory servers should follow when supporting
69 these schema elements and when responding to requests for which the
70 directory server does not contain the requested object but may contain
71 some knowledge of the location of the requested object.
74 1. Background and intended usage
76 The broadening of interest in LDAP directories beyond their use as front
77 ends to X.500 directories has created a need to represent knowledge
78 information in a more general way. Knowledge information is information
79 about one or more servers maintained in another server, used to link
80 servers and services together.
82 This document is based on the following basic assumptions:
84 - several naming domains
85 The usage of LDAP as a access protocol to other than X.500 servers has
86 created islands of directory service systems containing one or more
87 LDAP servers. Each of these islands are free to pick their own naming
88 domain. And that they also do; some use the old country,organization,
89 organizationalUnit naming scheme[X.521], some use the newer domain name
90 based naming scheme but these two are in no way the only ones in use. The
91 existence of several naming domains are in itself no real problem as
92 long as they produce unique names for the objects in the directory.
93 Still naming schemes like the domain name based one, might easily create
94 non-continues naming structures because some toplevel domain names
95 might no find organizations that are interested and/or willing
96 to manage them. Therefor tree transversal might not longer be possible
97 except in parts of the whole tree.
99 - authoritive structure vs directory structure
100 In some instances even if a part of the tree is delegated to one
101 organization, the organization doing the delegation might want to
102 remain as the authority for the baseobject of the delegated tree.
104 - support for onelevel searches
105 At points in the tree where the responsibility for all or almost all
106 of the children of a object is delegated to different organizations
107 and resides in different directory servers a one-level search is not
108 very efficient if not supported by special facilities in the directory
111 Hedberg Expires September 30, 2000 [Page 2]
113 Internet-Draft LDAP Knowledge references July 2000
115 -- directory server discovery
116 LDAP servers that do not use dc nameing or are not registered with
117 SRV records in the DNS are very hard to find.
119 This document defines a general method of representing knowledge
120 information in LDAP directories, based on URIs.
121 Two types of knowledge reference are defined: refer and subRefer.
123 The key words "MUST", "SHOULD", and "MAY" used in this document are to
124 be interpreted as described in [RFC2119].
126 2. Knowledge references
128 2.1 The refer attribute
133 EQUALITY caseExactIA5Match
134 SYNTAX 1.3.6.1.4.1.1466.115.121.1.26
135 USAGE distributedOperation )
137 The refer attribute type has IA5 syntax and is case sensitive.
138 It is multivalued. Values placed in the attribute MUST conform to the
139 specification given for the labeledURI attribute as defined in [RFC2079].
141 The labeledURI specification defines a format that is a URI,
142 optionally followed by whitespace and a label. This document does not
143 make use of the label portion of the syntax. Future documents MAY enable
144 new functionality by imposing additional structure on the label portion
145 of the syntax as it appears in a refer attribute.
146 If the URI contained in a refer attribute refers to an LDAP
147 server, it must be in the LDAP URI format described in [RFC2255].
149 When returning a referral result, the server must not return the label
150 portion of the labeledURI as part of the referral. Only the URI portion
151 of the refer attributes should be returned.
153 The refer attribute can be further specified by the use of options as
154 defined in section 4.1.5 of [RFC2251]. This document defines five
155 options and their use. Future documents might defined other options.
157 The options defined are:
158 "me", "sup", "cross", "nssr" and "sub" .
160 'refer;me' is used to hold the reference of this server, and is always
163 'refer;sup' is used to hold the reference of a server superior to this
164 one in this global LDAP naming domain e.g. a server holding the dc=com,
165 dc=se, or the c=se node. The 'refer;sup' is always held in the root DSE.
167 Hedberg Expires September 30, 2000 [Page 3]
169 Internet-Draft LDAP Knowledge references July 2000
171 'refer;cross' indicates that this is a cross reference pointing to another
172 naming context within or outside this global LDAP naming domain.
174 'refer;sub' indicates that this is a subordinate reference pointing to
175 a subordinate naming context in this global LDAP naming domain.
177 'refer;nssr' indicates that this is a non-specific subordinate reference
178 pointing to a subordinate naming context in this global LDAP naming domain.
181 3. Use of the knowledge attribute
183 Except when the manageDsaIT control (documented in section 6 of this
184 document) is present in the operation request, the refer attribute is not
185 visible to clients, except as its value is returned in referrals or con-
186 tinuation references.
188 If the manageDsaIT control is not set, and the entry named in a request
189 contains the refer attribute, and the entry is not the root DSE, the
190 server returns an LDAPResult with the resultCode field set to "referral"
191 and the referral field set to contain the value(s) of the refer attribute
192 minus any optional trailing whitespace and labels that might be present.
194 If the manageDsaIT control is not set, and an entry containing the ref
195 attribute is in the scope of a one level or subtree search request, the
196 server returns a SearchResultReference for each such entry containing
197 the value(s) of the entry's refer attribute.
199 When the manageDsaIT control is present in a request, the server will
200 treat an entry containing the refer attribute as an ordinary entry, and
201 the refer attribute as an ordinary attribute, and the server will not
202 return referrals or continuation references corresponding to refer
206 4 Behaviour specification
208 4.1 Name resolution for any operation
210 Clients SHOULD perform at least simple "depth-of-referral count" loop
211 detection by incrementing a counter each time a new set of referrals is
212 received. (The maximum value for this count SHOULD be twice the number
213 of RDNs in the target object less one, to allow for ascending and
214 descending the DIT.) Clients MAY perform more sophisticated loop
215 detection, for example not chasing the same referral twice.
217 Case 1: The target entry is not held by the server and is
218 superior to some entry held by the server.
220 If the server DSE contains a "refer;sup" attribute then
221 the server will return an LDAPResult with the result code field set
223 Hedberg Expires September 30, 2000 [Page 4]
225 Internet-Draft LDAP Knowledge references July 2000
227 to referral, and the referral field set to contain the value(s) of
228 the "refer;sup" attribute minus any optional trailing whitespace and
229 labels that might be present.
231 Case 2: The target entry is not held by the server and is
232 subordinate to some entry, held by the server, that contains a
235 The server will return an LDAPResult with the result code field set
236 to referral, and the referral field set to contain the value(s) of
237 the refer attribute minus any optional trailing whitespace and labels
238 that might be present.
240 Case 3: The target entry is held by the server and contains a
241 refer attribute without the 'nssr' option.
243 The server will return an LDAPResult with the result code field set
244 to referral, and the referral field set to contain the value(s) of
245 the refer attribute minus any optional trailing whitespace and labels
246 that might be present.
248 Case 4: The target entry is not held by the server, and is not
249 subordinate or superior to any object held by the server.
251 If the server contains a "refer;cross" attribute
252 in the root DSE with a baseobject that is either the same or
253 superior to the target entry then
254 the server will return an LDAPResult with the result code field set
255 to referral, and the referral field set to contain the value(s) of
256 these refer attributes minus any optional trailing whitespace and labels
257 that might be present.
260 4.2 Search evaluation
262 For search operations, once the base object has been found and
263 determined NOT to contain a refer attribute without the 'nssr'
264 option, the search may progress.
268 If the entry matches the filter and does NOT contain a refer attribute
269 it will be returned to the client as described in [RFC2251].
270 If the entry matches the filter contains a refer attribute without
271 the 'nssr' option it will be returned as a referral as described here.
273 If a matching entry contains a refer attribute and the URI
274 contained in the refer attribute is NOT an LDAP URI [RFC2255],
275 the server should return the URI value contained in the refer
276 attribute of that entry in a SearchResultReference.
279 Hedberg Expires September 30, 2000 [Page 5]
281 Internet-Draft LDAP Knowledge references July 2000
284 If a matching entry contains a refer attribute in the LDAP
285 URI syntax, the server will return an SearchResultReference
286 containing the value(s) of the refer attribute minus any optional
287 trailing whitespace and labels that might be present.
288 The URL from the refer attribute must be modified before it is
289 returned by adding or substituting a "base" scope into the URL. If the
290 URL does not contain a scope specifier, the "base" scope specifier must
291 be added. If the URL does contain a scope specifier, the existing scope
292 specifier must be replaced by the "base" scope.
296 Any entries matching the filter and one level scope that
297 do NOT contain a refer attribute are returned to the client normally as
298 described in [RFC2251]. Any entries matching the filter and one level
299 scope that contains a refer attribute without the 'nssr' option must
300 be returned as referrals as described here.
302 If a matching entry contains a refer attribute and the URI
303 contained in the refer attribute is NOT an LDAP URI [RFC2255],
304 the server should return the URI value contained in the refer
305 attribute of that entry in a SearchResultReference.
307 If a matching entry contains a refer attribute in the LDAP
308 URI syntax, the server will return an SearchResultReference
309 containing the value(s) of the refer attribute minus any optional
310 trailing whitespace and labels that might be present.
311 The URL from the refer attribute must be modified before it is
312 returned by adding or substituting a "base" scope into the URL. If the
313 URL does not contain a scope specifier, the "base" scope specifier must
314 be added. If the URL does contain a scope specifier, the existing scope
315 specifier must be replaced by the "base" scope.
317 4.2.3 Subtree search evaluation
319 Any entries, held by the server, matching the filter and
320 subtree scope that do NOT contain a refer attribute or contains
321 a refer attribute with the 'nssr' option are
322 returned to the client normally as described in [RFC2251].
323 Any entries matching the subtree scope and containing a refer
324 attribute must be returned as referrals as described here.
326 If a matching entry contains a refer attribute and the URI
327 contained in that attribute is NOT an LDAP URI [RFC2255],
328 the server should return the URI value contained in the refer
329 attribute of that entry in a SearchResultReference.
335 Hedberg Expires September 30, 2000 [Page 6]
337 Internet-Draft LDAP Knowledge references July 2000
339 If a matching entry contains a refer attribute in the LDAP
340 URI syntax, the server will return an SearchResultReference
341 containing the value(s) of the refer attribute minus any
342 optional trailing whitespace and labels that might be present.
344 N.B. in subtree search evaluation a entry containing a
345 refer attribut with the 'nssr' option might appear twice in the
346 result, first as a entry and then as a reference. A client
347 following all references might therefore end up with a resultset
348 containing two representations of the same entry, one from the
349 server getting the original query and one from the server
350 that the 'nssr' reference points to.
353 5. The referral object class
355 The referral object class is defined as follows.
363 The referral object class is a subclass of top and may contain the
364 refer attribute. The referral object class should, in general,
365 be used in conjunction with the extensibleObject object class to support
366 the naming attributes used in the entry's distinguished name.
368 Servers must support the refer attributes through use of the
369 referral object class. Any named reference must be of the referral
370 object class and will likely also be of the extensibleObject object
371 class to support naming and use of other attributes.
374 6. The manageDsaIT control
376 A client MAY specify the following control when issuing a search, com-
377 pare, add, delete, modify, or modifyDN request.
379 The control type is 2.16.840.1.113730.3.4.2. The control SHOULD be
380 marked as critical. There is no value; the controlValue field is
383 This control causes entries with the knowledge reference attributes to be
384 treated as normal entries, allowing clients to read and modify these entries.
391 Hedberg Expires September 30, 2000 [Page 7]
393 Internet-Draft LDAP Knowledge references July 2000
396 7. Superior Reference
398 This document defines two types of knowledge references that point to
399 parts of the naming context that is above of beyone the part held by a server.
400 The 'sup' option when referring to a LDAP server that holds a
401 naming context that is closer to the root of the same naming context and
402 'other' when referring to a LDAP server that holds a naming
403 context that belongs to a different naming domain then the one the
406 Thus if the server receives a request for an operation where the
407 target entry is a entry closer to the root than the naming
408 context held the server and if the server holds a 'refer;sup' attribute
409 in the DSE, then the server MUST return an LDAPResult with the result
410 code field set to referral, and the referral field set to contain the
411 value(s) of the 'refer;sub' attribute minus any optional trailing
412 whitespace and labels that might be present.
414 On the other hand if the server receives a request for an operation
415 where the target entry is a entry that belongs to a other naming domain
416 and if there is any 'refer;other' attributes in the DSE with a base entry
417 that belongs to the same naming domain as the target entry and is
418 closer to the root then the target entry, then the server SHOULD return
419 an LDAPResult with the result code field set to referral, and the referral
420 field set to contain the value(s) of the 'refer;other' attribute minus
421 any optional trailing hitespace and labels that might be present.
424 8. Security Considerations
426 This document defines mechanisms that can be used to "glue" LDAP (and
427 other) servers together. The information used to specify this glue
428 information should be protected from unauthorized modification. If the
429 server topology information itself is not public information, the
430 information should be protected from unauthorized access as well.
436 Berners-Lee, T., Masinter, L., and McCahill, M., "Uniform Resource
437 Locators (URL)", RFC 1738, CERN, Xerox Corporation, University of
438 Minnesota, December 1994,
441 M. Smith, "Definition of an X.500 Attribute Type and an Object Class
442 to Hold Uniform Resource Identifiers (URIs)", RFC 2079, January
447 Hedberg Expires September 30, 2000 [Page 8]
449 Internet-Draft LDAP Knowledge references July 2000
453 S. Bradner, "Key Words for use in RFCs to Indicate Requirement Lev-
454 els", RFC 2119, March 1997. (Format: TXT=4723 bytes) (Also BCP0014)
455 (Status: BEST CURRENT PRACTICE)
458 M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access Protocol
459 (v3)", RFC 2251, December 1997. 1997.
462 T. Howes, M. Smith, "The LDAP URL Format", RFC 2255, December, 1997.
463 (Format: TXT=20685 bytes) (Status: PROPOSED STANDARD)
466 ITU-T Rec. X.501, "The Directory: Models", 1993.
469 ITU-T Rec. X.521, "---------------------", 1993.
474 This draft is heavily based on the previous drafts on knowledge
475 references in LDAP written by Christopher Lukas, Tim Howes,
476 Michael Roszkowski, Mark C. Smith, Mark Wahl and David Chadwick.
477 Peter Valkenburg and Henny Bekker has also made valueable
488 EMail: Roland@catalogix.se
503 Hedberg Expires September 30, 2000 [Page 9]
505 Internet-Draft LDAP Knowledge references July 2000
511 Information stored in a server.
514 objectclass: referral
515 refer;me: ldap://hostCAT/dc=cat,dc=se
516 refer;sup: ldap://hostSE/dc=se
517 refer;cross: ldap://hostNO/dc=no
518 refer;cross: ldap://hostNL/c=nl
524 dn: dc=one,dc=cat,dc=se
525 objectclass: extendedObject
526 objectclass: referral
527 refer;nssr: ldap://hostCAT1/dc=one,dc=cat,dc=se
531 dc: dc=two,dc=cat,dc=se
532 objectclass: referral
533 objectclass: extendedObject
534 refer;sub: ldap://hostCAT2/dc=two,dc=cat,dc=se
536 dn: dc=three,dc=cat,dc=se
537 objectclass: referral
538 objectclass: extendedObject
539 refer;cross: ldap://hostCAT3/dc=cat,dc=nl
541 dc: dc=four,dc=cat,dc=se
543 objectclass: extendedObject
559 Hedberg Expires September 30, 2000 [Page 10]
561 Internet-Draft LDAP Knowledge references July 2000
564 ==========================================
565 A number of descriptive cases
566 ==========================================
568 case 1: One-level search, target object on the server
570 baseobject: dc=cat,dc=se
572 filter: (objectclass=*)
577 dn: dc=one,dc=cat,dc=se
580 searchResultReference {
581 ldapurl: ldap://hostCAT2/dc=two,dc=cat,dc=se
583 searchResultReference {
584 ldapurl: ldap://hostCAT3/dc=cat,dc=nl
587 dn: dc=four,dc=cat,dc=se
594 case 2: Subtree search, target object on the server
596 baseobject: dc=cat,dc=se
598 filter: (objectclass=*)
603 dn: dc=one,dc=cat,dc=se
606 searchResultReference {
607 ldapurl: ldap://hostCAT1/dc=one,dc=cat,dc=se
609 searchResultReference {
610 ldapurl: ldap://hostCAT2/dc=two,dc=cat,dc=se
615 Hedberg Expires September 30, 2000 [Page 11]
617 Internet-Draft LDAP Knowledge references July 2000
620 searchResultReference {
621 ldapurl: ldap://hostCAT3/dc=cat,dc=nl
624 dn: dc=four,dc=cat,dc=se
631 case 3: base search, target entry contains a 'refer;nssr' attribute
633 baseobject: dc=one,dc=cat,dc=se
635 filter: (objectclass=*)
640 dn: dc=one,dc=cat,dc=se
647 case 4: base search, target entry contains a 'refer;sub' attribute
649 baseobject: dc=two,dc=cat,dc=se
651 filter: (objectclass=*)
657 matchedDN: dc=two,dc=cat,dc=se
658 referral: ldap://hostCAT2/dc=two,dc=cat,dc=se
671 Hedberg Expires September 30, 2000 [Page 12]
673 Internet-Draft LDAP Knowledge references July 2000
676 case 5: one-level search, target entry contains a 'refer;nssr' attribute
678 baseobject: dc=one,dc=cat,dc=se
680 filter: (objectclass=*)
685 matchedDN: dc=one,dc=cat,dc=se
686 referral: ldap://hostCAT1/dc=one,dc=cat,dc=nu
689 case 6: Search on area above the baseobject of the server
691 baseobject: dc=pi,dc=se
693 filter: (objectclass=*)
700 referral: ldap://hostSE/dc=se
705 case 7: Search on area beyond, but not below the baseobject
708 baseobject: o=surfnet,c=nl
710 filter: (objectclass=*)
716 referral: ldap://hostNL/c=NL
727 Hedberg Expires September 30, 2000 [Page 13]