INTERNET-DRAFT Editor: Kurt D. Zeilenga
Intended Category: Standard Track OpenLDAP Foundation
Expires: 25 August 2001 25 February 2001
Named Subordinate References in LDAP Directories
<draft-zeilenga-ldap-namedref-03.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.
This document is intended to be, after appropriate review and
revision, submitted to the RFC Editor as a Standard Track document.
Distribution of this memo is unlimited. Technical discussion of this
document will take place on the IETF LDAP Extension Working Group
mailing list <ietf-ldapext@netscape.com>. Please send editorial
comments directly to the author <Kurt@OpenLDAP.org>.
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.
Copyright 2001, The Internet Society. All Rights Reserved.
Please see the Copyright section near the end of this document for
more information.
2. Abstract
This document details schema and protocol elements for representing
and manipulating named subordinate references in LDAP [RFC2251]
directories. A referral object is used to hold references at
subordinate delegation points in the directory. These referral
objects hold one or more URIs [RFC2396] contained in values of the ref
attribute type. A control, ManageDsaIT, is defined to allow
manipulation of referral objects as normal objects.
Zeilenga LDAP NamedRef [Page 1]
INTERNET-DRAFT draft-zeilenga-ldap-namedref-03 25 February 2001
3. Background and Intended Usage
The broadening of interest in LDAP directories beyond their use as
front ends to X.500 [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 specific method of representing subordinate
knowledge references in LDAP directories. Other forms of knowledge
information are not detailed by this document. These forms may be
described in subsequent documents.
This document details subordinate referral processing requirements for
servers. This document does not describe protocol syntax and
semantics. This is detailed in RFC 2251 [RFC2251].
The key words "SHALL", "SHALL NOT", "MUST", "MUST NOT", "SHOULD",
"SHOULD NOT", "MAY" and "MAY NOT" used in this document are to be
interpreted as described in [RFC2119].
4. Schema
The schema definitions are defined in terms of RFC 2252 [RFC2252].
4.1. The referral Object Class
A referral object is a directory entry whose structural object class
is (or is derived from) the referral object class.
( 2.16.840.1.113730.3.2.6
NAME 'referral'
DESC 'named subordinate reference object'
STRUCTURAL
MUST ref )
The referral object class is a structural object class used to
represent a named reference in the directory. The referral object
class SHOULD be used in conjunction with the extensibleObject object
class to support the naming attributes used in the entry's
Distinguished Name (DN) [RFC2253]. Referral objects are directory
entries whose structural object class is (or is derived from)
referral.
Referral objects SHOULD only be instantiated at the subordinate
delegation points.
Zeilenga LDAP NamedRef [Page 2]
INTERNET-DRAFT draft-zeilenga-ldap-namedref-03 25 February 2001
In the presence of a ManageDsaIT control, referral objects are treated
as normal entries (as described in section 5). Note that the ref
attribute is operational and will only returned in a search entry
response when requested.
In the absence of a ManageDsaIT control, the content of referral
objects are used to construct referrals and search references (as
described in section 6) and, as such, the referral entries are not
themselves visible to clients.
4.2 The ref Attribute Type
( 2.16.840.1.113730.3.1.34
NAME 'ref'
DESC 'named reference - a labeledURI'
EQUALITY caseExactMatch
SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
USAGE distributedOperation )
The ref attribute type has directoryString syntax and is case
sensitive. The ref attribute is multi-valued. Values placed in the
attribute MUST conform to the specification given for the labeledURI
attribute [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 a ref attribute value refers to a LDAP
[RFC2251] server, it MUST be a in the form of a LDAP URL [RFC2255].
In general, the LDAP URL should not contain an explicit scope
specifier, filter, attribute description list, or any extensions. If
the DN part is absent (or empty), the LDAP URL refers to entry of the
same DN as the referral object in which the value is held.
Other URI schemes MAY be used but MUST refer to services which are
capable of completing operations referred to the services. All URIs
contained in a ref attribute MUST point to services which are equally
capable of handling operations referring to these services.
The referential integrity of the URI SHALL NOT be validated by the
server holding or returning the URI (whether as part of the value of
the attribute or as part of a referral result or search reference
response).
When returning a referral result or search continuation, the server
Zeilenga LDAP NamedRef [Page 3]
INTERNET-DRAFT draft-zeilenga-ldap-namedref-03 25 February 2001
MUST NOT return the separator or label portions of the attribute
values as part of the reference. When the attribute contains multiple
values, the URI part of each value is used to construct the referral
result or search continuation.
The ref attribute values SHOULD NOT be used as an relative naming
component of an entry's DN [RFC2253].
This documents use of the ref attribute in conjunction with the
referral object class to represent subordinate reference. The ref
attribute may be used for other purposes as defined by other
documents.
5. The ManageDsaIT Control
The client MAY provide the ManageDsaIT control with an operation to
indicates that the operation is intended to manage objects with the
DSA (server) Information Tree. The control causes Directory-specific
entries (DSEs), regardless of type, to be treated as normal entries
allowing clients to interrogate and update these entries using LDAP
operations. This control is analogous to the ManageDsaIT option
described in X.511 [X.511].
A client MAY specify the following control when issuing an add,
compare, delete, modify, modifyDN, search 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 criticality
may be TRUE or, if FALSE, absent. The control value is absent.
When the control is present in the request, the server SHALL NOT
generate a referral or continuation reference for any referral object
and instead perform treat the referral object as an normal entry.
When not present, referral objects SHALL be handled as described
above.
The control MAY cause other objects to be treated as normal entries as
defined by subsequent documents.
6. Named Subordinate References
A named subordinate reference is constructed by instantiating a
referral object at the delegation point in the referencing server with
ref attribute values which to point to the corresponding subtree
maintained in the referenced server.
Zeilenga LDAP NamedRef [Page 4]
INTERNET-DRAFT draft-zeilenga-ldap-namedref-03 25 February 2001
That is, if server A holds "DC=example,DC=net" and server B holds
"DC=sub,DC=example,DC=net", server A may contain a referral object
named "OU=sub,DC=example,DC=net" which contains a ref attribute with
value of "ldap://B/DC=sub,DC=example,DC=net".
dn: DC=sub,DC=example,DC=net
dc: sub
ref: ldap://B/DC=sub,DC=example,DC=net
objectClass: referral
objectClass: extensibleObject
While typically the DN of the referral object and the DN of the object
in the referenced server are the same, they need not be the same. If
they are the same, the DN part of the LDAP URL MAY be absent. That
is, in the above example, the ref attribute with the value of
"ldap://B/" is equivalent to "ldap://B/DC=sub,DC=example,DC=net".
If the ref attribute has multiple values, all the DNs contained (or
implied) by LDAP URL SHOULD have the same. Administrators SHOULD
avoid configuring naming loops using referrals.
Named references MUST be treated as normal entries if the request
includes the ManageDsaIT control as described in section 5.
7. Scenarios
The following sections contain specifications of how referral objects
should be used in different scenarios followed by examples that
illustrate that usage. The scenarios described consist of referral
operation when finding target of a non-search operation, when finding
the base of a search operation, and when generating search references.
Lastly, other operation processing considerations are presented.
It is to be noted that, in this document, a search operation is
conceptually divided into two distinct, sequential phases: (1) finding
the base object where the search is to begin, and (2) performing the
search itself. The first phase is similar to, but not the same as,
finding the target of a non-search operation.
It should also be noted that the ref attribute may have multiple
values and, where these sections refer to a single ref attribute
value, multiple ref attribute values may be substituted and SHOULD be
processed and returned (in any order) as a group in a referral or
search reference in the same way as described for a single ref
attribute value.
Search references returned for a given request may be returned in any
Zeilenga LDAP NamedRef [Page 5]
INTERNET-DRAFT draft-zeilenga-ldap-namedref-03 25 February 2001
order.
7.1. Example Configuration
For example, suppose the contacted server (hosta) holds the entry
"O=MNN,C=WW" and the entry "CN=Manager,O=MNN,C=WW" and the following
referral objects:
dn: OU=People,O=MNN,C=WW
ou: People
ref: ldap://hostb/OU=People,O=MNN,C=US
ref: ldap://hostc/OU=People,O=MNN,C=US
objectClass: referral
objectClass: extensibleObject
dn: OU=Roles,O=MNN,C=WW
ou: Roles
ref: ldap://hostd/
objectClass: referral
objectClass: extensibleObject
The first referral object provides the server with the knowledge that
subtree "OU=People,O=MNN,C=WW" is held by hostb and hostc (one is the
master and the other a shadow). The second referral object provides
the server with the knowledge that the subtree "OU=Roles,O=MNN,C=WW"
is held by hostd.
Also, in the context of this document, the "nearest naming context"
means the deepest context which the object is within. That is, if the
object is within multiple naming contexts, the nearest naming context
is the one which is subordinate to all other naming contexts the
object is within.
7.2. Target object considerations
This section details referral handling to add, compare, delete,
modify, and modify DN operations. If the client requests any of these
operations, there are four cases that the server must handle with
respect to the target object.
In cases where the URI to be returned is a LDAP URL, the server SHOULD
trim any present search-specific parts (e.g. scope, filter, attribute
list) from the URI before return it. Critical extensions MUST NOT be
trimmed nor modified. Other parts MAY be modified or trimmed.
The DN part MUST be modified such that it refers to the appropriate
Zeilenga LDAP NamedRef [Page 6]
INTERNET-DRAFT draft-zeilenga-ldap-namedref-03 25 February 2001
target in the referenced server (as detailed below). If the modified
DN part is the same as the DN of the original request, the modified DN
part MAY be trimmed.
Case 1: The target object is not held by the server and is not within
or subordinate to any naming context nor in subordinate to any
referral object held by the server.
The server SHOULD process the request normally as appropriate for
a non-existent base which not within any naming context of the
server (generally return a superior referral or noSuchObject).
This document does not detail management or processing superior
knowledge references.
Case 2: The target object is held by the server and is a referral
object.
The server SHOULD return the URI value contained in the ref
attribute of the referral object.
Example: If the client issues a modify request for the target object
of "OU=People,O=MNN,c=WW", the server may return:
ModifyResponse "referral" {
ldap://hostb/OU=People,O=MNN,C=WW
ldap://hostc/OU=People,O=MNN,C=WW
}
or, if the server chooses to trim the DN from the LDAP URL, it may
return:
ModifyResponse "referral" {
ldap://hostb/
ldap://hostc/
}
Case 3: The target object is not held by the server, but is object
where the nearest naming context contains no referral object which
the target object is subordinate to.
If the nearest naming context contains no referral object which
the target is subordinate to, the server SHOULD process the
request as appropriate for a nonexistent target (generally return
noSuchObject).
Case 4: The target object is not held by the server, but is object
where the nearest naming context contains a referral object which
the target object is subordinate to.
Zeilenga LDAP NamedRef [Page 7]
INTERNET-DRAFT draft-zeilenga-ldap-namedref-03 25 February 2001
If a client requests an operation for which the target object is
not held by the server but the nearest naming context contains a
referral object which the target object is subordinate to, the
server SHALL return a referral response which constructed from the
URI portion of the ref value of the referral object.
Example: If the client issues an add request where the target object
has a DN of "CN=Manager,OU=Roles,O=MNN,C=WW", the server will
return
AddResponse "referral" {
ldap://hostd/CN=Manager,OU=Roles,O=MNN,C=WW"
}
Note that the DN part of the LDAP URL is modified such that it
refers to the appropriate entry in the referenced server. As the
DN part is the same original target DN (in this example), the
server may trim the DN and return
AddResponse "referral" {
ldap://hostd/
}
7.3. Base Object Considerations
This section details referral handling for base object processing
within search operations. Like target object considerations for non-
search operations, there are the four cases.
In cases where the URI to be returned is a LDAP URL, the server MUST
remove any explicit scope specifier from the LDAP URL prior to return
it. In addition, the DN part MUST be modified such that it refers to
the appropriate target in the referenced server (as detailed below).
If the modified DN part is the same as the DN of the original request,
the modified DN part MAY be trimmed.
If aliasing dereferencing was necessary in finding, the DN part of URI
MUST be replaced with the base DN as modified by the alias
dereferencing such that the return URL refers to the new target object
per [RFC2251, 4.1.11].
Critical extensions MUST NOT be trimmed nor modified. Other parts of
the LDAP URL MAY be modified.
Case 1: The base object is not held by the server and is not within or
subordinate to any naming context nor in subordinate to any
referral object held by the server.
Zeilenga LDAP NamedRef [Page 8]
INTERNET-DRAFT draft-zeilenga-ldap-namedref-03 25 February 2001
The server SHOULD process the request normally as appropriate for
a non-existent base which not within any naming context of the
server (generally return a superior referral or noSuchObject).
This document does not detail management or processing superior
knowledge references.
Case 2: The base object is held by the server and is a referral
object.
The server SHOULD return the URI value contained in the ref
attribute of the referral object. If the URI is a LDAP URL, in
addition to trimming search-specific parts as described above, the
server MUST NOT trim the DN of the URI if it is not equal to the
target DN but MAY if it equal.
Example: If the client issues a search in which the base object is
"OU=Roles,O=MNN,C=WW", the server will return
SearchResultDone "referral" {
ldap://hostd/OU=Roles,O=MNN,C=WW
}
or, if it chooses to trim the DN:
SearchResultDone "referral" {
ldap://hostd/
}
Case 3: The base object is not held by the server, but is object where
the nearest naming context contains no referral object which the
base object is subordinate to.
If the nearest naming context contains no referral object which
the base is subordinate to, the request SHOULD be processed
normally as appropriate for a nonexistent base (generally return
noSuchObject).
Case 4: The base object is not held by the server, but is object where
the nearest naming context contains a referral object which the
base object is subordinate to.
If a client requests an operation for which the target object is
not held by the server but the nearest naming context contains a
referral object which the target object is subordinate to, the
server SHALL return a referral response which constructed from the
URI portion of the ref value of the referral object.
Example: If the client issues an search request for
Zeilenga LDAP NamedRef [Page 9]
INTERNET-DRAFT draft-zeilenga-ldap-namedref-03 25 February 2001
"CN=Manager,OU=Roles,O=MNN,C=WW", the server will return
SearchResultDone "referral" {
ldap://hostd/CN=Manager,OU=Roles,O=MNN,C=WW"
}
Note that the DN part of the LDAP URL is modified such that it
refers to the appropriate entry in the referenced server. As the
DN part is the same original base DN (in this example), the server
may trim the DN and return
SearchResultDone "referral" {
ldap://hostd/
}
7.4. Search Continuation Considerations
For search operations, once the base object has been found and
determined not to be a referral object, the search may progress. Any
entries matching the filter and scope of the search which is not a
referral object are returned to the client normally as described in
[RFC2251].
For each referral object within the requested scope, regardless of the
search filter, the server SHOULD return a SearchResultReference which
is constructed from the URI component of values of the ref attribute.
If the URI component is not a LDAP URL, it should be returned as is.
If the URI component is a LDAP URL, the URI must be modified to remove
any explicit scope specifier. If the LDAP URL's DN part is absent or
empty, the DN part must be modified to contain the DN of the referral
object.
Subtree Example:
If a client requests a subtree search of "O=MNN,C=WW", then in
addition to any entries within scope which match the filter, hosta
will also return two search references as the two referral objects
are within scope. One possible response might be:
SearchEntry for O=MNN,C=WW
SearchResultReference {
ldap://hostb/OU=People,O=MNN,C=WW
ldap://hostc/OU=People,O=MNN,C=WW
}
SearchEntry for CN=Manager,O=MNN,C=WW
SearchResultReference {
ldap://hostd/OU=Roles,O=MNN,C=WW
Zeilenga LDAP NamedRef [Page 10]
INTERNET-DRAFT draft-zeilenga-ldap-namedref-03 25 February 2001
}
SearchResultDone "success"
One Level Example:
If a client requests a one level search of "O=MNN,C=WW" then, in
addition to any entries one level below the "O=MNN,C=WW" entry
matching the filter, the server will also return two search
references as the two referral objects are within scope. One
possible sequence is shown:
SearchResultReference {
ldap://hostb/OU=People,O=MNN,C=WW
ldap://hostc/OU=People,O=MNN,C=WW
}
SearchEntry for CN=Manager,O=MNN,C=WW
SearchResultReference {
ldap://hostd/OU=Roles,O=MNN,C=WW
}
SearchResultDone "success"
7.6. Other Considerations
This section details other operation processing considerations.
7.6.1 Bind
A server SHOULD process a bind request as if it held no referral
objects. That is, if the bind name is a referral object or is
subordinate to a referral object, the server SHOULD process the
request normally as appropriate for a non-existent bind name (e.g.
return invalidCredentials).
7.6.2 Modify DN
If the newSuperior is a referral object or is subordinate to a
referral object, the servers SHOULD return affectsMultipleDSAs. If
the newRDN already exists but is a referral object, the server should
return affectsMultipleDSAs instead of entryAlreadyExists.
8. Security Considerations
This document defines mechanisms that can be used to bind together
LDAP (and other) servers together. The information used to bind
Zeilenga LDAP NamedRef [Page 11]
INTERNET-DRAFT draft-zeilenga-ldap-namedref-03 25 February 2001
services together 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
[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 Levels", RFC 2119 (Also BCP0014), March 1997.
[RFC2251] M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access
Protocol (v3)", RFC 2251, December 1997.
[RFC2252] M. Wahl, A. Coulbeck, T. Howes, S. Kille, "Lightweight
Directory Access Protocol (v3): Attribute Syntax
Definitions", RFC 2252, December 1997.
[RFC2253] M. Wahl, S. Kille, T. Howes, "Lightweight Directory Access
Protocol (v3): UTF-8 String Representation of Distinguished
Names", RFC 2253, December 1997.
[RFC2255] T. Howes, M. Smith, "The LDAP URL Format", RFC 2255,
December, 1997.
[RFC2396] Berners-Lee, T., R. Fielding, L. Masinter, "Uniform Resource
Identifiers (URI): Generic Syntax", RFC 2396, August 1998.
[X.500] ITU-T Rec. X.501, "The Directory: Models", 1993.
[X.511] ITU-T Rec. X.511, "The Directory: Abstract Service
Definition", 1993.
10. Acknowledgments
This document is borrows heavily from previous work by IETF LDAPext
working group. In particular, this document is based upon "Named
Referral in LDAP Directories" (an expired Internet Draft) by
Christopher Lukes, Tim Howes, Michael Roszkowski, Mark C. Smith, and
Mark Wahl.
11. Author's Address
Zeilenga LDAP NamedRef [Page 12]
INTERNET-DRAFT draft-zeilenga-ldap-namedref-03 25 February 2001
Kurt D. Zeilenga
OpenLDAP Foundation
<Kurt@OpenLDAP.org>
Copyright 2001, The Internet Society. All Rights Reserved.
This document and translations of it may be copied and furnished to
others, and derivative works that comment on or otherwise explain it
or assist in its implementation may be prepared, copied, published and
distributed, in whole or in part, without restriction of any kind,
provided that the above copyright notice and this paragraph are
included on all such copies and derivative works. However, this
document itself may not be modified in any way, such as by removing
the copyright notice or references to the Internet Society or other
Internet organizations, except as needed for the purpose of
developing Internet standards in which case the procedures for
copyrights defined in the Internet Standards process must be followed,
or as required to translate it into languages other than English.
The limited permissions granted above are perpetual and will not be
revoked by the Internet Society or its successors or assigns.
This document and the information contained herein is provided on an
"AS IS" basis and THE AUTHORS, THE INTERNET SOCIETY, AND THE INTERNET
ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED,
INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Zeilenga LDAP NamedRef [Page 13]
