7 INTERNET-DRAFT Kurt D. Zeilenga
8 Intended Category: Standard Track OpenLDAP Foundation
9 Expires: 4 January 2001 4 July 2000
12 Named References in LDAP Directories
13 <draft-zeilenga-ldap-namedref-00.txt>
15 1. Status of this Memo
17 This document is an Internet-Draft and is in full conformance with all
18 provisions of Section 10 of RFC2026.
20 This document is intended to be, after appropriate review and
21 revision, submitted to the RFC Editor as a Standard Track document.
22 Distribution of this memo is unlimited. Technical discussion of this
23 document will take place on the IETF LDAP Extension Working Group
24 mailing list <ietf-ldapext@netscape.com>. Please send editorial
25 comments directly to the author <Kurt@OpenLDAP.org>.
27 Internet-Drafts are working documents of the Internet Engineering Task
28 Force (IETF), its areas, and its working groups. Note that other
29 groups may also distribute working documents as Internet-Drafts.
30 Internet-Drafts are draft documents valid for a maximum of six months
31 and may be updated, replaced, or obsoleted by other documents at any
32 time. It is inappropriate to use Internet-Drafts as reference
33 material or to cite them other than as ``work in progress.''
35 The list of current Internet-Drafts can be accessed at
36 http://www.ietf.org/ietf/1id-abstracts.txt The list of Internet-Draft
37 Shadow Directories can be accessed at http://www.ietf.org/shadow.html.
39 Copyright 2000, The Internet Society. All Rights Reserved.
41 Please see the Copyright section near the end of this document for
46 This document defines schema and protocol elements for representing
47 and manipulating generic knowledge information in LDAP [RFC2251]
48 directories. An attribute type "ref" is used to store URIs [RFC1738]
49 which may refer to LDAP and non-LDAP services. An object class
50 "referral" is used to construct entries in an LDAP directory which
51 references to other directories or services. An control, ManageDsaIT,
52 is defined to allow clients to manipulate referral objects as normal
53 entries. The document describes procedures directory servers should
54 follow when supporting these elements.
60 INTERNET-DRAFT draft-zeilenga-ldap-namedref-00 4 July 2000
63 3. Background and intended usage
65 The broadening of interest in LDAP directories beyond their use as
66 front ends to X.500 directories has created a need to represent
67 knowledge information in a more general way. Knowledge information is
68 information about one or more servers maintained in another server,
69 used to link servers and services together.
71 This document defines a general method of representing knowledge
72 information in LDAP directories, based on URIs.
74 This document does not detail client processing of referral and search
75 reference responses. This is detailed in RFC 2251 or subsequent
78 The key words "SHALL", "SHALL NOT", "MUST", "MUST NOT", "SHOULD",
79 "SHOULD NOT", "MAY" and "MAY NOT" used in this document are to be
80 interpreted as described in [RFC2119].
85 4.1 The ref attribute type
87 This section defines the ref attribute type for holding general
88 knowledge reference information.
90 ( 2.16.840.1.113730.3.1.34
93 EQUALITY caseExactIA5Match
94 SYNTAX 1.3.6.1.4.1.1466.115.121.1.26
95 USAGE distributedOperation )
97 The ref attribute type has IA5 syntax and is case sensitive. The ref
98 attribute is multi valued. Values placed in the attribute MUST conform
99 to the specification given for the labeledURI attribute defined in
100 [RFC2079]. The labeledURI specification defines a format that is a
101 URI, optionally followed by whitespace and a label. This document does
102 not make use of the label portion of the syntax. Future documents MAY
103 enable new functionality by imposing additional structure on the label
104 portion of the syntax as it appears in the ref attribute.
106 If the URI contained in a ref attribute value refers to an LDAPv3
107 server, it MUST be in the LDAP URI scheme described in [RFC2255].
108 Other URI schemes MAY be used but MUST refer to services which are
109 capable of completing operations referred to the services. The URI
110 values, regardless of scheme, contained in a ref attribute must point
116 INTERNET-DRAFT draft-zeilenga-ldap-namedref-00 4 July 2000
119 to services which are equally capable of handling operations refer to
122 The integrity of the URI SHALL NOT be validated by the server holding
123 or returning the reference.
125 When returning a referral result, the server MUST NOT return the label
126 portion of the labeledURI as part of the referral. Only the URI
127 portion of the ref attribute SHOULD be returned.
129 The ref attribute SHOULD NOT be used for naming.
132 4.2. The referral object class
134 The referral object class is defined as follows.
136 ( 2.16.840.1.113730.3.2.6
138 DESC 'named reference object'
139 STRUCTURAL MUST ref )
141 The referral object class is a structural object class used to
142 represent a named reference in the directory. The referral object
143 class SHOULD be used in conjunction with the extensibleObject object
144 class to support the naming attributes used in the entry's
147 In the presence of a ManageDsaIT control, referral objects are treated
148 as normal entries. Note that the ref attribute is operational and
149 will only returned in a search entry response when requested.
151 In the absence of a ManageDsaIT control, referral objects contents are
152 used to construct referrals and search references and, as such, the
153 referral entries themselves are general visible to clients.
156 5. Use of the ref attribute
158 Two uses the ref attribute is defined in this document. The first
159 use, in conjunction with the referral object class, represents a named
160 reference. The second use, in conjunction with the Root DSE,
161 represents superior reference. The following sections detail these
162 usages of the ref attribute.
164 Other uses of the ref attribute MAY be defined in subsequent
165 documents, or by bilateral agreement between cooperating clients and
166 servers and SHOULD be defined in conjunction with an object class
172 INTERNET-DRAFT draft-zeilenga-ldap-namedref-00 4 July 2000
175 indicating the usage.
180 A named reference is used to facilitate distributed name resolution or
181 search across multiple servers. The ref attribute appears in an
182 referral object (an entry with object class of referral) named in the
183 referencing server. The value of the ref attribute points to the
184 corresponding entry maintained in the referenced server.
186 While the distinguished name in a value of the ref attribute is
187 typically that of an entry in a naming context below the naming
188 context held by the referencing server, it is permitted to be the
189 distinguished name of any entry. If the ref attribute is multi-valued
190 all the DNs in the values of the ref attribute SHOULD have the same
191 value. Administrators SHOULD avoid configuring naming loops using
194 The URI SHOULD NOT explicitly define a scope and the server SHOULD NOT
195 explicitly add a scope to the URI before returning it to the client as
196 a referral or search reference as the scope is implied by the
199 Named references MUST be treated as normal entries if the request
200 includes the ManageDsaIT control. The remainder of this section
201 describes processing of requests which do not include the ManageDsaIT
207 The following sections contain specifications of how referral objects
208 should be used in different scenarios followed by examples that
209 illustrate that usage. The scenarios described consist of referral
210 operation when finding target of a non-search operation, when finding
211 the base of a search operation, and when generating search references.
213 It is to be noted that, in this document, a search operation is
214 conceptually divided into two distinct, sequential phases: (1) finding
215 the base object where the search is to begin, and (2) performing the
216 search itself. The operation of the server with respect to referrals
217 in phase (1) is similar to the operation of the server while finding
218 the target object for a non-search operations.
220 It is to also be noted that the ref attribute may have multiple values
221 and, where these sections refer to a single ref attribute value,
222 multiple ref attribute values may be substituted and SHOULD be
228 INTERNET-DRAFT draft-zeilenga-ldap-namedref-00 4 July 2000
231 processed and returned as a group in a referral or search reference in
232 the same way as described for a single ref attribute value.
234 Search references returned for a given request may be returned in any
238 5.1.1.1. Example configuration
241 |------------------------------------------------------------|
243 | dn: o=abc,c=us dn: o=xyz,c=us |
245 | ref: ldap://hostB/o=abc,c=us ref: ldap://hostD/o=xyz,c=us |
246 | ref: ldap://hostC/o=abc,c=us objectclass: referral |
247 | objectclass: referral objectclass: extensibleObject|
248 | objectclass: extensibleObject |
249 |____________________________________________________________|
251 |------------------| |------------------| |------------------|
252 | Server B | | Server D | | Server C |
253 | dn: o=abc,c=us | | dn: o=xyz,c=us | | dn: o=abc,c=us |
254 | o: abc | | o: xyz | | o: abc |
255 | other attributes | | other attributes | | other attributes |
256 |__________________| |__________________| |__________________|
258 In this example, Server A holds references for two entries:
259 "o=abc,c=us" and "o=xyz,c=us". For the "o=abc,c=us" entry, Server A
260 holds two references, one to Server B and one to Server C. The
261 entries referenced are replicas of each other. For the "o=xyz,c=us"
262 entry, Server A holds a single reference to the entry contained in
265 In the following protocol interaction examples, the client has
266 contacted Server A. Server A holds the naming context "c=us".
269 5.1.1.2. Base or Target object considerations
271 As previously described, the process of generating referrals for a
272 search can be described in two phases. The first, which is described
273 in this section, is generating referrals based on the base object
274 specified in the search. This process is similar to the process of
275 generating referrals based on the target object while processing other
276 operations (modify, add, delete, modify DN, and compare) with the sole
277 exception that for these other operations, the DN in the referral must
278 be modified in some cases.
284 INTERNET-DRAFT draft-zeilenga-ldap-namedref-00 4 July 2000
287 If a client requests any of these operations, there are four cases
288 that the server must handle with respect to the base or target object
289 specified in the request.
291 Case 1: The base or target object is not held by the server and is not
292 within or subordinate to any naming context nor is subordinate to any
293 referral object held by the server.
295 The handling of this case is described in section 6.
297 Case 2: The base or target object is held by the server and is a
300 In this case, if the type of operation requested is a search or the
301 URI contained in the ref attribute of the requested base object is NOT
302 an LDAP URI, the server SHOULD return the URI value contained in the
303 ref attribute of the base object whose DN is the DN requested by the
304 client as the base for the operation.
308 If the client issues a search in which the base object is
309 "o=xyz,c=us", server A will return
311 SearchResultDone "referral" {
312 ldap://hostD/o=xyz,c=us
315 If the type of operation requested is not a search and the URI
316 contained in the ref attribute of the requested target object is an
317 LDAP URI, the server SHOULD return a modified form of this URI. The
318 returned URI MUST have only the protocol, host, port, and trailing "/"
319 portion of the URI contained in the ref attribute. The server SHOULD
320 strip any DN, attributes, scope, and filter parts of the URI.
324 If the client issues a modify request for the target object of
325 "o=abc,c=us", server A will return
327 ModifyResponse "referral" {
332 Case 3: The base or target object is not held by the server, but is
333 object where the nearest naming context contains no referral object
334 which the base or target object is subordinate to.
340 INTERNET-DRAFT draft-zeilenga-ldap-namedref-00 4 July 2000
343 In the context of this document, the nearest naming context means the
344 deepest context which the object is within. That is, if the object is
345 within multiple naming contexts, the nearest naming context the one
346 which is subordinate to all other naming contexts the object is
349 If the nearest naming context contains no referral object which the
350 base or target object is subordinate to the request, request SHOULD be
351 process normally as appropriate for a nonexistent base or target
352 object (generally return noSuchObject).
354 Case 4: The base or target object is not held by the server, but is
355 object where the nearest naming context contains a referral object
356 which the base or target object is subordinate to.
358 As noted above, the nearest naming context means the deepest context
359 which the object is within.
361 If a client requests an operation for which the base or target object
362 is not held by the server but the nearest naming context contains a
363 referral object which the base or target object is subordinate to, the
364 server MUST return a referral response which contains referral values
365 constructed from the URI components of ref attribute values of the
368 For each ref attribute value, if the URI component is not an LDAP
369 URIs, it SHOULD be returned as-is. If URI component is an LDAP URI,
370 the URI MUST be modified, regardless of the type of operation, as case
371 2 describes for a non-search request. That is, the DN, attributes,
372 scope, and filter parts of the URI MUST be stripped from the returned
377 If the client issues an add request where the target object has a DN
378 of "cn=Chris Lukas,o=abc,c=us", server A will return
380 AddResponse "referral" {
386 5.1.1.3. Search with one level or subtree scope
388 For search operations, once the base object has been found and
389 determined not to be a referral object, the search may progress. Any
390 entries matching the filter and scope of the search which is not a
396 INTERNET-DRAFT draft-zeilenga-ldap-namedref-00 4 July 2000
399 referral object are returned to the client normally as described in
402 For each referral object within the requested scope, regardless of the
403 filter, the server SHOULD return a SearchResultReference which is
404 constructed from the URI component of values of the ref attribute. If
405 the URI component is not an LDAP URI, it should be returned as is. If
406 the URI component is an LDAP URI, the URI must be modified to remove
407 any explicit scope specifier.
411 If a client requests a one level search of "c=US" then, in addition to
412 any entries one level below the "c=US" naming context matching the
413 filter (shown below as "... SearchResultEntry responses ..."), the
414 server will also return search references for any referral object
415 within the scope of the search.
417 The order of the SearchResultEntry responses and the
418 SearchResultReference responses is undefined. One possible sequence
421 ... SearchResultEntry responses ...
423 SearchResultReference {
424 ldap://hostB/o=abc,c=us
425 ldap://hostC/o=abc,c=us
428 SearchResultReference {
429 ldap://hostD/o=xyz,c=us
432 SearchResultDone "success"
437 If a client requests a subtree search of "c=us", then in addition to
438 any entries in the "c=us" naming context which match the filter,
439 Server A will also return two continuation references. As described in
440 the preceding section, the order of the responses is not defined.
442 One possible response might be:
444 SearchResultReference {
445 ldap://hostB/o=abc,c=us
446 ldap://hostC/o=abc,c=us
452 INTERNET-DRAFT draft-zeilenga-ldap-namedref-00 4 July 2000
457 ... SearchResultEntry responses ...
459 SearchResultReference {
460 ldap://hostD/o=xyz,c=us
463 SearchResultDone "success"
466 6. Superior Reference
468 An LDAP server may be configured to return a superior reference in the
469 case where the requested base or target object is not contained within
470 or subordinate to a naming context held by the server or referral
473 An LDAP server's root DSE MAY contain a ref attribute. The values of
474 the ref attribute in the root DSE that are LDAP URIs SHOULD NOT
475 contain any DN part nor other search parameters (scope, filter,
476 attribute list). They MUST include the URI hostpart.
478 If the LDAP server's root DSE contains a ref attribute and a client
479 requests a target or base object not held by the server and not
480 contained within or subordinate to any naming context held by the
481 server or referral object, the server MUST return the URI component of
482 the values in the ref attribute of the root DSE as illustrated in the
485 If the LDAP server's root DSE does not contain a ref attribute, the
486 server may return referral result with or more URIs determined via an
487 appropriate method, return noSuchObject, or other appropriate
490 The presence of the ref attribute within the root DSE SHALL NOT cause
491 operations upon the root DSE to generate a referral.
495 If a client requests a subtree search of "c=de" from server A in the
496 example configuration, and server A has the following ref attribute
497 defined in it's root DSE:
501 then server A will return
508 INTERNET-DRAFT draft-zeilenga-ldap-namedref-00 4 July 2000
511 SearchResultDone "referral" {
516 8. The ManageDsaIT control
518 The ManageDsaIT control indicates that the operation has been
519 requested so that the DSA (server) Information Tree is managed. The
520 controls causes DSEs, regardless of type, to be treated as normal
521 entries allowing clients to interrogate and update these entries using
522 LDAP operations. This control is analogous to the ManageDsaIT option
523 described in X.511(93) [X.511].
525 A client MAY specify the following control when issuing an add,
526 compare, delete, modify, modifyDN, search request or an extended
527 operation for which the control is defined.
529 The control type is 2.16.840.1.113730.3.4.2. The control criticality
530 may be TRUE or FALSE. There is no value; the controlValue field is
533 When present in the request, the server SHALL NOT generate a referral
534 or continuation reference for any referral object and instead perform
535 treat the referral object as an normal entry. When not present,
536 referral objects SHALL be handled as described above.
538 The control MAY cause other objects to be treated as normal entries as
539 defined by subsequent documents.
542 9. Relationship to X.500 Knowledge References
544 The X.500 standard defines several types of knowledge references, used
545 to bind together different parts of the X.500 namespace. In X.500,
546 knowledge references can be associated with a set of unnamed entries
547 (e.g., a reference, associated with an entry, to a server containing
548 the descendants of that entry).
550 This creates a potential problem for LDAP clients resolving an LDAPv3
551 URI referral referring to an LDAP directory back-ended by X.500.
552 Suppose the search is a subtree search, and that server A holds the
553 base object of the search, and server B holds the descendants of the
554 base object. The behavior of X.500(1993) subordinate references is
555 that the base object on server A is searched, and a single
556 continuation reference is returned pointing to all of the descendants
564 INTERNET-DRAFT draft-zeilenga-ldap-namedref-00 4 July 2000
567 An LDAP URI only allows the base object to be specified. It is not
568 possible using standard LDAP URIs to indicate a search of several
569 entries whose names are not known to the server holding the superior
572 X.500 solves this problem by having two fields, one indicating the
573 progress of name resolution and the other indicating the target of the
574 search. In the above example, name resolution would be complete by the
575 time the query reached server B, indicating that it should not refer
578 This document does not address this problem. This problem will be
579 addressed in separate documents which define the changes to the X.500
580 distribution model and LDAPv3 extensions to indicate the progress of
584 10. Security Considerations
586 This document defines mechanisms that can be used to "glue" LDAP (and
587 other) servers together. The information used to specify this glue
588 information should be protected from unauthorized modification. If
589 the server topology information itself is not public information, the
590 information should be protected from unauthorized access as well.
595 [RFC1738] Berners-Lee, T., Masinter, L., and McCahill, M., "Uniform
596 Resource Locators (URL)", RFC 1738, CERN, Xerox Corporation,
597 University of Minnesota, December 1994.
599 [RFC2079] M. Smith, "Definition of an X.500 Attribute Type and an
600 Object Class to Hold Uniform Resource Identifiers (URIs)",
601 RFC 2079, January 1997.
603 [RFC2119] S. Bradner, "Key Words for use in RFCs to Indicate
604 Requirement Levels", RFC 2119 (Also BCP0014), March 1997.
606 [RFC2251] M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access
607 Protocol (v3)", RFC 2251, December 1997.
609 [RFC2255] T. Howes, M. Smith, "The LDAP URL Format", RFC 2255,
612 [X.500] ITU-T Rec. X.501, "The Directory: Models", 1993.
614 [X.511] ITU-T Rec. X.511, "The Directory: Abstract Service
620 INTERNET-DRAFT draft-zeilenga-ldap-namedref-00 4 July 2000
629 This document is borrows heavily from previous work by IETF LDAPext
630 working group. In particular, this document is based upon "Named
631 Referral in LDAP Directories" (a work in progress) by Christopher
632 Lukes, Tim Howes, Michael Roszkowski, Mark C. Smith, and Mark Wahl.
642 This draft expires 4 Jan. 2001.