IETF LDAPEXT Working Group Roland Hedberg Internet-Draft Catalogix Expires: January 12, 2000 July 12, 2000 Referrals in LDAP Directories Status of this Memo This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. This Internet-Draft will expire on January 12, 2000. Copyright Notice Copyright (C) The Internet Society (2000). All Rights Reserved. Hedberg Expires September 30, 2000 [Page 1] Internet-Draft LDAP Knowledge references July 2000 Abstract This document defines two reference attributes and associated "referral" object class for representing generic knowledge information in LDAP directories [RFC2251]. The attribute uses URIs [RFC1738] to represent knowledge, enabling LDAP and non-LDAP services alike to be referenced. The object class can be used to construct entries in an LDAP directory containing references to other directories or services. This document also defines procedures directory servers should follow when supporting these schema elements and when responding to requests for which the directory server does not contain the requested object but may contain some knowledge of the location of the requested object. 1. Background and intended usage The broadening of interest in LDAP directories beyond their use as front ends to X.500 directories has created a need to represent knowledge information in a more general way. Knowledge information is information about one or more servers maintained in another server, used to link servers and services together. This document is based on the following basic assumptions: - several naming domains The usage of LDAP as a access protocol to other than X.500 servers has created islands of directory service systems containing one or more LDAP servers. Each of these islands are free to pick their own naming domain. And that they also do; some use the old country,organization, organizationalUnit naming scheme[X.521], some use the newer domain name based naming scheme but these two are in no way the only ones in use. The existence of several naming domains are in itself no real problem as long as they produce unique names for the objects in the directory. Still naming schemes like the domain name based one, might easily create non-continues naming structures because some toplevel domain names might no find organizations that are interested and/or willing to manage them. Therefor tree transversal might not longer be possible except in parts of the whole tree. - authoritive structure vs directory structure In some instances even if a part of the tree is delegated to one organization, the organization doing the delegation might want to remain as the authority for the baseobject of the delegated tree. - support for onelevel searches At points in the tree where the responsibility for all or almost all of the children of a object is delegated to different organizations and resides in different directory servers a one-level search is not very efficient if not supported by special facilities in the directory as such. Hedberg Expires September 30, 2000 [Page 2] Internet-Draft LDAP Knowledge references July 2000 -- directory server discovery LDAP servers that do not use dc nameing or are not registered with SRV records in the DNS are very hard to find. This document defines a general method of representing knowledge information in LDAP directories, based on URIs. Two types of knowledge reference are defined: refer and subRefer. The key words "MUST", "SHOULD", and "MAY" used in this document are to be interpreted as described in [RFC2119]. 2. Knowledge references 2.1 The refer attribute ( 1.2.752.17.1.100 NAME 'refer' DESC 'URL reference' EQUALITY caseExactIA5Match SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 USAGE distributedOperation ) The refer attribute type has IA5 syntax and is case sensitive. It is multivalued. Values placed in the attribute MUST conform to the specification given for the labeledURI attribute as defined in [RFC2079]. The labeledURI specification defines a format that is a URI, optionally followed by whitespace and a label. This document does not make use of the label portion of the syntax. Future documents MAY enable new functionality by imposing additional structure on the label portion of the syntax as it appears in a refer attribute. If the URI contained in a refer attribute refers to an LDAP server, it must be in the LDAP URI format described in [RFC2255]. When returning a referral result, the server must not return the label portion of the labeledURI as part of the referral. Only the URI portion of the refer attributes should be returned. The refer attribute can be further specified by the use of options as defined in section 4.1.5 of [RFC2251]. This document defines five options and their use. Future documents might defined other options. The options defined are: "me", "sup", "cross", "nssr" and "sub" . 'refer;me' is used to hold the reference of this server, and is always held in the root DSE 'refer;sup' is used to hold the reference of a server superior to this one in this global LDAP naming domain e.g. a server holding the dc=com, dc=se, or the c=se node. The 'refer;sup' is always held in the root DSE. Hedberg Expires September 30, 2000 [Page 3] Internet-Draft LDAP Knowledge references July 2000 'refer;cross' indicates that this is a cross reference pointing to another naming context within or outside this global LDAP naming domain. 'refer;sub' indicates that this is a subordinate reference pointing to a subordinate naming context in this global LDAP naming domain. 'refer;nssr' indicates that this is a non-specific subordinate reference pointing to a subordinate naming context in this global LDAP naming domain. 3. Use of the knowledge attribute Except when the manageDsaIT control (documented in section 6 of this document) is present in the operation request, the refer attribute is not visible to clients, except as its value is returned in referrals or con- tinuation references. If the manageDsaIT control is not set, and the entry named in a request contains the refer attribute, and the entry is not the root DSE, the server returns an LDAPResult with the resultCode field set to "referral" and the referral field set to contain the value(s) of the refer attribute minus any optional trailing whitespace and labels that might be present. If the manageDsaIT control is not set, and an entry containing the ref attribute is in the scope of a one level or subtree search request, the server returns a SearchResultReference for each such entry containing the value(s) of the entry's refer attribute. When the manageDsaIT control is present in a request, the server will treat an entry containing the refer attribute as an ordinary entry, and the refer attribute as an ordinary attribute, and the server will not return referrals or continuation references corresponding to refer attributes. 4 Behaviour specification 4.1 Name resolution for any operation Clients SHOULD perform at least simple "depth-of-referral count" loop detection by incrementing a counter each time a new set of referrals is received. (The maximum value for this count SHOULD be twice the number of RDNs in the target object less one, to allow for ascending and descending the DIT.) Clients MAY perform more sophisticated loop detection, for example not chasing the same referral twice. Case 1: The target entry is not held by the server and is superior to some entry held by the server. If the server DSE contains a "refer;sup" attribute then the server will return an LDAPResult with the result code field set Hedberg Expires September 30, 2000 [Page 4] Internet-Draft LDAP Knowledge references July 2000 to referral, and the referral field set to contain the value(s) of the "refer;sup" attribute minus any optional trailing whitespace and labels that might be present. Case 2: The target entry is not held by the server and is subordinate to some entry, held by the server, that contains a refer attribute. The server will return an LDAPResult with the result code field set to referral, and the referral field set to contain the value(s) of the refer attribute minus any optional trailing whitespace and labels that might be present. Case 3: The target entry is held by the server and contains a refer attribute without the 'nssr' option. The server will return an LDAPResult with the result code field set to referral, and the referral field set to contain the value(s) of the refer attribute minus any optional trailing whitespace and labels that might be present. Case 4: The target entry is not held by the server, and is not subordinate or superior to any object held by the server. If the server contains a "refer;cross" attribute in the root DSE with a baseobject that is either the same or superior to the target entry then the server will return an LDAPResult with the result code field set to referral, and the referral field set to contain the value(s) of these refer attributes minus any optional trailing whitespace and labels that might be present. 4.2 Search evaluation For search operations, once the base object has been found and determined NOT to contain a refer attribute without the 'nssr' option, the search may progress. 4.2.1 base-level If the entry matches the filter and does NOT contain a refer attribute it will be returned to the client as described in [RFC2251]. If the entry matches the filter contains a refer attribute without the 'nssr' option it will be returned as a referral as described here. If a matching entry contains a refer attribute and the URI contained in the refer attribute is NOT an LDAP URI [RFC2255], the server should return the URI value contained in the refer attribute of that entry in a SearchResultReference. Hedberg Expires September 30, 2000 [Page 5] Internet-Draft LDAP Knowledge references July 2000 If a matching entry contains a refer attribute in the LDAP URI syntax, the server will return an SearchResultReference containing the value(s) of the refer attribute minus any optional trailing whitespace and labels that might be present. The URL from the refer attribute must be modified before it is returned by adding or substituting a "base" scope into the URL. If the URL does not contain a scope specifier, the "base" scope specifier must be added. If the URL does contain a scope specifier, the existing scope specifier must be replaced by the "base" scope. 4.2.2 One-level Any entries matching the filter and one level scope that do NOT contain a refer attribute are returned to the client normally as described in [RFC2251]. Any entries matching the filter and one level scope that contains a refer attribute without the 'nssr' option must be returned as referrals as described here. If a matching entry contains a refer attribute and the URI contained in the refer attribute is NOT an LDAP URI [RFC2255], the server should return the URI value contained in the refer attribute of that entry in a SearchResultReference. If a matching entry contains a refer attribute in the LDAP URI syntax, the server will return an SearchResultReference containing the value(s) of the refer attribute minus any optional trailing whitespace and labels that might be present. The URL from the refer attribute must be modified before it is returned by adding or substituting a "base" scope into the URL. If the URL does not contain a scope specifier, the "base" scope specifier must be added. If the URL does contain a scope specifier, the existing scope specifier must be replaced by the "base" scope. 4.2.3 Subtree search evaluation Any entries, held by the server, matching the filter and subtree scope that do NOT contain a refer attribute or contains a refer attribute with the 'nssr' option are returned to the client normally as described in [RFC2251]. Any entries matching the subtree scope and containing a refer attribute must be returned as referrals as described here. If a matching entry contains a refer attribute and the URI contained in that attribute is NOT an LDAP URI [RFC2255], the server should return the URI value contained in the refer attribute of that entry in a SearchResultReference. Hedberg Expires September 30, 2000 [Page 6] Internet-Draft LDAP Knowledge references July 2000 If a matching entry contains a refer attribute in the LDAP URI syntax, the server will return an SearchResultReference containing the value(s) of the refer attribute minus any optional trailing whitespace and labels that might be present. N.B. in subtree search evaluation a entry containing a refer attribut with the 'nssr' option might appear twice in the result, first as a entry and then as a reference. A client following all references might therefore end up with a resultset containing two representations of the same entry, one from the server getting the original query and one from the server that the 'nssr' reference points to. 5. The referral object class The referral object class is defined as follows. ( 1.2.752.17.2.10 NAME 'referral' SUP top STRUCTURAL MAY ( refer ) ) The referral object class is a subclass of top and may contain the refer attribute. The referral object class should, in general, be used in conjunction with the extensibleObject object class to support the naming attributes used in the entry's distinguished name. Servers must support the refer attributes through use of the referral object class. Any named reference must be of the referral object class and will likely also be of the extensibleObject object class to support naming and use of other attributes. 6. The manageDsaIT control A client MAY specify the following control when issuing a search, com- pare, add, delete, modify, or modifyDN request. The control type is 2.16.840.1.113730.3.4.2. The control SHOULD be marked as critical. There is no value; the controlValue field is absent. This control causes entries with the knowledge reference attributes to be treated as normal entries, allowing clients to read and modify these entries. Hedberg Expires September 30, 2000 [Page 7] Internet-Draft LDAP Knowledge references July 2000 7. Superior Reference This document defines two types of knowledge references that point to parts of the naming context that is above of beyone the part held by a server. The 'sup' option when referring to a LDAP server that holds a naming context that is closer to the root of the same naming context and 'other' when referring to a LDAP server that holds a naming context that belongs to a different naming domain then the one the server belongs to. Thus if the server receives a request for an operation where the target entry is a entry closer to the root than the naming context held the server and if the server holds a 'refer;sup' attribute in the DSE, then the server MUST return an LDAPResult with the result code field set to referral, and the referral field set to contain the value(s) of the 'refer;sub' attribute minus any optional trailing whitespace and labels that might be present. On the other hand if the server receives a request for an operation where the target entry is a entry that belongs to a other naming domain and if there is any 'refer;other' attributes in the DSE with a base entry that belongs to the same naming domain as the target entry and is closer to the root then the target entry, then the server SHOULD return an LDAPResult with the result code field set to referral, and the referral field set to contain the value(s) of the 'refer;other' attribute minus any optional trailing hitespace and labels that might be present. 8. Security Considerations This document defines mechanisms that can be used to "glue" LDAP (and other) servers together. The information used to specify this glue information should be protected from unauthorized modification. If the server topology information itself is not public information, the information should be protected from unauthorized access as well. 9. References [RFC1738] Berners-Lee, T., Masinter, L., and McCahill, M., "Uniform Resource Locators (URL)", RFC 1738, CERN, Xerox Corporation, University of Minnesota, December 1994, [RFC2079] M. Smith, "Definition of an X.500 Attribute Type and an Object Class to Hold Uniform Resource Identifiers (URIs)", RFC 2079, January 1997. Hedberg Expires September 30, 2000 [Page 8] Internet-Draft LDAP Knowledge references July 2000 [RFC2119] S. Bradner, "Key Words for use in RFCs to Indicate Requirement Lev- els", RFC 2119, March 1997. (Format: TXT=4723 bytes) (Also BCP0014) (Status: BEST CURRENT PRACTICE) [RFC2251] M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access Protocol (v3)", RFC 2251, December 1997. 1997. [RFC2255] T. Howes, M. Smith, "The LDAP URL Format", RFC 2255, December, 1997. (Format: TXT=20685 bytes) (Status: PROPOSED STANDARD) [X500] ITU-T Rec. X.501, "The Directory: Models", 1993. [X521] ITU-T Rec. X.521, "---------------------", 1993. 12. Acknowledgements This draft is heavily based on the previous drafts on knowledge references in LDAP written by Christopher Lukas, Tim Howes, Michael Roszkowski, Mark C. Smith, Mark Wahl and David Chadwick. Peter Valkenburg and Henny Bekker has also made valueable contributions. 13. Authors Address Roland Hedberg Catalogix Dalsveien 53 0775 Oslo Norway EMail: Roland@catalogix.se Hedberg Expires September 30, 2000 [Page 9] Internet-Draft LDAP Knowledge references July 2000 Appendix A Example of usage. Information stored in a server. dn: objectclass: referral refer;me: ldap://hostCAT/dc=cat,dc=se refer;sup: ldap://hostSE/dc=se refer;cross: ldap://hostNO/dc=no refer;cross: ldap://hostNL/c=nl dn: dc=cat,dc=se objectclass: domain dc: cat dn: dc=one,dc=cat,dc=se objectclass: extendedObject objectclass: referral refer;nssr: ldap://hostCAT1/dc=one,dc=cat,dc=se ou: one l: umea dc: dc=two,dc=cat,dc=se objectclass: referral objectclass: extendedObject refer;sub: ldap://hostCAT2/dc=two,dc=cat,dc=se dn: dc=three,dc=cat,dc=se objectclass: referral objectclass: extendedObject refer;cross: ldap://hostCAT3/dc=cat,dc=nl dc: dc=four,dc=cat,dc=se objectclass: domain objectclass: extendedObject ou: four l: umea Hedberg Expires September 30, 2000 [Page 10] Internet-Draft LDAP Knowledge references July 2000 ========================================== A number of descriptive cases ========================================== case 1: One-level search, target object on the server search baseobject: dc=cat,dc=se scope: onelevel filter: (objectclass=*) attributes: ou returns searchResultEntry { dn: dc=one,dc=cat,dc=se ou: one } searchResultReference { ldapurl: ldap://hostCAT2/dc=two,dc=cat,dc=se } searchResultReference { ldapurl: ldap://hostCAT3/dc=cat,dc=nl } searchResultEntry { dn: dc=four,dc=cat,dc=se ou: four } searchResultDone { resultCode: success } case 2: Subtree search, target object on the server search baseobject: dc=cat,dc=se scope: subtree filter: (objectclass=*) attributes: ou returns searchResultEntry { dn: dc=one,dc=cat,dc=se ou: one } searchResultReference { ldapurl: ldap://hostCAT1/dc=one,dc=cat,dc=se } searchResultReference { ldapurl: ldap://hostCAT2/dc=two,dc=cat,dc=se } Hedberg Expires September 30, 2000 [Page 11] Internet-Draft LDAP Knowledge references July 2000 searchResultReference { ldapurl: ldap://hostCAT3/dc=cat,dc=nl } searchResultEntry { dn: dc=four,dc=cat,dc=se ou: four } searchResultDone { resultCode: success } case 3: base search, target entry contains a 'refer;nssr' attribute search baseobject: dc=one,dc=cat,dc=se scope: base filter: (objectclass=*) attributes: ou returns searchResultEntry { dn: dc=one,dc=cat,dc=se ou: four } searchResultDone { resultCode: success } case 4: base search, target entry contains a 'refer;sub' attribute search baseobject: dc=two,dc=cat,dc=se scope: base filter: (objectclass=*) attributes: ou returns searchResultDone { resultCode: referral matchedDN: dc=two,dc=cat,dc=se referral: ldap://hostCAT2/dc=two,dc=cat,dc=se } Hedberg Expires September 30, 2000 [Page 12] Internet-Draft LDAP Knowledge references July 2000 case 5: one-level search, target entry contains a 'refer;nssr' attribute search baseobject: dc=one,dc=cat,dc=se scope: onelevel filter: (objectclass=*) attributes: ou searchResultDone { resultCode: referral matchedDN: dc=one,dc=cat,dc=se referral: ldap://hostCAT1/dc=one,dc=cat,dc=nu } case 6: Search on area above the baseobject of the server search baseobject: dc=pi,dc=se scope: subtree filter: (objectclass=*) attributes: ou returns searchResultDone { resultCode: referral matchedDN: dc=se referral: ldap://hostSE/dc=se } case 7: Search on area beyond, but not below the baseobject of the server search baseobject: o=surfnet,c=nl scope: base filter: (objectclass=*) returns searchResultDone { resultCode: referral matchedDN: c=nl referral: ldap://hostNL/c=NL } Hedberg Expires September 30, 2000 [Page 13]