7 INTERNET-DRAFT Editor: Kurt D. Zeilenga
8 Intended Category: Standard Track OpenLDAP Foundation
9 Expires: 20 January 2002 20 July 2001
12 Named Subordinate References in LDAP Directories
13 <draft-zeilenga-ldap-namedref-04.txt>
18 This document is an Internet-Draft and is in full conformance with all
19 provisions of Section 10 of RFC2026.
21 This document is intended to be, after appropriate review and
22 revision, submitted to the RFC Editor as a Standard Track document.
23 Distribution of this memo is unlimited. Technical discussion of this
24 document will take place on the IETF LDAP Extension Working Group
25 mailing list <ietf-ldapext@netscape.com>. Please send editorial
26 comments directly to the author <Kurt@OpenLDAP.org>.
28 Internet-Drafts are working documents of the Internet Engineering Task
29 Force (IETF), its areas, and its working groups. Note that other
30 groups may also distribute working documents as Internet-Drafts.
31 Internet-Drafts are draft documents valid for a maximum of six months
32 and may be updated, replaced, or obsoleted by other documents at any
33 time. It is inappropriate to use Internet-Drafts as reference
34 material or to cite them other than as ``work in progress.''
36 The list of current Internet-Drafts can be accessed at
37 <http://www.ietf.org/ietf/1id-abstracts.txt>. The list of
38 Internet-Draft Shadow Directories can be accessed at
39 <http://www.ietf.org/shadow.html>.
41 Copyright 2001, The Internet Society. All Rights Reserved.
43 Please see the Copyright section near the end of this document for
49 This document details schema and protocol elements for representing
50 and manipulating named subordinate references in LDAP [RFC2251]
51 directories. A referral object is used to hold subordinate reference
52 information in the directory. These referral objects hold one or more
53 URIs [RFC2396] contained in values of the ref attribute type and are
54 used to generate protocol referrals and continuations. A control,
58 Zeilenga LDAP NamedRef [Page 1]
60 INTERNET-DRAFT draft-zeilenga-ldap-namedref-04 20 July 2001
63 ManageDsaIT, is defined to allow manipulation of referral objects as
67 1. Background and Intended Usage
69 The broadening of interest in LDAP directories beyond their use as
70 front ends to X.500 [X.500] directories has created a need to
71 represent knowledge information in a more general way. Knowledge
72 information is information about one or more servers maintained in
73 another server, used to link servers and services together.
75 This document defines a specific method of representing subordinate
76 knowledge references in LDAP directories. Other forms of knowledge
77 information are not detailed by this document. These forms may be
78 described in subsequent documents.
80 This document details subordinate referral processing requirements for
81 servers. This document does not describe protocol syntax and
82 semantics. This is detailed in RFC 2251 [RFC2251].
84 This document does not detail use of subordinate knowledge references
85 to support replicated environments nor distributed operations (e.g.,
86 chaining of operations from one server to other servers).
88 The key words "SHALL", "SHALL NOT", "MUST", "MUST NOT", "SHOULD",
89 "SHOULD NOT", "MAY" and "MAY NOT" used in this document are to be
90 interpreted as described in BCP 14 [RFC2119].
95 The schema definitions are defined in terms of RFC 2252 [RFC2252].
98 2.1. The referral Object Class
100 A referral object is a directory entry whose structural object class
101 is (or is derived from) the referral object class.
103 ( 2.16.840.1.113730.3.2.6
105 DESC 'named subordinate reference object'
109 The referral object class is a structural object class used to
110 represent a subordinate reference in the directory. The referral
114 Zeilenga LDAP NamedRef [Page 2]
116 INTERNET-DRAFT draft-zeilenga-ldap-namedref-04 20 July 2001
119 object class SHOULD be used in conjunction with the extensibleObject
120 object class to support the naming attributes used in the entry's
121 Distinguished Name (DN) [RFC2253]. Referral objects are directory
122 entries whose structural object class is (or is derived from)
125 Referral objects MUST only be instantiated at DSEs immediately
126 subordinate to leaf object entries within a naming context held by the
127 DSA. Referral objects correspond to X.500 subordinate knowledge
130 In the presence of a ManageDsaIT control, referral objects are treated
131 as normal entries as described in section 3. Note that the ref
132 attribute is operational and will only returned in a search entry
133 response when requested.
135 In the absence of a ManageDsaIT control, the content of referral
136 objects are used to construct referrals and search references as
137 described in section 4 and, as such, the referral entries are not
138 themselves visible to clients.
141 2.2 The ref Attribute Type
143 ( 2.16.840.1.113730.3.1.34
145 DESC 'named reference - a labeledURI'
146 EQUALITY caseExactMatch
147 SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
148 USAGE distributedOperation )
150 The ref attribute type has directoryString syntax and is case
151 sensitive. The ref attribute is multi-valued. Values placed in the
152 attribute MUST conform to the specification given for the labeledURI
153 attribute [RFC2079]. The labeledURI specification defines a format
154 that is a URI, optionally followed by whitespace and a label. This
155 document does not make use of the label portion of the syntax. Future
156 documents MAY enable new functionality by imposing additional
157 structure on the label portion of the syntax as it appears in the ref
160 If the URI contained in a ref attribute value refers to a LDAP
161 [RFC2251] server, it MUST be in the form of a LDAP URL [RFC2255]. The
162 LDAP URL SHOULD NOT contain an explicit scope specifier, filter,
163 attribute description list, or any extensions. The LDAP URL SHOULD
164 contain a non-empty DN. The handling of LDAP URLs with absent or
165 empty DN parts or with explicit scope specifier is not defined by this
170 Zeilenga LDAP NamedRef [Page 3]
172 INTERNET-DRAFT draft-zeilenga-ldap-namedref-04 20 July 2001
175 Other URI schemes MAY be used so long as all operations returning
176 referrals based upon the value could be performed. This document does
177 not detail use of non-LDAP URIs. This is left to future
180 All values of a ref attribute MUST point to services which are equally
181 capable of handling operations referred to these services.
183 The referential integrity of the URI SHOULD NOT be validated by the
184 server holding or returning the URI (whether as part of the value of
185 the attribute or as part of a referral result or search reference
188 When returning a referral result or search continuation, the server
189 MUST NOT return the separator or label portions of the attribute
190 values as part of the reference. When the attribute contains multiple
191 values, the URI part of each value is used to construct the referral
192 result or search continuation.
194 The ref attribute values SHOULD NOT be used as a relative
195 name-component of an entry's DN [RFC2253].
197 This document uses the ref attribute in conjunction with the referral
198 object class to represent subordinate references. The ref attribute
199 may be used for other purposes as defined by other documents.
202 3. The ManageDsaIT Control
204 The client may provide the ManageDsaIT control with an operation to
205 indicate that the operation is intended to manage objects within the
206 DSA (server) Information Tree. The control causes Directory-specific
207 entries (DSEs), regardless of type, to be treated as normal entries
208 allowing clients to interrogate and update these entries using LDAP
209 operations. This control is analogous to the ManageDsaIT option
210 described in X.511 [X.511].
212 A client MAY specify the following control when issuing an add,
213 compare, delete, modify, modifyDN, search request or an extended
214 operation for which the control is defined.
216 The control type is 2.16.840.1.113730.3.4.2. The control criticality
217 may be TRUE or, if FALSE, absent. The control value is absent.
219 When the control is present in the request, the server SHALL NOT
220 generate a referral or continuation reference for any referral object
221 and instead treat the referral object as a normal entry. When not
222 present, referral objects SHALL be handled as described above.
226 Zeilenga LDAP NamedRef [Page 4]
228 INTERNET-DRAFT draft-zeilenga-ldap-namedref-04 20 July 2001
231 The control MAY cause other objects to be treated as normal entries as
232 defined by subsequent documents.
235 4. Named Subordinate References
237 A named subordinate reference is constructed by instantiating a
238 referral object in the referencing server with ref attribute values
239 which point to the corresponding subtree maintained in the referenced
240 server. In general, the name of the referral object is the same as
241 the referenced object and this referenced object is a context prefix
244 That is, if server A holds "DC=example,DC=net" and server B holds
245 "DC=sub,DC=example,DC=net", server A may contain a referral object
246 named "DC=sub,DC=example,DC=net" which contains a ref attribute with
247 value of "ldap://B/DC=sub,DC=example,DC=net".
249 dn: DC=sub,DC=example,DC=net
251 ref: ldap://B/DC=sub,DC=example,DC=net
252 objectClass: referral
253 objectClass: extensibleObject
255 While typically the DN of the referral object and the DN of the object
256 in the referenced server are the same, they need not be the same.
258 If the ref attribute has multiple values, all the DNs contained within
259 the LDAP URLs SHOULD be equivalent. Administrators SHOULD avoid
260 configuring naming loops using referrals.
262 Named references MUST be treated as normal entries if the request
263 includes the ManageDsaIT control as described in section 3.
268 The following sections contain specifications of how referral objects
269 should be used in different scenarios followed by examples that
270 illustrate that usage. The scenarios described consist of referral
271 operation when finding target of a non-search operation, when finding
272 the base of a search operation, and when generating search references.
273 Lastly, other operation processing considerations are presented.
275 It is to be noted that, in this document, a search operation is
276 conceptually divided into two distinct, sequential phases: (1) finding
277 the base object where the search is to begin, and (2) performing the
278 search itself. The first phase is similar to, but not the same as,
282 Zeilenga LDAP NamedRef [Page 5]
284 INTERNET-DRAFT draft-zeilenga-ldap-namedref-04 20 July 2001
287 finding the target of a non-search operation.
289 It should also be noted that the ref attribute may have multiple
290 values and, where these sections refer to a single ref attribute
291 value, multiple ref attribute values may be substituted and SHOULD be
292 processed and returned (in any order) as a group in a referral or
293 search reference in the same way as described for a single ref
296 Search references returned for a given request may be returned in any
300 5.1. Example Configuration
302 For example, suppose the contacted server (hosta) holds the entry
303 "O=MNN,C=WW" and the entry "CN=Manager,O=MNN,C=WW" and the following
306 dn: OU=People,O=MNN,C=WW
308 ref: ldap://hostb/OU=People,O=MNN,C=US
309 ref: ldap://hostc/OU=People,O=MNN,C=US
310 objectClass: referral
311 objectClass: extensibleObject
313 dn: OU=Roles,O=MNN,C=WW
315 ref: ldap://hostd/OU=Roles,O=MNN,C=WW
316 objectClass: referral
317 objectClass: extensibleObject
319 The first referral object provides the server with the knowledge that
320 subtree "OU=People,O=MNN,C=WW" is held by hostb and hostc (e.g., one
321 is the master and the other a shadow). The second referral object
322 provides the server with the knowledge that the subtree
323 "OU=Roles,O=MNN,C=WW" is held by hostd.
325 Also, in the context of this document, the "nearest naming context"
326 means the deepest context which the object is within. That is, if the
327 object is within multiple naming contexts, the nearest naming context
328 is the one which is subordinate to all other naming contexts the
332 5.2. Target object considerations
334 This section details referral handling for add, compare, delete,
338 Zeilenga LDAP NamedRef [Page 6]
340 INTERNET-DRAFT draft-zeilenga-ldap-namedref-04 20 July 2001
343 modify, and modify DN operations. If the client requests any of these
344 operations, there are four cases that the server must handle with
345 respect to the target object.
347 The DN part MUST be modified such that it refers to the appropriate
348 target in the referenced server (as detailed below). Even where the
349 DN to be returned is the same as the target DN, the DN part SHOULD NOT
352 In cases where the URI to be returned is a LDAP URL, the server SHOULD
353 trim any present scope, filter, or attribute list from the URI before
354 returning it. Critical extensions MUST NOT be trimmed or modified.
356 Case 1: The target object is not held by the server and is not within
357 or subordinate to any naming context nor subordinate to any
358 referral object held by the server.
360 The server SHOULD process the request normally as appropriate for
361 a non-existent base which is not within any naming context of the
362 server (generally return noSuchObject or a referral based upon
363 superior knowledge reference information). This document does not
364 detail management or processing of superior knowledge reference
367 Case 2: The target object is held by the server and is a referral
370 The server SHOULD return the URI value contained in the ref
371 attribute of the referral object.
373 Example: If the client issues a modify request for the target object
374 of "OU=People,O=MNN,c=WW", the server will return:
376 ModifyResponse (referral) {
377 ldap://hostb/OU=People,O=MNN,C=WW
378 ldap://hostc/OU=People,O=MNN,C=WW
382 Case 3: The target object is not held by the server, but the nearest
383 naming context contains no referral object which the target object
386 If the nearest naming context contains no referral object which
387 the target is subordinate to, the server SHOULD process the
388 request as appropriate for a nonexistent target (generally return
394 Zeilenga LDAP NamedRef [Page 7]
396 INTERNET-DRAFT draft-zeilenga-ldap-namedref-04 20 July 2001
399 Case 4: The target object is not held by the server, but the nearest
400 naming context contains a referral object which the target object
403 If a client requests an operation for which the target object is
404 not held by the server and the nearest naming context contains a
405 referral object which the target object is subordinate to, the
406 server SHOULD return a referral response constructed from the URI
407 portion of the ref value of the referral object.
409 Example: If the client issues an add request where the target object
410 has a DN of "CN=Manager,OU=Roles,O=MNN,C=WW", the server will
413 AddResponse (referral) {
414 ldap://hostd/CN=Manager,OU=Roles,O=MNN,C=WW"
417 Note that the DN part of the LDAP URL is modified such that it
418 refers to the appropriate entry in the referenced server.
421 5.3. Base Object Considerations
423 This section details referral handling for base object processing
424 within search operations. Like target object considerations for non-
425 search operations, there are the four cases.
427 In cases where the URI to be returned is a LDAP URL, the server MUST
428 provide an explicit scope specifier from the LDAP URL prior to
429 returning it. In addition, the DN part MUST be modified such that it
430 refers to the appropriate target in the referenced server (as detailed
433 If aliasing dereferencing was necessary in finding the referral
434 object, the DN part of the URI MUST be replaced with the base DN as
435 modified by the alias dereferencing such that the return URL refers to
436 the new target object per [RFC2251, 4.1.11].
438 Critical extensions MUST NOT be trimmed nor modified.
440 Case 1: The base object is not held by the server and is not within
441 nor subordinate to any naming context held by the server.
443 The server SHOULD process the request normally as appropriate for
444 a non-existent base which not within any naming context of the
445 server (generally return a superior referral or noSuchObject).
446 This document does not detail management or processing of superior
450 Zeilenga LDAP NamedRef [Page 8]
452 INTERNET-DRAFT draft-zeilenga-ldap-namedref-04 20 July 2001
455 knowledge references.
457 Case 2: The base object is held by the server and is a referral
460 The server SHOULD return the URI value contained in the ref
461 attribute of the referral object.
463 Example: If the client issues a subtree search in which the base
464 object is "OU=Roles,O=MNN,C=WW", the server will return
466 SearchResultDone (referral) {
467 ldap://hostd/OU=Roles,O=MNN,C=WW??sub
470 If the client were to issue a base or oneLevel search instead of
471 subtree, the returned LDAP URL would explicitly specify "base" or
472 "one", respectively, instead of "sub".
474 Case 3: The base object is not held by the server, but the nearest
475 naming context contains no referral object which the base object
478 If the nearest naming context contains no referral object which
479 the base is subordinate to, the request SHOULD be processed
480 normally as appropriate for a nonexistent base (generally return
483 Case 4: The base object is not held by the server, but the nearest
484 naming context contains a referral object which the base object is
487 If a client requests an operation for which the target object is
488 not held by the server and the nearest naming context contains a
489 referral object which the target object is subordinate to, the
490 server SHOULD return a referral response which is constructed from
491 the URI portion of the ref value of the referral object.
493 Example: If the client issues a base search request for
494 "CN=Manager,OU=Roles,O=MNN,C=WW", the server will return
496 SearchResultDone (referral) {
497 ldap://hostd/CN=Manager,OU=Roles,O=MNN,C=WW??base"
500 If the client were to issue a subtree or oneLevel search instead
501 of subtree, the returned LDAP URL would explicitly specify "sub"
502 or "one", respectively, instead of "base".
506 Zeilenga LDAP NamedRef [Page 9]
508 INTERNET-DRAFT draft-zeilenga-ldap-namedref-04 20 July 2001
511 Note that the DN part of the LDAP URL is modified such that it
512 refers to the appropriate entry in the referenced server.
515 5.4. Search Continuation Considerations
517 For search operations, once the base object has been found and
518 determined not to be a referral object, the search may progress. Any
519 entry matching the filter and scope of the search which is not a
520 referral object is returned to the client normally as described in
523 For each referral object within the requested scope, regardless of the
524 search filter, the server SHOULD return a SearchResultReference which
525 is constructed from the URI component of values of the ref attribute.
526 If the URI component is not a LDAP URL, it should be returned as is.
527 If the LDAP URL's DN part is absent or empty, the DN part must be
528 modified to contain the DN of the referral object. If the URI
529 component is a LDAP URL, the URI SHOULD be modified to add an explicit
534 If a client requests a subtree search of "O=MNN,C=WW", then in
535 addition to any entries within scope which match the filter, hosta
536 will also return two search references as the two referral objects
537 are within scope. One possible response might be:
539 SearchEntry for O=MNN,C=WW
540 SearchResultReference {
541 ldap://hostb/OU=People,O=MNN,C=WW??sub
542 ldap://hostc/OU=People,O=MNN,C=WW??sub
544 SearchEntry for CN=Manager,O=MNN,C=WW
545 SearchResultReference {
546 ldap://hostd/OU=Roles,O=MNN,C=WW??sub
548 SearchResultDone (success)
552 If a client requests a one level search of "O=MNN,C=WW" then, in
553 addition to any entries one level below the "O=MNN,C=WW" entry
554 matching the filter, the server will also return two search
555 references as the two referral objects are within scope. One
556 possible sequence is shown:
558 SearchResultReference {
562 Zeilenga LDAP NamedRef [Page 10]
564 INTERNET-DRAFT draft-zeilenga-ldap-namedref-04 20 July 2001
567 ldap://hostb/OU=People,O=MNN,C=WW??base
568 ldap://hostc/OU=People,O=MNN,C=WW??base
570 SearchEntry for CN=Manager,O=MNN,C=WW
571 SearchResultReference {
572 ldap://hostd/OU=Roles,O=MNN,C=WW??base
574 SearchResultDone (success)
576 Note: Unlike the examples in Section 4.5.3.1 of RFC 2251, the LDAP
577 URLs returned with the SearchResultReference messages contain,
578 as required by this specification, an explicit scope specifier.
581 5.6. Other Considerations
583 This section details processing considerations for other operations.
588 Servers SHOULD NOT return referral result code if the bind name (or
589 other identity in the DN form) is (or is subordinate to) a referral
590 object but MAY use the knowledge information to process the bind
591 request (such as in support a future distributed operation
592 specification). Where the server makes no use of the knowledge
593 information, the server processes the request normally as appropriate
594 for a non-existent authentication or authorization identity (e.g.
595 return invalidCredentials).
600 If the newSuperior is a referral object or is subordinate to a
601 referral object, the server SHOULD return affectsMultipleDSAs. If the
602 newRDN already exists but is a referral object, the server SHOULD
603 return affectsMultipleDSAs instead of entryAlreadyExists.
606 6. Security Considerations
608 This document defines mechanisms that can be used to tie LDAP (and
609 other) servers together. The information used to tie services
610 together should be protected from unauthorized modification. If the
611 server topology information is not public information, it should be
612 protected from unauthorized disclosure as well.
618 Zeilenga LDAP NamedRef [Page 11]
620 INTERNET-DRAFT draft-zeilenga-ldap-namedref-04 20 July 2001
625 This document borrows heavily from previous work by IETF LDAPext
626 Working Group. In particular, this document is based upon "Named
627 Referral in LDAP Directories" (an expired Internet Draft) by
628 Christopher Lukas, Tim Howes, Michael Roszkowski, Mark C. Smith, and
641 [RFC2079] M. Smith, "Definition of an X.500 Attribute Type and an
642 Object Class to Hold Uniform Resource Identifiers (URIs)",
643 RFC 2079, January 1997.
645 [RFC2119] S. Bradner, "Key Words for use in RFCs to Indicate
646 Requirement Levels", RFC 2119 (Also BCP 14), March 1997.
648 [RFC2251] M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access
649 Protocol (v3)", RFC 2251, December 1997.
651 [RFC2252] M. Wahl, A. Coulbeck, T. Howes, S. Kille, "Lightweight
652 Directory Access Protocol (v3): Attribute Syntax
653 Definitions", RFC 2252, December 1997.
655 [RFC2253] M. Wahl, S. Kille, T. Howes, "Lightweight Directory Access
656 Protocol (v3): UTF-8 String Representation of Distinguished
657 Names", RFC 2253, December 1997.
659 [RFC2255] T. Howes, M. Smith, "The LDAP URL Format", RFC 2255,
662 [RFC2396] Berners-Lee, T., R. Fielding, L. Masinter, "Uniform Resource
663 Identifiers (URI): Generic Syntax", RFC 2396, August 1998.
665 [X.500] ITU-T Rec. X.500, "The Directory: Overview of Concepts,
666 Models, and Services", 1993.
668 [X.501] ITU-T Rec. X.501, "The Directory: Models", 1993.
670 [X.511] ITU-T Rec. X.511, "The Directory: Abstract Service
674 Zeilenga LDAP NamedRef [Page 12]
676 INTERNET-DRAFT draft-zeilenga-ldap-namedref-04 20 July 2001
682 Copyright 2001, The Internet Society. All Rights Reserved.
684 This document and translations of it may be copied and furnished to
685 others, and derivative works that comment on or otherwise explain it
686 or assist in its implementation may be prepared, copied, published and
687 distributed, in whole or in part, without restriction of any kind,
688 provided that the above copyright notice and this paragraph are
689 included on all such copies and derivative works. However, this
690 document itself may not be modified in any way, such as by removing
691 the copyright notice or references to the Internet Society or other
692 Internet organizations, except as needed for the purpose of
693 developing Internet standards in which case the procedures for
694 copyrights defined in the Internet Standards process must be followed,
695 or as required to translate it into languages other than English.
697 The limited permissions granted above are perpetual and will not be
698 revoked by the Internet Society or its successors or assigns.
700 This document and the information contained herein is provided on an
701 "AS IS" basis and THE AUTHORS, THE INTERNET SOCIETY, AND THE INTERNET
702 ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED,
703 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
704 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
705 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
730 Zeilenga LDAP NamedRef [Page 13]