-IETF LDAPEXT Working Group Christopher Lukas [Editor]
-INTERNET-DRAFT Internet Scout Project
- Tim Howes
- Netscape Communications Corp.
- Michael Roszkowski
- Internet Scout Project
- Mark C. Smith
- Netscape Communications Corp.
- Mark Wahl
- Critial Angle, Inc.
- June 1999
-
-
- Named Referrals in LDAP Directories
- <draft-ietf-ldapext-namedref-00.txt>
-
-
-
-1. 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.
-
-Distribution of this document is unlimited. Please send comments to the
-authors or the LDAPEXT mailing list, ietf-ldapext@netscape.com.
-
-Copyright Notice: Copyright (C) The Internet Society (1999). All Rights
-Reserved.
-
-This draft is a revision of a draft formerly published as draft-ietf-
-ldapext-referral-00.txt.
-
-This draft expires December 6, 1999.
-
-
-
-Howes, et al. IETF LDAPEXT Working Group [Page 1]
-
-
-
-
-
-INTERNET-DRAFT LDAPv3 Named Referrals March 1999
-
-
-2. Abstract
-
-This document defines a "ref" attribute 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.
-
-3. 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 defines a general method of representing knowledge infor-
-mation in LDAP directories, based on URIs.
-
-The key words "MUST", "SHOULD", and "MAY" used in this document are to
-be interpreted as described in [RFC2119].
-
-4. The ref attribute type
-
-This section defines the ref attribute type for holding general
-knowledge reference information.
-
-( 2.16.840.1.113730.3.1.34 NAME 'ref' DESC 'URL reference'
- EQUALITY caseExactIA5Match SYNTAX 1.3.6.1.4.1.1466.115.121.1.26
- USAGE distributedOperation )
-
-The ref attribute type has IA5 syntax and is case sensitive. The ref
-attribute is multivalued. Values placed in the attribute MUST conform to
-the specification given for the labeledURI attribute 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 the ref attribute.
-
-If the URI contained in the ref attribute refers to an LDAPv3 server, it
-must be in the LDAP URI format described in [RFC2255].
-
-
-
-
-Howes, et al. IETF LDAPEXT Working Group [Page 2]
-
-
-
-
-
-INTERNET-DRAFT LDAPv3 Named Referrals March 1999
-
-
-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 ref attribute should be returned.
-
-5. Use of the ref attribute
-
-One usage of the ref attribute is defined in this document. Other uses
-of the ref attribute MAY be defined in subsequent documents, or by bila-
-teral agreement between cooperating clients and servers.
-
-Except when the manageDsaIT control (documented in section 8 of this
-document) is present in the operation request, the ref 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 ref 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 ref 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 ref attribute.
-
-When the manageDsaIT control is present in a request, the server will
-treat an entry containing the ref attribute as an ordinary entry, and
-the ref attribute as an ordinary attribute, and the server will not
-return referrals or continuation references corresponding to ref attri-
-butes.
-
-The following sections detail these usages of the ref attribute.
-
-5.1. Named reference
-
-This use of the ref attribute is to facilitate distributed name resolu-
-tion or search across multiple servers. The ref attribute appears in an
-entry named in the referencing server. The value of the ref attribute
-points to the corresponding entry maintained in the referenced server.
-
-While the distinguished name in a value of the ref attribute is typi-
-cally that of an entry in a naming context below the naming context held
-by the referencing server, it is permitted to be the distinguished name
-of any entry. If the ref attribute is multi-valued all the DNs in the
-values of the ref attribute SHOULD have the same value. It is the
-responsibility of clients to not loop repeatedly if a naming loop is
-present in the directory. Administrators SHOULD avoid configuring
-
-
-
-Howes, et al. IETF LDAPEXT Working Group [Page 3]
-
-
-
-
-
-INTERNET-DRAFT LDAPv3 Named Referrals March 1999
-
-
-naming loops using referrals.
-
-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. Clients MAY perform more sophisticated loop detection, for
-example not chasing the same URI twice.
-
-If an entry containing the ref attribute is immediately subordinate to
-the base object named in a one level search request, then the referring
-server MUST include a scope of "base" in any LDAP URIs returned in the
-corresponding SearchResultReference.
-
-5.1.1. Scenarios
-
-The following sections contain specifications of how the ref attribute
-should be used in different scenarios followed by examples that illus-
-trate that usage. The scenarios described consist of referral operation
-when finding a base or target object, referral operation when performing
-a one level search, and referral operation when performing a subtree
-search.
-
-It is to be noted that, in this document, a search operation is concep-
-tually divided into two distinct, sequential phases: (1) finding the
-base object where the search is to begin, and (2) performing the search
-itself. The operation of the server with respect to referrals in phase
-(1) is almost identical to the operation of the server while finding the
-target object for a non-search operation.
-
-It is to also be noted that multiple ref attributes are allowed in any
-entry and, where these sections refer to a single ref attribute, multi-
-ple ref attributes may be substituted and should be processed and
-returned as a group in an LDAPResult or search result in the same way as
-described for a single attribute. The order of the returned continuation
-references within a result is not defined.
-
-
-5.1.1.1. Example configuration
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Howes, et al. IETF LDAPEXT Working Group [Page 4]
-
-
-
-
-
-INTERNET-DRAFT LDAPv3 Named Referrals March 1999
-
-
- |------------------------------------------------------------|
- | Server A |
- | dn: o=abc,c=us dn: o=xyz,c=us |
- | o: abc o: xyz |
- | ref: ldap://hostB/o=abc,c=us ref: ldap://hostD/o=xyz,c=us |
- | ref: ldap://hostC/o=abc,c=us objectclass: referral |
- | objectclass: referral objectclass: extensibleObject|
- | objectclass: extensibleObject |
- |____________________________________________________________|
-
- |---------------------| |---------------------| |---------------------|
- | Server B | | Server D | | Server C |
- | dn: o=abc,c=us | | dn: o=xyz,c=us | | dn: o=abc,c=us |
- | o: abc | | o: xyz | | o: abc |
- | other attributes... | | other attributes... | | other attributes... |
- |_____________________| |_____________________| |_____________________|
-
-In this example, Server A holds references for two entries: "o=abc,c=us"
-and "o=xyz,c=us". For the "o=abc,c=us" entry, Server A holds two refer-
-ences, one to Server B and one to Server C. The entries referenced are
-replicas of each other. For the "o=xyz,c=us" entry, Server A holds a
-single reference to the entry contained in Server D.
-
-In the following protocol interaction examples, the client has contacted
-Server A. Server A holds the naming context "c=us".
-
-5.1.1.2. Base or target object considerations
-
-As previously described, the process of generating referrals for a
-search can be described in two phases. The first, which is described in
-this section, is generating referrals based on the base object specified
-in the search. This process is identical to the process of generating
-referrals based on the target object while processing other operations
-(modify, add, delete, modify DN, and compare) with the sole exception
-that for these other operations, the DN in the referral must be modified
-in some cases.
-
-If a client requests any of these operations, there are four cases that
-the server must handle with respect to the base or target object speci-
-fied in the request.
-
-Case 1: The base or target object is not held by the server and is not
-subordinate to any object held by the server with a ref attribute.
-
-The handling of this case is described in section 6.
-
-Case 2: The base or target object is held by the server and contains a
-ref attribute
-
-
-
-Howes, et al. IETF LDAPEXT Working Group [Page 5]
-
-
-
-
-
-INTERNET-DRAFT LDAPv3 Named Referrals March 1999
-
-
-In this case, if the type of operation requested is a search or the URI
-contained in the ref attribute of the requested base object is NOT an
-LDAP URI as defined in [RFC2255], the server should return the URI value
-contained in the ref attribute of the base object whose DN is the DN
-requested by the client as the base for the operation.
-
-Example:
-
-If the client issues a search in which the base object is "o=xyz,c=us",
-server A will return
-
- SearchResultDone "referral" {
- ldap://hostD/o=xyz,c=us
- }
-
-If the type of operation requested is not a search and the URI contained
-in the ref attribute of the requested target object is an LDAP URI
-[RFC2255], the server should return a modified form of this URL. The
-returned URL must have only the protocol, host, port, and trailing "/"
-portion of the URL contained in the ref attribute. The server should
-strip any dn, attributes, scope, and filter parts of the URL.
-
-Example:
-
-If the client issues a modify request for the target object of
-"o=abc,c=us", server A will return
-
- ModifyResponse "referral" {
- ldap://hostB/
- ldap://hostC/
- }
-
-Case 3: The base or target object is not held by the server, but is
-subordinate to an object with a ref attribute held by the server.
-
-
-If a client requests an operation for which the base or target object is
-not held by the server, but is subordinate to one or more objects with a
-ref attribute held by the server, the server must return the referral
-from the superior held object nearest to the requested base or target
-object. Nearest superior object with a referral, in this document, means
-an object superior to the base or target object with the DN that has the
-most attribute values in common with the DN of the base or target object
-and contains a ref attribute.
-
-The process of finding the nearest superior object can be envisioned as
-walking up the locally held part of the DIT from the requested base or
-target object checking each superior object until either an object with
-
-
-
-Howes, et al. IETF LDAPEXT Working Group [Page 6]
-
-
-
-
-
-INTERNET-DRAFT LDAPv3 Named Referrals March 1999
-
-
-a ref attribute is found or the top-most locally held object is reached.
-Once possible implementation of this algorithm is as follows:
-
- 1. Remove the leftmost attribute/value pair from the DN of the
- requested base or target object.
- 2. If the remaining DN represents a locally held object that contains
- a ref attribute, that object is the nearest superior object with a
- referral. Stop and process the referral as described below.
- 3. If the remaining DN is the root of the locally held part of the
- DIT, stop and proceed as described in section 6.
- 4. Continue with step 1.
-
-Once the nearest superior object has been identified, if the referral
-contained in that object is not an LDAP URI [RFC2255], it should be
-returned as-is. If the referral is an LDAP URI, the referral must be
-modified, regardless of the type of operation, as case 2 describes for a
-non-search requuest. That is, the dn, attributes, scope, and filter
-parts of the URL must be stripped from the referral and the referral
-returned.
-
-Example:
-
-If the client issues an add request where the target object has a DN of
-"cn=Chris Lukas,o=abc,c=us", server A will return
-
- AddResponse "referral" {
- ldap://hostB/
- ldap://hostC/
- }
-
-
-
-
-5.1.1.3. Search with one level scope
-
-For search operations, once the base object has been found and deter-
-mined not to contain a ref attribute, the search may progress. Any
-entries matching the filter and scope of the search that do NOT contain
-a ref attribute are returned to the client normally as described in
-[RFC2251]. Any entries matching the filter and one level scope that do
-contain a ref attribute must be returned as referrals as described here.
-
-If a matching entry contains a ref attribute and the URI contained in
-the ref attribute is NOT an LDAP URI [RFC2255], the server should return
-the URI value contained in the ref attribute of that entry in a Sear-
-chResultReference.
-
-If a matching entry contains a ref attribute in the LDAP URI syntax
-
-
-
-Howes, et al. IETF LDAPEXT Working Group [Page 7]
-
-
-
-
-
-INTERNET-DRAFT LDAPv3 Named Referrals March 1999
-
-
-[RFC2255], the URL from the ref 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.
-
-Example:
-
-If a client requests a one level search of "c=US" then, in addition to
-any entries one level below the "c=US" naming context matching the
-filter (shown below as "... SearchResultEntry responses ..."), the
-server will also return referrals modified to include the "base" scope
-to maintain the one level search semantics.
-
-The order of the SearchResultEntry responses and the SearchResultRefer-
-ence responses is undefined. One possible sequence is shown.
-
- ... SearchResultEntry responses ...
-
- SearchResultReference {
- ldap://hostB/o=abc,c=us??base
- ldap://hostC/o=abc,c=us??base
- }
-
- SearchResultReference {
- ldap://hostD/o=xyz,c=us??base
- }
-
- SearchResultDone "success"
-
-
-5.1.1.4. Search with subtree scope
-
-For a search operation with a subtree scope, once the base object has
-been found, the search progresses. As with the one level search, any
-entries matching the filter and scope of the search that do NOT contain
-a ref attribute are returned to the client normally as described in
-[RFC2251].
-
-If an entry matching the requested scope and filter contains a ref
-attribute, the server should return the URI value in a SearchResul-
-tReference.
-
-Example:
-
-If a client requests a subtree search of "c=us", then in addition to any
-entries in the "c=us" naming context which match the filter, Server A
-will also return two continuation references. As described in the
-
-
-
-Howes, et al. IETF LDAPEXT Working Group [Page 8]
-
-
-
-
-
-INTERNET-DRAFT LDAPv3 Named Referrals March 1999
-
-
-preceding section, the order of the responses is not defined.
-
-One possible response might be:
-
- ... SearchResultEntry responses ...
-
- SearchResultReference {
- ldap://hostB/o=abc,c=us
- ldap://hostC/o=abc,c=us
- }
-
- SearchResultReference {
- ldap://hostD/o=xyz,c=us
- }
-
- SearchResultDone "success"
-
-
-6. Superior Reference
-
-An LDAP server may be configured to return a superior reference in the
-case where the server does not hold either the requested base object or
-an object containing a ref attribute that is superior to that base
-object.
-
-An LDAP server's root DSE MAY contain a ref attribute. The values of the
-ref attribute in the root DSE that are LDAP URIs SHOULD NOT contain any
-dn part, just the host name and optional port number.
-
-If the LDAP server's root DSE contains a ref attribute and a client
-requests an object not held by the server and not subordinate to any
-held object, the server must return the URI component of the values in
-the ref attribute of the root DSE as illustrated in the example.
-
-If the LDAP server's root DSE does not contain a ref attribute, the
-server may return one or more references that the server determines via
-a method not defined in this document to be appropriate.
-
-The default reference may be to any server that might contain more
-knowledge of the namespace than the responding server. In particular,
-the client must not expect the superior reference to be identical from
-session to session as the reference may be dynamically created by the
-server based on the details of the query submitted by the client.
-
-When the server receives an operation for which the base or target entry
-of the request is not contained in or subordinate to any naming context
-held by the server or a referral entry, the server will return an
-LDAPResult with the resultCode set to "referral", and with the referral
-
-
-
-Howes, et al. IETF LDAPEXT Working Group [Page 9]
-
-
-
-
-
-INTERNET-DRAFT LDAPv3 Named Referrals March 1999
-
-
-field filled with a referral that the server has determined to be
-appropriate.
-
-Example:
-
-If a client requests a subtree search of "c=de" from server A in the
-example configuration, and server A has the following ref attribute
-defined in it's root DSE:
-
- ref: ldap://hostG/
-
-then server A will return
-
- SearchResultDone "referral" {
- ldap://hostG/
- }
-
-
-7. The referral object class
-
-The referral object class is defined as follows.
-
-( 2.16.840.1.113730.3.2.6 NAME 'referral' SUP top STRUCTURAL
- MAY ( ref ) )
-
-The referral object class is a subclass of top and may contain the
-referral 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 ref attribute 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.
-
-8. The manageDsaIT control
-
-A client MAY specify the following control when issuing a search, com-
-pare, add, delete, modify, or modifyDN request or an extended operation
-for which the control is defined.
-
-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 "ref" attribute to be treated as
-normal entries, allowing clients to read and modify these entries.
-
-
-
-
-Howes, et al. IETF LDAPEXT Working Group [Page 10]
-
-
-
-
-
-INTERNET-DRAFT LDAPv3 Named Referrals March 1999
-
-
-This control is not needed if the entry containing the referral attri-
-bute is one used for directory administrative purposes, such as the root
-DSE, or the server change log entries. Operations on these entries
-never cause referrals or continuation references to be returned.
-
-9. Relationship to X.500 Knowledge References
-
-The X.500 standard defines several types of knowledge references, used
-to bind together different parts of the X.500 namespace. In X.500,
-knowledge references can be associated with a set of unnamed entries
-(e.g., a reference, associated with an entry, to a server containing the
-descendants of that entry).
-
-This creates a potential problem for LDAP clients resolving an LDAPv3
-URL referral referring to an LDAP directory back-ended by X.500. Sup-
-pose the search is a subtree search, and that server A holds the base
-object of the search, and server B holds the descendants of the base
-object. The behavior of X.500(1993) subordinate references is that the
-base object on server A is searched, and a single continuation reference
-is returned pointing to all of the descendants held on server B.
-
-An LDAP URI only allows the base object to be specified. It is not pos-
-sible using standard LDAP URIs to indicate a search of several entries
-whose names are not known to the server holding the superior entry.
-
-X.500 solves this problem by having two fields, one indicating the pro-
-gress of name resolution and the other indicating the target of the
-search. In the above example, name resolution would be complete by the
-time the query reached server B, indicating that it should not refer the
-request.
-
-This document does not address this problem. This problem will be
-addressed in separate documents which define the changes to the X.500
-distribution model and LDAPv3 extensions to indicate the progress of
-name resolution.
-
-10. 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 infor-
-mation should be protected from unauthorized access as well.
-
-Clients should use caution when re-using credentials while following
-referrals as the client may be directed to any server which may or may
-not respect or use those credentials appropriately.
-
-
-
-
-Howes, et al. IETF LDAPEXT Working Group [Page 11]
-
-
-
-
-
-INTERNET-DRAFT LDAPv3 Named Referrals March 1999
-
-
-11. 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.
-
-[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.
-
-[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.
-
-12. Author's Address
-
-Tim Howes
-Netscape Communications Corp.
-501 E. Middlefield Rd.
-Mailstop MV068
-Mountain View, CA 94043
-USA
-+1 650 937-3419
-EMail: howes@netscape.com
-
-Christopher E. Lukas
-Internet Scout Project
-Computer Sciences Dept.
-University of Wisconsin-Madison
-1210 W. Dayton St.
-Madison, WI 53706
-USA
-EMail: lukas@cs.wisc.edu
-
-
-
-
-Howes, et al. IETF LDAPEXT Working Group [Page 12]
-
-
-
-
-
-INTERNET-DRAFT LDAPv3 Named Referrals March 1999
-
-
-Michael Roszkowski
-Internet Scout Project
-Computer Sciences Dept.
-University of Wisconsin-Madison
-1210 W. Dayton St.
-Madison, WI 53706
-USA
-EMail: mfr@cs.wisc.edu
-
-Mark C. Smith
-Netscape Communications Corp.
-501 E. Middlefield Rd.
-Mailstop MV068
-Mountain View, CA 94043
-USA
-EMail: mcs@netscape.com
-
-Mark Wahl
-Innosoft International, Inc.
-8911 Capital of Texas Hwy #4140
-Austin TX 78759
-EMail: M.Wahl@innosoft.com
-
-
-This draft expires December 6, 1999.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Howes, et al. IETF LDAPEXT Working Group [Page 13]
-
-