7 INTERNET-DRAFT Editor: Kurt D. Zeilenga
8 Intended Category: Standard Track OpenLDAP Foundation
9 Expires: 20 May 2002 20 November 2001
13 Named Subordinate References in LDAP Directories
14 <draft-zeilenga-ldap-namedref-05.txt>
19 This document is an Internet-Draft and is in full conformance with all
20 provisions of Section 10 of RFC2026.
22 This document is intended to be, after appropriate review and
23 revision, submitted to the RFC Editor as a Standard Track document.
24 Distribution of this memo is unlimited. Technical discussion of this
25 document will take place on the IETF LDAP Extension Working Group
26 mailing list <ietf-ldapext@netscape.com>. Please send editorial
27 comments directly to the author <Kurt@OpenLDAP.org>.
29 Internet-Drafts are working documents of the Internet Engineering Task
30 Force (IETF), its areas, and its working groups. Note that other
31 groups may also distribute working documents as Internet-Drafts.
32 Internet-Drafts are draft documents valid for a maximum of six months
33 and may be updated, replaced, or obsoleted by other documents at any
34 time. It is inappropriate to use Internet-Drafts as reference
35 material or to cite them other than as ``work in progress.''
37 The list of current Internet-Drafts can be accessed at
38 <http://www.ietf.org/ietf/1id-abstracts.txt>. The list of
39 Internet-Draft Shadow Directories can be accessed at
40 <http://www.ietf.org/shadow.html>.
42 Copyright 2001, The Internet Society. All Rights Reserved.
44 Please see the Copyright section near the end of this document for
50 This document details schema and protocol elements for representing
51 and managing named subordinate references in LDAP directories.
58 Zeilenga LDAP NamedRef [Page 1]
60 INTERNET-DRAFT draft-zeilenga-ldap-namedref-05 20 November 2001
63 Schema definitions are provided using LDAPv3 description formats
64 [RFC2252]. Definitions provided here are formatted (line wrapped) for
67 The key words "SHALL", "SHALL NOT", "MUST", "MUST NOT", "SHOULD",
68 "SHOULD NOT", "MAY" and "MAY NOT" used in this document are to be
69 interpreted as described in BCP 14 [RFC2119].
72 1. Background and Intended Usage
74 The broadening of interest in LDAP (Lightweight Directory Access
75 Protocol) [RFC2251] directories beyond their use as front ends to
76 X.500 [X.500] directories has created a need to represent knowledge
77 information in a more general way. Knowledge information is
78 information about one or more servers maintained in another server,
79 used to link servers and services together.
81 This document details schema and protocol elements for representing
82 and manipulating named subordinate references in LDAP directories. A
83 referral object is used to hold subordinate reference information in
84 the directory. These referral objects hold one or more URIs [RFC2396]
85 contained in values of the ref attribute type and are used to generate
86 protocol referrals and continuations.
88 A control, ManageDsaIT, is defined to allow manipulation of referral
89 and other special objects as normal objects. As the name of control
90 implies, it is intended to be analogous to the ManageDsaIT service
91 option described in X.511(97) [X.511].
93 Other forms of knowledge information are not detailed by this
94 document. These forms may be described in subsequent documents.
96 This document details subordinate referral processing requirements for
97 servers. This document does not describe protocol syntax and
98 semantics. This is detailed in RFC 2251 [RFC2251].
100 This document does not detail use of subordinate knowledge references
101 to support replicated environments nor distributed operations (e.g.,
102 chaining of operations from one server to other servers).
107 2.1. The referral Object Class
109 A referral object is a directory entry whose structural object class
110 is (or is derived from) the referral object class.
114 Zeilenga LDAP NamedRef [Page 2]
116 INTERNET-DRAFT draft-zeilenga-ldap-namedref-05 20 November 2001
119 ( 2.16.840.1.113730.3.2.6
121 DESC 'named subordinate reference object'
125 The referral object class is a structural object class used to
126 represent a subordinate reference in the directory. The referral
127 object class SHOULD be used in conjunction with the extensibleObject
128 object class to support the naming attributes used in the entry's
129 Distinguished Name (DN) [RFC2253]. Referral objects are directory
130 entries whose structural object class is (or is derived from)
133 Referral objects are normally instantiated at DSEs immediately
134 subordinate to object entries within a naming context held by the DSA.
135 Referral objects are analogous to X.500 subordinate knowledge (subr)
138 In the presence of a ManageDsaIT control, referral objects are treated
139 as normal entries as described in section 3. Note that the ref
140 attribute is operational and will only returned in a search entry
141 response when requested.
143 In the absence of a ManageDsaIT control, the content of referral
144 objects are used to construct referrals and search references as
145 described in section 4 and, as such, the referral entries are not
146 themselves visible to clients.
149 2.2 The ref Attribute Type
151 ( 2.16.840.1.113730.3.1.34
153 DESC 'named reference - a labeledURI'
154 EQUALITY caseExactMatch
155 SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
156 USAGE distributedOperation )
158 The ref attribute type has directoryString syntax and is case
159 sensitive. The ref attribute is multi-valued. Values placed in the
160 attribute MUST conform to the specification given for the labeledURI
161 attribute [RFC2079]. The labeledURI specification defines a format
162 that is a URI, optionally followed by whitespace and a label. This
163 document does not make use of the label portion of the syntax. Future
164 documents MAY enable new functionality by imposing additional
165 structure on the label portion of the syntax as it appears in the ref
170 Zeilenga LDAP NamedRef [Page 3]
172 INTERNET-DRAFT draft-zeilenga-ldap-namedref-05 20 November 2001
175 If the URI contained in a ref attribute value refers to a LDAP
176 [RFC2251] server, it MUST be in the form of a LDAP URL [RFC2255]. The
177 LDAP URL SHOULD NOT contain an explicit scope specifier, filter,
178 attribute description list, or any extensions. The LDAP URL SHOULD
179 contain a non-empty DN. The handling of LDAP URLs with absent or
180 empty DN parts or with explicit scope specifier is not defined by this
183 Other URI schemes MAY be used so long as all operations returning
184 referrals based upon the value could be performed. This document does
185 not detail use of non-LDAP URIs. This is left to future
188 The referential integrity of the URI SHOULD NOT be validated by the
189 server holding or returning the URI (whether as a value of the
190 attribute or as part of a referral result or search reference
193 When returning a referral result or search continuation, the server
194 MUST NOT return the separator or label portions of the attribute
195 values as part of the reference. When the attribute contains multiple
196 values, the URI part of each value is used to construct the referral
197 result or search continuation.
199 The ref attribute values SHOULD NOT be used as a relative
200 name-component of an entry's DN [RFC2253].
202 This document uses the ref attribute in conjunction with the referral
203 object class to represent subordinate references. The ref attribute
204 may be used for other purposes as defined by other documents.
207 3. The ManageDsaIT Control
209 The client may provide the ManageDsaIT control with an operation to
210 indicate that the operation is intended to manage objects within the
211 DSA (server) Information Tree. The control causes Directory-specific
212 entries (DSEs), regardless of type, to be treated as normal entries
213 allowing clients to interrogate and update these entries using LDAP
216 A client MAY specify the following control when issuing an add,
217 compare, delete, modify, modifyDN, search request or an extended
218 operation for which the control is defined.
220 The control type is 2.16.840.1.113730.3.4.2. The control criticality
221 may be TRUE or, if FALSE, absent. The control value is absent.
226 Zeilenga LDAP NamedRef [Page 4]
228 INTERNET-DRAFT draft-zeilenga-ldap-namedref-05 20 November 2001
231 When the control is present in the request, the server SHALL NOT
232 generate a referral or continuation reference based upon information
233 held in referral objects and instead SHALL treat the referral object
234 as a normal entry. The server, however, is still free to return
235 referrals for other reasons. When not present, referral objects SHALL
236 be handled as described above.
238 The control MAY cause other objects to be treated as normal entries as
239 defined by subsequent documents.
242 4. Named Subordinate References
244 A named subordinate reference is constructed by instantiating a
245 referral object in the referencing server with ref attribute values
246 which point to the corresponding subtree maintained in the referenced
247 server. In general, the name of the referral object is the same as
248 the referenced object and this referenced object is a context prefix
251 That is, if server A holds "DC=example,DC=net" and server B holds
252 "DC=sub,DC=example,DC=net", server A may contain a referral object
253 named "DC=sub,DC=example,DC=net" which contains a ref attribute with
254 value of "ldap://B/DC=sub,DC=example,DC=net".
256 dn: DC=sub,DC=example,DC=net
258 ref: ldap://B/DC=sub,DC=example,DC=net
259 objectClass: referral
260 objectClass: extensibleObject
262 Typically the DN of the referral object and the DN of the object in
263 the referenced server are the same.
265 If the ref attribute has multiple values, all the DNs contained within
266 the LDAP URLs SHOULD be equivalent. Administrators SHOULD avoid
267 configuring naming loops using referrals.
269 Named references MUST be treated as normal entries if the request
270 includes the ManageDsaIT control as described in section 3.
275 The following sections contain specifications of how referral objects
276 should be used in different scenarios followed by examples that
277 illustrate that usage. The scenarios described here consist of
278 referral object handling when finding target of a non-search
282 Zeilenga LDAP NamedRef [Page 5]
284 INTERNET-DRAFT draft-zeilenga-ldap-namedref-05 20 November 2001
287 operation, when finding the base of a search operation, and when
288 generating search references. Lastly, other operation processing
289 considerations are presented.
291 It is to be noted that, in this document, a search operation is
292 conceptually divided into two distinct, sequential phases: (1) finding
293 the base object where the search is to begin, and (2) performing the
294 search itself. The first phase is similar to, but not the same as,
295 finding the target of a non-search operation.
297 It should also be noted that the ref attribute may have multiple
298 values and, where these sections refer to a single ref attribute
299 value, multiple ref attribute values may be substituted and SHOULD be
300 processed and returned (in any order) as a group in a referral or
301 search reference in the same way as described for a single ref
304 Search references returned for a given request may be returned in any
308 5.1. Example Configuration
310 For example, suppose the contacted server (hosta) holds the entry
311 "O=MNN,C=WW" and the entry "CN=Manager,O=MNN,C=WW" and the following
314 dn: OU=People,O=MNN,C=WW
316 ref: ldap://hostb/OU=People,O=MNN,C=US
317 ref: ldap://hostc/OU=People,O=MNN,C=US
318 objectClass: referral
319 objectClass: extensibleObject
321 dn: OU=Roles,O=MNN,C=WW
323 ref: ldap://hostd/OU=Roles,O=MNN,C=WW
324 objectClass: referral
325 objectClass: extensibleObject
327 The first referral object provides the server with the knowledge that
328 subtree "OU=People,O=MNN,C=WW" is held by hostb and hostc (e.g., one
329 is the master and the other a shadow). The second referral object
330 provides the server with the knowledge that the subtree
331 "OU=Roles,O=MNN,C=WW" is held by hostd.
333 Also, in the context of this document, the "nearest naming context"
334 means the deepest context which the object is within. That is, if the
338 Zeilenga LDAP NamedRef [Page 6]
340 INTERNET-DRAFT draft-zeilenga-ldap-namedref-05 20 November 2001
343 object is within multiple naming contexts, the nearest naming context
344 is the one which is subordinate to all other naming contexts the
348 5.2. Target object considerations
350 This section details referral handling for add, compare, delete,
351 modify, and modify DN operations. If the client requests any of these
352 operations, there are four cases that the server must handle with
353 respect to the target object.
355 The DN part MUST be modified such that it refers to the appropriate
356 target in the referenced server (as detailed below). Even where the
357 DN to be returned is the same as the target DN, the DN part SHOULD NOT
360 In cases where the URI to be returned is a LDAP URL, the server SHOULD
361 trim any present scope, filter, or attribute list from the URI before
362 returning it. Critical extensions MUST NOT be trimmed or modified.
364 Case 1: The target object is not held by the server and is not within
365 or subordinate to any naming context nor subordinate to any
366 referral object held by the server.
368 The server SHOULD process the request normally as appropriate for
369 a non-existent base which is not within any naming context of the
370 server (generally return noSuchObject or a referral based upon
371 superior knowledge reference information). This document does not
372 detail management or processing of superior knowledge reference
375 Case 2: The target object is held by the server and is a referral
378 The server SHOULD return the URI value contained in the ref
379 attribute of the referral object appropriately modified as
382 Example: If the client issues a modify request for the target object
383 of "OU=People,O=MNN,c=WW", the server will return:
385 ModifyResponse (referral) {
386 ldap://hostb/OU=People,O=MNN,C=WW
387 ldap://hostc/OU=People,O=MNN,C=WW
394 Zeilenga LDAP NamedRef [Page 7]
396 INTERNET-DRAFT draft-zeilenga-ldap-namedref-05 20 November 2001
399 Case 3: The target object is not held by the server, but the nearest
400 naming context contains no referral object which the target object
403 If the nearest naming context contains no referral object which
404 the target is subordinate to, the server SHOULD process the
405 request as appropriate for a nonexistent target (generally return
408 Case 4: The target object is not held by the server, but the nearest
409 naming context contains a referral object which the target object
412 If a client requests an operation for which the target object is
413 not held by the server and the nearest naming context contains a
414 referral object which the target object is subordinate to, the
415 server SHOULD return a referral response constructed from the URI
416 portion of the ref value of the referral object.
418 Example: If the client issues an add request where the target object
419 has a DN of "CN=Manager,OU=Roles,O=MNN,C=WW", the server will
422 AddResponse (referral) {
423 ldap://hostd/CN=Manager,OU=Roles,O=MNN,C=WW"
426 Note that the DN part of the LDAP URL is modified such that it
427 refers to the appropriate entry in the referenced server.
430 5.3. Base Object Considerations
432 This section details referral handling for base object processing
433 within search operations. Like target object considerations for non-
434 search operations, there are the four cases.
436 In cases where the URI to be returned is a LDAP URL, the server MUST
437 provide an explicit scope specifier from the LDAP URL prior to
438 returning it. In addition, the DN part MUST be modified such that it
439 refers to the appropriate target in the referenced server (as detailed
442 If aliasing dereferencing was necessary in finding the referral
443 object, the DN part of the URI MUST be replaced with the base DN as
444 modified by the alias dereferencing such that the return URL refers to
445 the new target object per [RFC2251, 4.1.11].
450 Zeilenga LDAP NamedRef [Page 8]
452 INTERNET-DRAFT draft-zeilenga-ldap-namedref-05 20 November 2001
455 Critical extensions MUST NOT be trimmed nor modified.
457 Case 1: The base object is not held by the server and is not within
458 nor subordinate to any naming context held by the server.
460 The server SHOULD process the request normally as appropriate for
461 a non-existent base which not within any naming context of the
462 server (generally return a superior referral or noSuchObject).
463 This document does not detail management or processing of superior
464 knowledge references.
466 Case 2: The base object is held by the server and is a referral
469 The server SHOULD return the URI value contained in the ref
470 attribute of the referral object appropriately modified as
474 Example: If the client issues a subtree search in which the base
475 object is "OU=Roles,O=MNN,C=WW", the server will return
477 SearchResultDone (referral) {
478 ldap://hostd/OU=Roles,O=MNN,C=WW??sub
481 If the client were to issue a base or oneLevel search instead of
482 subtree, the returned LDAP URL would explicitly specify "base" or
483 "one", respectively, instead of "sub".
485 Case 3: The base object is not held by the server, but the nearest
486 naming context contains no referral object which the base object
489 If the nearest naming context contains no referral object which
490 the base is subordinate to, the request SHOULD be processed
491 normally as appropriate for a nonexistent base (generally return
494 Case 4: The base object is not held by the server, but the nearest
495 naming context contains a referral object which the base object is
498 If a client requests an operation for which the target object is
499 not held by the server and the nearest naming context contains a
500 referral object which the target object is subordinate to, the
501 server SHOULD return a referral response which is constructed from
502 the URI portion of the ref value of the referral object.
506 Zeilenga LDAP NamedRef [Page 9]
508 INTERNET-DRAFT draft-zeilenga-ldap-namedref-05 20 November 2001
511 Example: If the client issues a base search request for
512 "CN=Manager,OU=Roles,O=MNN,C=WW", the server will return
514 SearchResultDone (referral) {
515 ldap://hostd/CN=Manager,OU=Roles,O=MNN,C=WW??base"
518 If the client were to issue a subtree or oneLevel search instead
519 of subtree, the returned LDAP URL would explicitly specify "sub"
520 or "one", respectively, instead of "base".
522 Note that the DN part of the LDAP URL is modified such that it
523 refers to the appropriate entry in the referenced server.
526 5.4. Search Continuation Considerations
528 For search operations, once the base object has been found and
529 determined not to be a referral object, the search may progress. Any
530 entry matching the filter and scope of the search which is not a
531 referral object is returned to the client normally as described in
534 For each referral object within the requested scope, regardless of the
535 search filter, the server SHOULD return a SearchResultReference which
536 is constructed from the URI component of values of the ref attribute.
537 If the URI component is not a LDAP URL, it should be returned as is.
538 If the LDAP URL's DN part is absent or empty, the DN part must be
539 modified to contain the DN of the referral object. If the URI
540 component is a LDAP URL, the URI SHOULD be modified to add an explicit
545 If a client requests a subtree search of "O=MNN,C=WW", then in
546 addition to any entries within scope which match the filter, hosta
547 will also return two search references as the two referral objects
548 are within scope. One possible response might be:
550 SearchEntry for O=MNN,C=WW
551 SearchResultReference {
552 ldap://hostb/OU=People,O=MNN,C=WW??sub
553 ldap://hostc/OU=People,O=MNN,C=WW??sub
555 SearchEntry for CN=Manager,O=MNN,C=WW
556 SearchResultReference {
557 ldap://hostd/OU=Roles,O=MNN,C=WW??sub
562 Zeilenga LDAP NamedRef [Page 10]
564 INTERNET-DRAFT draft-zeilenga-ldap-namedref-05 20 November 2001
567 SearchResultDone (success)
571 If a client requests a one level search of "O=MNN,C=WW" then, in
572 addition to any entries one level below the "O=MNN,C=WW" entry
573 matching the filter, the server will also return two search
574 references as the two referral objects are within scope. One
575 possible sequence is shown:
577 SearchResultReference {
578 ldap://hostb/OU=People,O=MNN,C=WW??base
579 ldap://hostc/OU=People,O=MNN,C=WW??base
581 SearchEntry for CN=Manager,O=MNN,C=WW
582 SearchResultReference {
583 ldap://hostd/OU=Roles,O=MNN,C=WW??base
585 SearchResultDone (success)
587 Note: Unlike the examples in Section 4.5.3.1 of RFC 2251, the LDAP
588 URLs returned with the SearchResultReference messages contain,
589 as required by this specification, an explicit scope specifier.
592 5.6. Other Considerations
594 This section details processing considerations for other operations.
599 Servers SHOULD NOT return referral result code if the bind name (or
600 authentication identity or authorization identity) is (or is
601 subordinate to) a referral object but MAY use the knowledge
602 information to process the bind request (such as in support a future
603 distributed operation specification). Where the server makes no use
604 of the knowledge information, the server processes the request
605 normally as appropriate for a non-existent authentication or
606 authorization identity (e.g., return invalidCredentials).
611 If the newSuperior is a referral object or is subordinate to a
612 referral object, the server SHOULD return affectsMultipleDSAs. If the
613 newRDN already exists but is a referral object, the server SHOULD
614 return affectsMultipleDSAs instead of entryAlreadyExists.
618 Zeilenga LDAP NamedRef [Page 11]
620 INTERNET-DRAFT draft-zeilenga-ldap-namedref-05 20 November 2001
623 6. Security Considerations
625 This document defines mechanisms that can be used to tie LDAP (and
626 other) servers together. The information used to tie services
627 together should be protected from unauthorized modification. If the
628 server topology information is not public information, it should be
629 protected from unauthorized disclosure as well.
634 This document borrows heavily from previous work by IETF LDAPext
635 Working Group. In particular, this document is based upon "Named
636 Referral in LDAP Directories" (an expired Internet Draft) by
637 Christopher Lukas, Tim Howes, Michael Roszkowski, Mark C. Smith, and
648 9. Normative References
650 [RFC2079] M. Smith, "Definition of an X.500 Attribute Type and an
651 Object Class to Hold Uniform Resource Identifiers (URIs)",
652 RFC 2079, January 1997.
654 [RFC2119] S. Bradner, "Key Words for use in RFCs to Indicate
655 Requirement Levels", BCP 14 (also RFC 2119), March 1997.
657 [RFC2251] M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access
658 Protocol (v3)", RFC 2251, December 1997.
660 [RFC2252] M. Wahl, A. Coulbeck, T. Howes, S. Kille, "Lightweight
661 Directory Access Protocol (v3): Attribute Syntax
662 Definitions", RFC 2252, December 1997.
664 [RFC2253] M. Wahl, S. Kille, T. Howes, "Lightweight Directory Access
665 Protocol (v3): UTF-8 String Representation of Distinguished
666 Names", RFC 2253, December 1997.
668 [RFC2255] T. Howes, M. Smith, "The LDAP URL Format", RFC 2255,
674 Zeilenga LDAP NamedRef [Page 12]
676 INTERNET-DRAFT draft-zeilenga-ldap-namedref-05 20 November 2001
679 [RFC2396] Berners-Lee, T., R. Fielding, L. Masinter, "Uniform Resource
680 Identifiers (URI): Generic Syntax", RFC 2396, August 1998.
682 [X.501] ITU-T, "The Directory: Models", X.501, 1993.
685 10. Informative References
687 [X.500] ITU-T, "The Directory: Overview of Concepts, Models, and
688 Services", X.500, 1993.
690 [X.511] ITU-T, "The Directory: Abstract Service Definition", X.500,
694 Copyright 2001, The Internet Society. All Rights Reserved.
696 This document and translations of it may be copied and furnished to
697 others, and derivative works that comment on or otherwise explain it
698 or assist in its implementation may be prepared, copied, published and
699 distributed, in whole or in part, without restriction of any kind,
700 provided that the above copyright notice and this paragraph are
701 included on all such copies and derivative works. However, this
702 document itself may not be modified in any way, such as by removing
703 the copyright notice or references to the Internet Society or other
704 Internet organizations, except as needed for the purpose of
705 developing Internet standards in which case the procedures for
706 copyrights defined in the Internet Standards process must be followed,
707 or as required to translate it into languages other than English.
709 The limited permissions granted above are perpetual and will not be
710 revoked by the Internet Society or its successors or assigns.
712 This document and the information contained herein is provided on an
713 "AS IS" basis and THE AUTHORS, THE INTERNET SOCIETY, AND THE INTERNET
714 ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED,
715 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
716 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
717 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
730 Zeilenga LDAP NamedRef [Page 13]