RFC 3296

Named Subordinate References in Lightweight Directory Access Protocol (LDAP) Directories

📅 published July 2002, from ietf

Named Subordinate References in Lightweight Directory Access Protocol (LDAP) Directories 🦋

okay bestie, this one's an IETF RFC, so it's the official spec doc for how LDAP directories handle named subordinate references 🧚 It was written by K. Zeilenga from the OpenLDAP Foundation, and it was published in July 2002. The category is Standards Track, which means it's a real protocol spec and not just an informational doc 💅 The header doesn't say it obsoletes or updates any other RFCs, so it's kind of its own thing 🌸

Status of this Memo 🎀

this doc is a Standards Track spec for the internet community, and it's asking for discussion and suggestions for improvements 💜 For the current standardization state and status of this protocol, check the current edition of "Internet Official Protocol Standards" (STD 1). And yes, the distribution is unlimited, so share it with everyone 🍓

Copyright (C) The Internet Society (2002). All Rights Reserved. 🌈

Abstract ✨

this doc is all about the schema and protocol elements for representing and managing named subordinate references in LDAP directories 🦋

Conventions 🌸

the schema definitions are written in LDAPv3 description formats [RFC2252]. the definitions are line wrapped so they're easier to read 🙈

the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" are interpreted as described in BCP 14 [RFC2119] 💅 those are the official requirement words, so they matter 🔥

1. Background and Intended Usage 💖

so LDAP (Lightweight Directory Access Protocol) [RFC2251] directories got popular way beyond being front ends to X.500 [X.500] directories 👑 that means they need a more general way to represent knowledge information. Knowledge information is info about one or more servers that's kept in another server, and it's used to link servers and services together ✨ it's giving connection energy 🫶

this doc details the schema and protocol elements for representing and manipulating named subordinate references in LDAP directories. a referral object is used to hold subordinate reference info in the directory 🧚 These referral objects hold one or more URIs [RFC2396] in values of the ref attribute type, and they're used to generate protocol referrals and continuations 🦋

there's a control called ManageDsaIT that lets you treat referral and other special objects like normal objects 💜 As the name says, it's meant to be analogous to the ManageDsaIT service option described in X.511(97) [X.511] 🎀

other forms of knowledge information aren't detailed here, but they might show up in later docs 🌈

this doc details the subordinate referral processing requirements for servers 🔥 It does NOT describe protocol syntax and semantics. that stuff is in RFC 2251 [RFC2251] 🍓

this doc also doesn't cover using subordinate knowledge references to support replicated environments, or distributed operations (for example, chaining operations from one server to other servers) 🙈

2. Schema 🌸

2.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 that's used to represent a subordinate reference in the directory 💅 The referral object class SHOULD be used together with the extensibleObject object class, so that it can support the naming attributes used in the entry's Distinguished Name (DN) [RFC2253] 💖

referral objects usually get instantiated at DSEs that sit directly under object entries within a naming context held by the DSA 🧚 they're analogous to X.500 subordinate knowledge (subr) DSEs [X.501] 🌈

when the ManageDsaIT control is present, referral objects get treated as normal entries, as described in section 3 👑 Note that the ref attribute is operational, so it only comes back in a search entry response when it's requested 🙈

when the ManageDsaIT control is absent, the content of referral objects is used to build referrals and search references, as described in Section 4 🔥 Because of that, the referral entries themselves are not visible to clients 🫶

2.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 it's case sensitive ✨ It's multi-valued too 🦋 Values placed in the attribute MUST conform to the labeledURI specification [RFC2079] 💅 That spec defines a format that's a URI, optionally followed by whitespace and a label 🌸 This doc does not use the label portion of the syntax 🙈 Future documents MAY enable new functionality by adding more structure to the label portion of the syntax as it appears in the ref attribute 🧚

if the URI in a ref attribute value points to an LDAP [RFC2251] server, it MUST be in the form of an LDAP URL [RFC2255] 🔥 The LDAP URL SHOULD NOT contain an explicit scope specifier, filter, attribute description list, or any extensions 💀 The LDAP URL SHOULD contain a non-empty DN 🍓 How LDAP URLs with absent or empty DN parts, or with an explicit scope specifier, are handled is NOT defined by this spec 🙈

other URI schemes MAY be used, as long as all operations that return referrals based on the value could still be performed 🌈 This doc does not detail use of non-LDAP URIs, and that's left to future specs 🦋

the referential integrity of the URI SHOULD NOT be validated by the server that holds or returns it (whether it's a value of the attribute or part of a referral result or search reference response) 💜

when returning a referral result or search continuation, the server MUST NOT return the separator or label portions of the attribute values as part of the reference 👑 When the attribute has multiple values, the URI part of each value is used to build the referral result or search continuation 💖

the ref attribute values SHOULD NOT be used as a relative name-component of an entry's DN [RFC2253] 🫶

this doc uses the ref attribute together with the referral object class to represent subordinate references 🎀 The ref attribute may be used for other purposes as defined by other documents ✨

3. The ManageDsaIT Control 🦋

the client may provide the ManageDsaIT control with an operation to say that the operation is meant to manage objects within the DSA (server) Information Tree 🧚 The control makes Directory-specific entries (DSEs), no matter their type, get treated as normal entries, so clients can read and update these entries using LDAP operations 💅

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 based on information held in referral objects. Instead, it SHALL treat the referral object as a normal entry 🔥 The server is still free to return referrals for other reasons 👑 When the control is 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 later documents ✨

4. Named Subordinate References 💜

a named subordinate reference is built by instantiating a referral object in the referencing server, with ref attribute values that point to the matching subtree held in the referenced server 🦋 In general, the name of the referral object is the same as the referenced object, and that referenced object is a context prefix [X.501] 🧚

so, 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 "DC=sub,DC=example,DC=net" with a ref attribute whose value is "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

usually the DN of the referral object and the DN of the object in the referenced server are the same 🌸

if the ref attribute has multiple values, all the DNs contained within the LDAP URLs SHOULD be equivalent 🍓 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 3 🔥

5. Scenarios 🌈

the following sections give specs for how referral objects should be used in different scenarios, followed by examples that show that usage 💅 The scenarios here cover referral object handling when finding the target of a non-search operation, when finding the base of a search operation, and when generating search references 🦋 Last but not least, other operation processing considerations are presented 👑

it's worth noting that in this doc, a search operation is conceptually split into two distinct, sequential phases: (1) finding the base object where the search begins, 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 💖

also note that the ref attribute may have multiple values. Where these sections refer to a single ref attribute value, multiple values may be substituted, and they SHOULD be processed and returned (in any order) as a group in a referral or search reference, the same way as for a single value 🫶

search references returned for a given request may come back in any order 🎀

5.1. Example Configuration ✨

for example, say the contacted server (hosta) holds the entry "O=MNN,C=WW" and the entry "CN=Manager,O=MNN,C=WW", plus 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/OU=Roles,O=MNN,C=WW
      objectClass: referral
      objectClass: extensibleObject

the first referral object tells the server that the subtree "OU=People,O=MNN,C=WW" is held by hostb and hostc (for example, one is the master and the other is a shadow) 🧚 The second referral object tells the server that the subtree "OU=Roles,O=MNN,C=WW" is held by hostd 💅

also, in the context of this doc, the "nearest naming context" means the deepest context that the object is within 🌸 So if the object is within multiple naming contexts, the nearest naming context is the one that's subordinate to all the other naming contexts the object is within 🍓

5.2. Target Object Considerations

okay so this part is about what the server does when a client asks for an add, compare, delete, modify, or modify DN 💅 there are four cases the server has to handle for the target object 🎀

The DN part MUST be modified so it points at the right target on the referenced server (more on how below). Even when the DN being returned is the same as the target DN, it SHOULD NOT be trimmed ✨

When the URI being returned is an LDAP URL, the server SHOULD trim any scope, filter, or attribute list from it before sending it back 🦋 Critical extensions MUST NOT be trimmed or modified, bestie, not even a little 🙈

Case 1: The target object is not held by the server, and it isn't within or subordinate to any naming context, and it isn't subordinate to any referral object the server holds.

The server SHOULD process the request normally, the way it would for a non-existent base that isn't in any of its naming contexts (generally return noSuchObject, or a referral based on superior knowledge reference information). This document doesn't detail how superior knowledge reference information is managed or processed 🌸

Case 2: The target object is held by the server and is a referral object.

The server SHOULD return the URI value in the ref attribute of the referral object, modified as described above 💜

Example: if the client issues a modify request for the target object "OU=People,O=MNN,c=WW", the server will return:

         ModifyResponse (referral) {
             ldap://hostb/OU=People,O=MNN,C=WW
             ldap://hostc/OU=People,O=MNN,C=WW
         }

Case 3: The target object is not held by the server, but the nearest naming context contains no referral object that the target object is subordinate to.

If the nearest naming context contains no referral object that the target is subordinate to, the server SHOULD process the request as it would for a nonexistent target (generally return noSuchObject) 🙈

Case 4: The target object is not held by the server, but the nearest naming context contains a referral object that the target object is subordinate to.

If a client requests an operation where the target object isn't held by the server, and the nearest naming context contains a referral object that the target object is subordinate to, the server SHOULD return a referral response built 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 so it points at the right entry on the referenced server 🫶

5.3. Base Object Considerations

this section is about base object processing inside search operations 🔍 just like target object considerations for the non-search stuff, there are the same four cases 💖

When the URI being returned is an LDAP URL, the server MUST provide an explicit scope specifier from the LDAP URL before returning it. On top of that, the DN part MUST be modified so it refers to the right target on the referenced server (as detailed below) 🎀

If alias dereferencing was needed to find the referral object, the DN part of the URI MUST be replaced with the base DN as modified by the alias dereferencing, so the returned URL refers to the new target object per [RFC2251, 4.1.11] ✨

Critical extensions MUST NOT be trimmed nor modified 💅

Case 1: The base object is not held by the server, and it isn't within or subordinate to any naming context the server holds.

The server SHOULD process the request normally, the way it would for a non-existent base that isn't in any of its naming contexts (generally return a superior referral or noSuchObject). This document doesn't detail how superior knowledge references are managed or processed 🌈

Case 2: The base object is held by the server and is a referral object.

The server SHOULD return the URI value in the ref attribute of the referral object, appropriately modified as described above 🦋

Example: if the client issues a subtree search where the base object is "OU=Roles,O=MNN,C=WW", the server will return:

         SearchResultDone (referral) {
             ldap://hostd/OU=Roles,O=MNN,C=WW??sub
         }

If the client issued a base or oneLevel search instead of subtree, the returned LDAP URL would explicitly specify "base" or "one", respectively, instead of "sub" 🍓

Case 3: The base object is not held by the server, but the nearest naming context contains no referral object that the base object is subordinate to.

If the nearest naming context contains no referral object that the base is subordinate to, the request SHOULD be processed normally, the way it would for a nonexistent base (generally return noSuchObject) 💀

Case 4: The base object is not held by the server, but the nearest naming context contains a referral object that the base object is subordinate to.

If a client requests an operation where the target object isn't held by the server, and the nearest naming context contains a referral object that the target object is subordinate to, the server SHOULD return a referral response constructed from the URI portion of the ref value of the referral object 🧚

Example: if the client issues a base search request for "CN=Manager,OU=Roles,O=MNN,C=WW", the server will return:

         SearchResultDone (referral) {
             ldap://hostd/CN=Manager,OU=Roles,O=MNN,C=WW??base"
         }

If the client issued a subtree or oneLevel search instead of subtree, the returned LDAP URL would explicitly specify "sub" or "one", respectively, instead of "base" 🫶

Note that the DN part of the LDAP URL is modified so it refers to the right entry on the referenced server 💜

5.4. Search Continuation Considerations

for search operations, once the base object has been found and it's been determined not to be a referral object, the search can keep going 🏃‍♀️ any entry that matches the filter and scope of the search and isn't a referral object gets 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 constructed from the URI component of the values of the ref attribute. If the URI component isn't an LDAP URL, it should be returned as is. 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. If the URI component is an LDAP URL, the URI SHOULD be modified to add an explicit scope specifier 🎀

Subtree Example:

If a client requests a subtree search of "O=MNN,C=WW", then in addition to any entries within scope that match the filter, hosta will also return two search references, since the two referral objects are within scope 🌸 one possible response might look like this:

          SearchEntry for O=MNN,C=WW
          SearchResultReference {
              ldap://hostb/OU=People,O=MNN,C=WW??sub
              ldap://hostc/OU=People,O=MNN,C=WW??sub
          }
          SearchEntry for CN=Manager,O=MNN,C=WW
          SearchResultReference {
              ldap://hostd/OU=Roles,O=MNN,C=WW??sub
          }
          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 that match the filter, the server will also return two search references, since the two referral objects are within scope 🌷 one possible sequence is shown here:

          SearchResultReference {
              ldap://hostb/OU=People,O=MNN,C=WW??base
              ldap://hostc/OU=People,O=MNN,C=WW??base
          }
          SearchEntry for CN=Manager,O=MNN,C=WW
          SearchResultReference {
              ldap://hostd/OU=Roles,O=MNN,C=WW??base
          }
          SearchResultDone (success)
Heads up: unlike the examples in Section 4.5.3.1 of RFC 2251, the LDAP URLs returned with the SearchResultReference messages contain an explicit scope specifier, as this specification requires 🙈

5.6. Other Considerations

this section covers processing considerations for other operations 🧸

5.6.1 Bind

Servers SHOULD NOT return the referral result code if the bind name (or authentication identity or authorization identity) is (or is subordinate to) a referral object, but they MAY use the knowledge information to process the bind request (such as to support a future distributed operation specification) 🔮 Where the server makes no use of the knowledge information, it processes the request normally, the way it would for a non-existent authentication or authorization identity (e.g., return invalidCredentials) 💅

5.6.2 Modify DN

If the newSuperior is a referral object or is subordinate to a referral object, the server SHOULD return affectsMultipleDSAs. If the newRDN already exists but is a referral object, the server SHOULD return affectsMultipleDSAs instead of entryAlreadyExists 🚧

6. Security Considerations

okay this is the serious bit, so listen up 🚨 this document defines mechanisms that can be used to tie LDAP (and other) servers together 🔗 the information used to tie services together should be protected from unauthorized modification, no exceptions 😭 and if the server topology information isn't public, it should also be protected from unauthorized disclosure 🔐

7. Acknowledgments

this document borrows heavily from previous work by the IETF LDAPext Working Group 🫶 in particular, it's based on "Named Referral in LDAP Directories" (an expired Internet Draft) by Christopher Lukas, Tim Howes, Michael Roszkowski, Mark C. Smith, and Mark Wahl 🌟

8. Normative References

  • [RFC2079] Smith, M., "Definition of an X.500 Attribute Type and an Object Class to Hold Uniform Resource Identifiers (URIs)", RFC 2079, January 1997.
  • [RFC2119] Bradner, S., "Key Words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997.
  • [RFC2251] Wahl, M., Howes, T. and S. Kille, "Lightweight Directory Access Protocol (v3)", RFC 2251, December 1997.
  • [RFC2252] Wahl, M., Coulbeck, A., Howes, T. and S. Kille, "Lightweight Directory Access Protocol (v3): Attribute Syntax Definitions", RFC 2252, December 1997.
  • [RFC2253] Wahl, M., Kille, S. and T. Howes, "Lightweight Directory Access Protocol (v3): UTF-8 String Representation of Distinguished Names", RFC 2253, December 1997.
  • [RFC2255] Howes, T. and M. Smith, "The LDAP URL Format", RFC 2255, December, 1997.
  • [RFC2396] Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform Resource Identifiers (URI): Generic Syntax", RFC 2396, August 1998.
  • [X.501] ITU-T, "The Directory: Models", X.501, 1993.

9. Informative References

  • [X.500] ITU-T, "The Directory: Overview of Concepts, Models, and Services", X.500, 1993.
  • [X.511] ITU-T, "The Directory: Abstract Service Definition", X.500, 1997.

10. Author's Address ✨

okay so the author info is super short bestie 🎀

Kurt D. Zeilenga OpenLDAP Foundation

EMail: Kurt@OpenLDAP.org 💌

Copyright (C) The Internet Society (2002). All Rights Reserved. 🌸

okay so this part is the legal stuff, and ngl it's kind of iconic in its own way 💅 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 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. 😭

Acknowledgement 🫶

Funding for the RFC Editor function is currently provided by the Internet Society. 🌈

📦 where this page comes from