1 2 3 4 5 6 7Network Working Group K. Zeilenga 8Request for Comments: 3296 OpenLDAP Foundation 9Category: Standards Track July 2002 10 11 12 Named Subordinate References in 13 Lightweight Directory Access Protocol (LDAP) Directories 14 15Status of this Memo 16 17 This document specifies an Internet standards track protocol for the 18 Internet community, and requests discussion and suggestions for 19 improvements. Please refer to the current edition of the "Internet 20 Official Protocol Standards" (STD 1) for the standardization state 21 and status of this protocol. Distribution of this memo is unlimited. 22 23Copyright Notice 24 25 Copyright (C) The Internet Society (2002). All Rights Reserved. 26 27Abstract 28 29 This document details schema and protocol elements for representing 30 and managing named subordinate references in Lightweight Directory 31 Access Protocol (LDAP) Directories. 32 33Conventions 34 35 Schema definitions are provided using LDAPv3 description formats 36 [RFC2252]. Definitions provided here are formatted (line wrapped) 37 for readability. 38 39 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 40 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" used in 41 this document are to be interpreted as described in BCP 14 [RFC2119]. 42 431. Background and Intended Usage 44 45 The broadening of interest in LDAP (Lightweight Directory Access 46 Protocol) [RFC2251] directories beyond their use as front ends to 47 X.500 [X.500] directories has created a need to represent knowledge 48 information in a more general way. Knowledge information is 49 information about one or more servers maintained in another server, 50 used to link servers and services together. 51 52 This document details schema and protocol elements for representing 53 and manipulating named subordinate references in LDAP directories. A 54 referral object is used to hold subordinate reference information in 55 56 57 58Zeilenga Standards Track [Page 1] 59 60RFC 3296 Named Subordinate References in LDAP Directories July 2002 61 62 63 the directory. These referral objects hold one or more URIs 64 [RFC2396] contained in values of the ref attribute type and are used 65 to generate protocol referrals and continuations. 66 67 A control, ManageDsaIT, is defined to allow manipulation of referral 68 and other special objects as normal objects. As the name of control 69 implies, it is intended to be analogous to the ManageDsaIT service 70 option described in X.511(97) [X.511]. 71 72 Other forms of knowledge information are not detailed by this 73 document. These forms may be described in subsequent documents. 74 75 This document details subordinate referral processing requirements 76 for servers. This document does not describe protocol syntax and 77 semantics. This is detailed in RFC 2251 [RFC2251]. 78 79 This document does not detail use of subordinate knowledge references 80 to support replicated environments nor distributed operations (e.g., 81 chaining of operations from one server to other servers). 82 832. Schema 84 852.1. The referral Object Class 86 87 A referral object is a directory entry whose structural object class 88 is (or is derived from) the referral object class. 89 90 ( 2.16.840.1.113730.3.2.6 91 NAME 'referral' 92 DESC 'named subordinate reference object' 93 STRUCTURAL 94 MUST ref ) 95 96 The referral object class is a structural object class used to 97 represent a subordinate reference in the directory. The referral 98 object class SHOULD be used in conjunction with the extensibleObject 99 object class to support the naming attributes used in the entry's 100 Distinguished Name (DN) [RFC2253]. 101 102 Referral objects are normally instantiated at DSEs immediately 103 subordinate to object entries within a naming context held by the 104 DSA. Referral objects are analogous to X.500 subordinate knowledge 105 (subr) DSEs [X.501]. 106 107 108 109 110 111 112 113 114Zeilenga Standards Track [Page 2] 115 116RFC 3296 Named Subordinate References in LDAP Directories July 2002 117 118 119 In the presence of a ManageDsaIT control, referral objects are 120 treated as normal entries as described in section 3. Note that the 121 ref attribute is operational and will only be returned in a search 122 entry response when requested. 123 124 In the absence of a ManageDsaIT control, the content of referral 125 objects are used to construct referrals and search references as 126 described in Section 4 and, as such, the referral entries are not 127 themselves visible to clients. 128 1292.2 The ref Attribute Type 130 131 ( 2.16.840.1.113730.3.1.34 132 NAME 'ref' 133 DESC 'named reference - a labeledURI' 134 EQUALITY caseExactMatch 135 SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 136 USAGE distributedOperation ) 137 138 The ref attribute type has directoryString syntax and is case 139 sensitive. The ref attribute is multi-valued. Values placed in the 140 attribute MUST conform to the specification given for the labeledURI 141 attribute [RFC2079]. The labeledURI specification defines a format 142 that is a URI, optionally followed by whitespace and a label. This 143 document does not make use of the label portion of the syntax. 144 Future documents MAY enable new functionality by imposing additional 145 structure on the label portion of the syntax as it appears in the ref 146 attribute. 147 148 If the URI contained in a ref attribute value refers to a LDAP 149 [RFC2251] server, it MUST be in the form of a LDAP URL [RFC2255]. 150 The LDAP URL SHOULD NOT contain an explicit scope specifier, filter, 151 attribute description list, or any extensions. The LDAP URL SHOULD 152 contain a non-empty DN. The handling of LDAP URLs with absent or 153 empty DN parts or with explicit scope specifier is not defined by 154 this specification. 155 156 Other URI schemes MAY be used so long as all operations returning 157 referrals based upon the value could be performed. This document 158 does not detail use of non-LDAP URIs. This is left to future 159 specifications. 160 161 The referential integrity of the URI SHOULD NOT be validated by the 162 server holding or returning the URI (whether as a value of the 163 attribute or as part of a referral result or search reference 164 response). 165 166 167 168 169 170Zeilenga Standards Track [Page 3] 171 172RFC 3296 Named Subordinate References in LDAP Directories July 2002 173 174 175 When returning a referral result or search continuation, the server 176 MUST NOT return the separator or label portions of the attribute 177 values as part of the reference. When the attribute contains 178 multiple values, the URI part of each value is used to construct the 179 referral result or search continuation. 180 181 The ref attribute values SHOULD NOT be used as a relative name- 182 component of an entry's DN [RFC2253]. 183 184 This document uses the ref attribute in conjunction with the referral 185 object class to represent subordinate references. The ref attribute 186 may be used for other purposes as defined by other documents. 187 1883. The ManageDsaIT Control 189 190 The client may provide the ManageDsaIT control with an operation to 191 indicate that the operation is intended to manage objects within the 192 DSA (server) Information Tree. The control causes Directory-specific 193 entries (DSEs), regardless of type, to be treated as normal entries 194 allowing clients to interrogate and update these entries using LDAP 195 operations. 196 197 A client MAY specify the following control when issuing an add, 198 compare, delete, modify, modifyDN, search request or an extended 199 operation for which the control is defined. 200 201 The control type is 2.16.840.1.113730.3.4.2. The control criticality 202 may be TRUE or, if FALSE, absent. The control value is absent. 203 204 When the control is present in the request, the server SHALL NOT 205 generate a referral or continuation reference based upon information 206 held in referral objects and instead SHALL treat the referral object 207 as a normal entry. The server, however, is still free to return 208 referrals for other reasons. When not present, referral objects 209 SHALL be handled as described above. 210 211 The control MAY cause other objects to be treated as normal entries 212 as defined by subsequent documents. 213 2144. Named Subordinate References 215 216 A named subordinate reference is constructed by instantiating a 217 referral object in the referencing server with ref attribute values 218 which point to the corresponding subtree maintained in the referenced 219 server. In general, the name of the referral object is the same as 220 the referenced object and this referenced object is a context prefix 221 [X.501]. 222 223 224 225 226Zeilenga Standards Track [Page 4] 227 228RFC 3296 Named Subordinate References in LDAP Directories July 2002 229 230 231 That is, if server A holds "DC=example,DC=net" and server B holds 232 "DC=sub,DC=example,DC=net", server A may contain a referral object 233 named "DC=sub,DC=example,DC=net" which contains a ref attribute with 234 value of "ldap://B/DC=sub,DC=example,DC=net". 235 236 dn: DC=sub,DC=example,DC=net 237 dc: sub 238 ref: ldap://B/DC=sub,DC=example,DC=net 239 objectClass: referral 240 objectClass: extensibleObject 241 242 Typically the DN of the referral object and the DN of the object in 243 the referenced server are the same. 244 245 If the ref attribute has multiple values, all the DNs contained 246 within the LDAP URLs SHOULD be equivalent. Administrators SHOULD 247 avoid configuring naming loops using referrals. 248 249 Named references MUST be treated as normal entries if the request 250 includes the ManageDsaIT control as described in section 3. 251 2525. Scenarios 253 254 The following sections contain specifications of how referral objects 255 should be used in different scenarios followed by examples that 256 illustrate that usage. The scenarios described here consist of 257 referral object handling when finding target of a non-search 258 operation, when finding the base of a search operation, and when 259 generating search references. Lastly, other operation processing 260 considerations are presented. 261 262 It is to be noted that, in this document, a search operation is 263 conceptually divided into two distinct, sequential phases: (1) 264 finding the base object where the search is to begin, and (2) 265 performing the search itself. The first phase is similar to, but not 266 the same as, finding the target of a non-search operation. 267 268 It should also be noted that the ref attribute may have multiple 269 values and, where these sections refer to a single ref attribute 270 value, multiple ref attribute values may be substituted and SHOULD be 271 processed and returned (in any order) as a group in a referral or 272 search reference in the same way as described for a single ref 273 attribute value. 274 275 Search references returned for a given request may be returned in any 276 order. 277 278 279 280 281 282Zeilenga Standards Track [Page 5] 283 284RFC 3296 Named Subordinate References in LDAP Directories July 2002 285 286 2875.1. Example Configuration 288 289 For example, suppose the contacted server (hosta) holds the entry 290 "O=MNN,C=WW" and the entry "CN=Manager,O=MNN,C=WW" and the following 291 referral objects: 292 293 dn: OU=People,O=MNN,C=WW 294 ou: People 295 ref: ldap://hostb/OU=People,O=MNN,C=US 296 ref: ldap://hostc/OU=People,O=MNN,C=US 297 objectClass: referral 298 objectClass: extensibleObject 299 300 dn: OU=Roles,O=MNN,C=WW 301 ou: Roles 302 ref: ldap://hostd/OU=Roles,O=MNN,C=WW 303 objectClass: referral 304 objectClass: extensibleObject 305 306 The first referral object provides the server with the knowledge that 307 subtree "OU=People,O=MNN,C=WW" is held by hostb and hostc (e.g., one 308 is the master and the other a shadow). The second referral object 309 provides the server with the knowledge that the subtree 310 "OU=Roles,O=MNN,C=WW" is held by hostd. 311 312 Also, in the context of this document, the "nearest naming context" 313 means the deepest context which the object is within. That is, if 314 the object is within multiple naming contexts, the nearest naming 315 context is the one which is subordinate to all other naming contexts 316 the object is within. 317 3185.2. Target Object Considerations 319 320 This section details referral handling for add, compare, delete, 321 modify, and modify DN operations. If the client requests any of 322 these operations, there are four cases that the server must handle 323 with respect to the target object. 324 325 The DN part MUST be modified such that it refers to the appropriate 326 target in the referenced server (as detailed below). Even where the 327 DN to be returned is the same as the target DN, the DN part SHOULD 328 NOT be trimmed. 329 330 In cases where the URI to be returned is a LDAP URL, the server 331 SHOULD trim any present scope, filter, or attribute list from the URI 332 before returning it. Critical extensions MUST NOT be trimmed or 333 modified. 334 335 336 337 338Zeilenga Standards Track [Page 6] 339 340RFC 3296 Named Subordinate References in LDAP Directories July 2002 341 342 343 Case 1: The target object is not held by the server and is not within 344 or subordinate to any naming context nor subordinate to any 345 referral object held by the server. 346 347 The server SHOULD process the request normally as appropriate for 348 a non-existent base which is not within any naming context of the 349 server (generally return noSuchObject or a referral based upon 350 superior knowledge reference information). This document does not 351 detail management or processing of superior knowledge reference 352 information. 353 354 Case 2: The target object is held by the server and is a referral 355 object. 356 357 The server SHOULD return the URI value contained in the ref 358 attribute of the referral object appropriately modified as 359 described above. 360 361 Example: If the client issues a modify request for the target object 362 of "OU=People,O=MNN,c=WW", the server will return: 363 364 ModifyResponse (referral) { 365 ldap://hostb/OU=People,O=MNN,C=WW 366 ldap://hostc/OU=People,O=MNN,C=WW 367 } 368 369 Case 3: The target object is not held by the server, but the nearest 370 naming context contains no referral object which the target object 371 is subordinate to. 372 373 If the nearest naming context contains no referral object which 374 the target is subordinate to, the server SHOULD process the 375 request as appropriate for a nonexistent target (generally return 376 noSuchObject). 377 378 Case 4: The target object is not held by the server, but the nearest 379 naming context contains a referral object which the target object 380 is subordinate to. 381 382 If a client requests an operation for which the target object is 383 not held by the server and the nearest naming context contains a 384 referral object which the target object is subordinate to, the 385 server SHOULD return a referral response constructed from the URI 386 portion of the ref value of the referral object. 387 388 389 390 391 392 393 394Zeilenga Standards Track [Page 7] 395 396RFC 3296 Named Subordinate References in LDAP Directories July 2002 397 398 399 Example: If the client issues an add request where the target object 400 has a DN of "CN=Manager,OU=Roles,O=MNN,C=WW", the server will 401 return: 402 403 AddResponse (referral) { 404 ldap://hostd/CN=Manager,OU=Roles,O=MNN,C=WW" 405 } 406 407 Note that the DN part of the LDAP URL is modified such that it 408 refers to the appropriate entry in the referenced server. 409 4105.3. Base Object Considerations 411 412 This section details referral handling for base object processing 413 within search operations. Like target object considerations for 414 non-search operations, there are the four cases. 415 416 In cases where the URI to be returned is a LDAP URL, the server MUST 417 provide an explicit scope specifier from the LDAP URL prior to 418 returning it. In addition, the DN part MUST be modified such that it 419 refers to the appropriate target in the referenced server (as 420 detailed below). 421 422 If aliasing dereferencing was necessary in finding the referral 423 object, the DN part of the URI MUST be replaced with the base DN as 424 modified by the alias dereferencing such that the return URL refers 425 to the new target object per [RFC2251, 4.1.11]. 426 427 Critical extensions MUST NOT be trimmed nor modified. 428 429 Case 1: The base object is not held by the server and is not within 430 nor subordinate to any naming context held by the server. 431 432 The server SHOULD process the request normally as appropriate for 433 a non-existent base which not within any naming context of the 434 server (generally return a superior referral or noSuchObject). 435 This document does not detail management or processing of superior 436 knowledge references. 437 438 Case 2: The base object is held by the server and is a referral 439 object. 440 441 The server SHOULD return the URI value contained in the ref 442 attribute of the referral object appropriately modified as 443 described above. 444 445 446 447 448 449 450Zeilenga Standards Track [Page 8] 451 452RFC 3296 Named Subordinate References in LDAP Directories July 2002 453 454 455 Example: If the client issues a subtree search in which the base 456 object is "OU=Roles,O=MNN,C=WW", the server will return 457 458 SearchResultDone (referral) { 459 ldap://hostd/OU=Roles,O=MNN,C=WW??sub 460 } 461 462 If the client were to issue a base or oneLevel search instead of 463 subtree, the returned LDAP URL would explicitly specify "base" or 464 "one", respectively, instead of "sub". 465 466 Case 3: The base object is not held by the server, but the nearest 467 naming context contains no referral object which the base object 468 is subordinate to. 469 470 If the nearest naming context contains no referral object which 471 the base is subordinate to, the request SHOULD be processed 472 normally as appropriate for a nonexistent base (generally return 473 noSuchObject). 474 475 Case 4: The base object is not held by the server, but the nearest 476 naming context contains a referral object which the base object is 477 subordinate to. 478 479 If a client requests an operation for which the target object is 480 not held by the server and the nearest naming context contains a 481 referral object which the target object is subordinate to, the 482 server SHOULD return a referral response which is constructed from 483 the URI portion of the ref value of the referral object. 484 485 Example: If the client issues a base search request for 486 "CN=Manager,OU=Roles,O=MNN,C=WW", the server will return 487 488 SearchResultDone (referral) { 489 ldap://hostd/CN=Manager,OU=Roles,O=MNN,C=WW??base" 490 } 491 492 If the client were to issue a subtree or oneLevel search instead 493 of subtree, the returned LDAP URL would explicitly specify "sub" 494 or "one", respectively, instead of "base". 495 496 Note that the DN part of the LDAP URL is modified such that it 497 refers to the appropriate entry in the referenced server. 498 499 500 501 502 503 504 505 506Zeilenga Standards Track [Page 9] 507 508RFC 3296 Named Subordinate References in LDAP Directories July 2002 509 510 5115.4. Search Continuation Considerations 512 513 For search operations, once the base object has been found and 514 determined not to be a referral object, the search may progress. Any 515 entry matching the filter and scope of the search which is not a 516 referral object is returned to the client normally as described in 517 [RFC2251]. 518 519 For each referral object within the requested scope, regardless of 520 the search filter, the server SHOULD return a SearchResultReference 521 which is constructed from the URI component of values of the ref 522 attribute. If the URI component is not a LDAP URL, it should be 523 returned as is. If the LDAP URL's DN part is absent or empty, the DN 524 part must be modified to contain the DN of the referral object. If 525 the URI component is a LDAP URL, the URI SHOULD be modified to add an 526 explicit scope specifier. 527 528 Subtree Example: 529 530 If a client requests a subtree search of "O=MNN,C=WW", then in 531 addition to any entries within scope which match the filter, hosta 532 will also return two search references as the two referral objects 533 are within scope. One possible response might be: 534 535 SearchEntry for O=MNN,C=WW 536 SearchResultReference { 537 ldap://hostb/OU=People,O=MNN,C=WW??sub 538 ldap://hostc/OU=People,O=MNN,C=WW??sub 539 } 540 SearchEntry for CN=Manager,O=MNN,C=WW 541 SearchResultReference { 542 ldap://hostd/OU=Roles,O=MNN,C=WW??sub 543 } 544 SearchResultDone (success) 545 546 One Level Example: 547 548 If a client requests a one level search of "O=MNN,C=WW" then, in 549 addition to any entries one level below the "O=MNN,C=WW" entry 550 matching the filter, the server will also return two search 551 references as the two referral objects are within scope. One 552 possible sequence is shown: 553 554 555 556 557 558 559 560 561 562Zeilenga Standards Track [Page 10] 563 564RFC 3296 Named Subordinate References in LDAP Directories July 2002 565 566 567 SearchResultReference { 568 ldap://hostb/OU=People,O=MNN,C=WW??base 569 ldap://hostc/OU=People,O=MNN,C=WW??base 570 } 571 SearchEntry for CN=Manager,O=MNN,C=WW 572 SearchResultReference { 573 ldap://hostd/OU=Roles,O=MNN,C=WW??base 574 } 575 SearchResultDone (success) 576 577 Note: Unlike the examples in Section 4.5.3.1 of RFC 2251, the LDAP 578 URLs returned with the SearchResultReference messages contain, as 579 required by this specification, an explicit scope specifier. 580 5815.6. Other Considerations 582 583 This section details processing considerations for other operations. 584 5855.6.1 Bind 586 587 Servers SHOULD NOT return referral result code if the bind name (or 588 authentication identity or authorization identity) is (or is 589 subordinate to) a referral object but MAY use the knowledge 590 information to process the bind request (such as in support a future 591 distributed operation specification). Where the server makes no use 592 of the knowledge information, the server processes the request 593 normally as appropriate for a non-existent authentication or 594 authorization identity (e.g., return invalidCredentials). 595 5965.6.2 Modify DN 597 598 If the newSuperior is a referral object or is subordinate to a 599 referral object, the server SHOULD return affectsMultipleDSAs. If 600 the newRDN already exists but is a referral object, the server SHOULD 601 return affectsMultipleDSAs instead of entryAlreadyExists. 602 6036. Security Considerations 604 605 This document defines mechanisms that can be used to tie LDAP (and 606 other) servers together. The information used to tie services 607 together should be protected from unauthorized modification. If the 608 server topology information is not public information, it should be 609 protected from unauthorized disclosure as well. 610 611 612 613 614 615 616 617 618Zeilenga Standards Track [Page 11] 619 620RFC 3296 Named Subordinate References in LDAP Directories July 2002 621 622 6237. Acknowledgments 624 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 629 Mark Wahl. 630 6318. Normative References 632 633 [RFC2079] Smith, M., "Definition of an X.500 Attribute Type and an 634 Object Class to Hold Uniform Resource Identifiers (URIs)", 635 RFC 2079, January 1997. 636 637 [RFC2119] Bradner, S., "Key Words for use in RFCs to Indicate 638 Requirement Levels", BCP 14, RFC 2119, March 1997. 639 640 [RFC2251] Wahl, M., Howes, T. and S. Kille, "Lightweight Directory 641 Access Protocol (v3)", RFC 2251, December 1997. 642 643 [RFC2252] Wahl, M., Coulbeck, A., Howes, T. and S. Kille, 644 "Lightweight Directory Access Protocol (v3): Attribute 645 Syntax Definitions", RFC 2252, December 1997. 646 647 [RFC2253] Wahl, M., Kille, S. and T. Howes, "Lightweight Directory 648 Access Protocol (v3): UTF-8 String Representation of 649 Distinguished Names", RFC 2253, December 1997. 650 651 [RFC2255] Howes, T. and M. Smith, "The LDAP URL Format", RFC 2255, 652 December, 1997. 653 654 [RFC2396] Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform 655 Resource Identifiers (URI): Generic Syntax", RFC 2396, 656 August 1998. 657 658 [X.501] ITU-T, "The Directory: Models", X.501, 1993. 659 6609. Informative References 661 662 [X.500] ITU-T, "The Directory: Overview of Concepts, Models, and 663 Services", X.500, 1993. 664 665 [X.511] ITU-T, "The Directory: Abstract Service Definition", X.500, 666 1997. 667 668 669 670 671 672 673 674Zeilenga Standards Track [Page 12] 675 676RFC 3296 Named Subordinate References in LDAP Directories July 2002 677 678 67910. Author's Address 680 681 Kurt D. Zeilenga 682 OpenLDAP Foundation 683 684 EMail: Kurt@OpenLDAP.org 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730Zeilenga Standards Track [Page 13] 731 732RFC 3296 Named Subordinate References in LDAP Directories July 2002 733 734 73511. Full Copyright Statement 736 737 Copyright (C) The Internet Society (2002). All Rights Reserved. 738 739 This document and translations of it may be copied and furnished to 740 others, and derivative works that comment on or otherwise explain it 741 or assist in its implementation may be prepared, copied, published 742 and distributed, in whole or in part, without restriction of any 743 kind, provided that the above copyright notice and this paragraph are 744 included on all such copies and derivative works. However, this 745 document itself may not be modified in any way, such as by removing 746 the copyright notice or references to the Internet Society or other 747 Internet organizations, except as needed for the purpose of 748 developing Internet standards in which case the procedures for 749 copyrights defined in the Internet Standards process must be 750 followed, or as required to translate it into languages other than 751 English. 752 753 The limited permissions granted above are perpetual and will not be 754 revoked by the Internet Society or its successors or assigns. 755 756 This document and the information contained herein is provided on an 757 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 758 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 759 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 760 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 761 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 762 763Acknowledgement 764 765 Funding for the RFC Editor function is currently provided by the 766 Internet Society. 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786Zeilenga Standards Track [Page 14] 787 788