RFC 4516
Lightweight Directory Access Protocol (LDAP): Uniform Resource Locator
RFC 4516: Lightweight Directory Access Protocol (LDAP): Uniform Resource Locator 🦋
Okay bestie, let's talk about RFC 4516 💖 It's a Standards Track document from June 2006, published in the Network Working Group series. The authors are M. Smith, Ed. from Pearl Crescent, LLC and T. Howes from Opsware, Inc. 💅 It obsoletes RFC 2255 and replaces it, and the title block doesn't list any other RFC it updates. ✨
Status of This Memo 📜
This document is an Internet standards track protocol for the Internet community, and it's asking for discussion and suggestions for improvements. 🌸 To check where this protocol stands in standardization, look at the current edition of "Internet Official Protocol Standards" (STD 1). Distribution of this memo is unlimited. 🫶
Copyright Notice ©️
Copyright (C) The Internet Society (2006).
Abstract 🍓
This doc describes a format for a Lightweight Directory Access Protocol (LDAP) Uniform Resource Locator (URL). An LDAP URL describes an LDAP search operation that's used to retrieve information from an LDAP directory. Or, in the context of an LDAP referral or reference, an LDAP URL describes a service where an LDAP operation may be progressed. It's giving directory lookup energy 🔥
Table of Contents
1. Introduction ....................................................2
2. URL Definition ..................................................2
2.1. Percent-Encoding ...........................................4
3. Defaults for Fields of the LDAP URL .............................5
4. Examples ........................................................6
5. Security Considerations .........................................8
6. Normative References ............................................9
7. Informative References .........................................10
8. Acknowledgements ...............................................10
Appendix A: Changes Since RFC 2255 ................................11
A.1. Technical Changes .........................................11
A.2. Editorial Changes .........................................111. Introduction 💫
LDAP is the Lightweight Directory Access Protocol [RFC4510]. 💖 This doc specifies the LDAP URL format for version 3 of LDAP and clarifies how LDAP URLs get resolved. It also defines an extension mechanism for LDAP URLs, and this mechanism may be used to give access to new LDAP extensions. Iconic, right? 👑
Note that not all the parameters of the LDAP search operation described in [RFC4511] can be expressed using the format defined in this document. Also note that URLs may be used to represent reference knowledge, including knowledge for non-search operations. 🧚
This document is an integral part of the LDAP technical specification [RFC4510]. That spec obsoletes the previously defined LDAP technical specification, RFC 3377, in its entirety. Main character energy for [RFC4510] 🎀
This document replaces RFC 2255. See Appendix A for a list of changes relative to RFC 2255. 🦋
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119]. 🌈
2. URL Definition 🎀
An LDAP URL begins with the protocol prefix "ldap" and is defined by the following grammar, following the ABNF notation defined in [RFC4234]. 💅
ldapurl = scheme COLON SLASH SLASH [host [COLON port]]
[SLASH dn [QUESTION [attributes]
[QUESTION [scope] [QUESTION [filter]
[QUESTION extensions]]]]]
; <host> and <port> are defined
; in Sections 3.2.2 and 3.2.3
; of [RFC3986].
; <filter> is from Section 3 of
; [RFC4515], subject to the
; provisions of the
; "Percent-Encoding" section
; below.
scheme = "ldap"
dn = distinguishedName ; From Section 3 of [RFC4514],
; subject to the provisions of
; the "Percent-Encoding"
; section below.
attributes = attrdesc *(COMMA attrdesc)
attrdesc = selector *(COMMA selector)
selector = attributeSelector ; From Section 4.5.1 of
; [RFC4511], subject to the
; provisions of the
; "Percent-Encoding" section
; below.
scope = "base" / "one" / "sub"
extensions = extension *(COMMA extension)
extension = [EXCLAMATION] extype [EQUALS exvalue]
extype = oid ; From section 1.4 of [RFC4512].
exvalue = LDAPString ; From section 4.1.2 of
; [RFC4511], subject to the
; provisions of the
; "Percent-Encoding" section
; below.
EXCLAMATION = %x21 ; exclamation mark ("!")
SLASH = %x2F ; forward slash ("/")
COLON = %x3A ; colon (":")
QUESTION = %x3F ; question mark ("?")The "ldap" prefix tells you there's an entry (or entries) you can reach from the LDAP server on the given hostname and portnumber. 🌸 Heads up: the <host> can be a literal IPv6 address, as covered in Section 3.2.2 of [RFC3986]. 🫶
The <dn> is an LDAP Distinguished Name written in the string format from [RFC4514]. It identifies the base object of the LDAP search, or the target of a non-search operation. 🍓
The <attributes> construct says which attributes should be returned from the entry or entries. ✨
The <scope> construct sets the scope of the search to do in the given LDAP server. The allowable scopes are "base" for a base object search, "one" for a one-level search, or "sub" for a subtree search. 🧚
The <filter> is the search filter that gets applied to the entries inside the specified scope during the search. It has the format from [RFC4515]. 💖
The <extensions> construct gives the LDAP URL an extensibility mechanism, so the URL's capabilities can be extended in the future. 🦋 Extensions are a simple comma-separated list of type=value pairs, where the =value portion MAY be omitted for options that don't need it. Each type=value pair is its own separate extension. These LDAP URL extensions aren't necessarily related to any of the LDAP extension mechanisms, so don't mix them up 🙈 A client resolving the URL may or may not support any given extension. An extension prefixed with a '!' character (ASCII 0x21) is critical. An extension that's not prefixed with a '!' character is non-critical. 🔥
If an LDAP URL extension is implemented (meaning the implementation understands it and is able to use it), the implementation MUST make use of it. If an extension is not implemented and is marked critical, the implementation MUST NOT process the URL. If an extension is not implemented and is not marked critical, the implementation MUST ignore the extension. 💀
The extension type (<extype>) MAY be specified using the numeric OID <numericoid> form (e.g., 1.2.3.4) or the descriptor <descr> form (e.g., myLDAPURLExtension). Use of the <descr> form SHOULD be restricted to registered object identifier descriptive names. See [RFC4520] for registration details and usage guidelines for descriptive names. 🌈
No LDAP URL extensions are defined in this document. Other documents, or a future version of this document, MAY define one or more extensions. 🎀
2.1. Percent-Encoding 🌸
A generated LDAP URL MUST consist only of the restricted set of characters included in one of the following three productions defined in [RFC3986]:
<reserved>
<unreserved>
<pct-encoded>Implementations SHOULD accept other valid UTF-8 strings [RFC3629] as input. 🫶 An octet MUST be encoded using the percent-encoding mechanism described in section 2.1 of [RFC3986] in any of these situations:
- The octet is not in the reserved set defined in section 2.2 of [RFC3986] or in the unreserved set defined in section 2.3 of [RFC3986].
- It is the single Reserved character '?' and occurs inside a
<dn>,<filter>, or other element of an LDAP URL. - It is a comma character ',' that occurs inside an
<exvalue>.
Note that before the percent-encoding mechanism is applied, the extensions component of the LDAP URL may contain one or more null (zero) bytes. No other component may. 🙈
3. Defaults for Fields of the LDAP URL 🧁
Some fields of the LDAP URL are optional, as described above. 💅 Without any other specification, the following general defaults SHOULD be used when a field is absent. Other documents MAY specify different defaulting rules. For example, section 4.1.10 of [RFC4511] specifies a different rule for working out the correct DN to use when it's absent in an LDAP URL that comes back as a referral. 👑
<host>: If no<host>is given, the client must have some a priori knowledge of an appropriate LDAP server to contact. 🦋<port>: The default LDAP port is TCP port 389. 🌈<dn>: If no<dn>is given, the default is the zero-length DN, "". ✨<attributes>: If the<attributes>part is omitted, all user attributes of the entry or entries should be requested (e.g., by setting the attributes field AttributeDescriptionList in the LDAP search request to a NULL list, or by using the special<alluserattrs>selector"*"). 💖<scope>: If<scope>is omitted, a<scope>of "base" is assumed. 🍓<filter>: If<filter>is omitted, a filter of"(objectClass=*)"is assumed. 🧚<extensions>: If<extensions>is omitted, no extensions are assumed. 🌸
4. Examples 🧚
okay so this section is literally a parade of example LDAP URLs, and I'm obsessed. Each one shows the format from before in action 💅 The first one points at the University of Michigan entry, and the client gets to pick which LDAP server to ask:
ldap:///o=University%20of%20Michigan,c=USThe next one is the same entry, but now it names a particular server:
ldap://ldap1.example.net/o=University%20of%20Michigan,c=USBoth of these mean the same thing: a base object search of the "o=University of Michigan,c=US" entry, using a filter of "(objectclass=*)", asking for all attributes 🦋
Next up, we only want the postalAddress attribute of that entry. The search is identical to the last one, except only postalAddress gets requested 🎀
ldap://ldap1.example.net/o=University%20of%20Michigan,
c=US?postalAddressThis one is giving subtree search energy 🌳 It goes to port 6666 and looks through the University of Michigan for anyone with a common name of "Babs Jensen", and it grabs all the attributes:
ldap://ldap1.example.net:6666/o=University%20of%20Michigan,
c=US??sub?(cn=Babs%20Jensen)Here we want every child of the c=GB entry 🇬🇧 The objectClass attribute is requested along with the entries, and the default filter of "(objectclass=*)" is used:
LDAP://ldap1.example.com/c=GB?objectClass?ONENow this one is a fun trick 🙈 It fetches the mail attribute for the entry named "o=Question?,c=US". The question mark is reserved, so it gets percent-encoded as %3f. That's the URL encoding doing its job:
ldap://ldap2.example.com/o=Question%3f,c=US?mailThis next example got split into two lines so it's easier to read, and it shows how the LDAP filter quoting and the URL quoting work together 🌈
ldap://ldap3.example.com/o=Babsco,c=US
???(four-octet=%5c00%5c00%5c00%5c04)The filter uses the LDAP escaping mechanism of \ to encode three zero or null bytes in the value. In LDAP the filter would be written as (four-octet=\00\00\00\04). Since \ has to be escaped in a URL, each \ gets percent-encoded as %5c (or %5C) in the URL 💀
Next is the DN quoting mechanism meeting URL quoting 🍓
ldap://ldap.example.com/o=An%20Example%5C2C%20Inc.,c=USDecoding that URL gives you this DN:
o=An Example\2C Inc.,c=USSo the left-most RDN value is:
An Example, Inc.These three URLs are equivalent, assuming the defaulting rules from Section 3 of this document are used 🫶
ldap://ldap.example.net
ldap://ldap.example.net/
ldap://ldap.example.net/?All three of them point at the root DSE on the ldap.example.net server ✨
The last two examples are for a hypothetical, experimental bind name extension, where the extension's value is an LDAP DN. The only difference between them is that the second one marks e-bindname as critical, which means a ! shows up in front of it. Look at how the commas inside the distinguished name get percent-encoded as %2c 🧚♀️
ldap:///??sub??e-bindname=cn=Manager%2cdc=example%2cdc=com
ldap:///??sub??!e-bindname=cn=Manager%2cdc=example%2cdc=com5. Security Considerations 🔒
okay, security time, and this part is SERIOUS bestie 😭 The general URL security considerations from [RFC3986] apply to LDAP URLs too, so don't skip those.
Here's the big deal: clients can hit a bunch of different servers through URLs, and URLs often get processed automatically with no human clicking anything. So you need to be careful 🚨 A client SHOULD have a user-configurable policy that controls which servers it will open LDAP sessions with and which security mechanisms it'll use. It SHOULD NOT open LDAP sessions that go against that policy. If a client decides to reuse an existing LDAP session when it resolves one or more LDAP URLs, it MUST make sure the session is compatible with the URL and that no security policies get broken.
Sending authentication info, no matter how it's done, can violate a user's privacy requirements 🙈 Unless a policy specifically allows authentication info to go to a server, a client should use an anonymous LDAP session. (Clients that follow the older LDAP URL specs, where every LDAP session is anonymous and unprotected, still agree with this spec. They just have the default security policy.) Even just opening a transport connection to another server can break some users' privacy requirements, so clients should give the user a way to control URL processing.
Some authentication methods, especially reusable passwords sent to the server, can reveal info that's easy to abuse, either to the remote server or to someone eavesdropping in transit. They should not be used in URL processing unless a policy explicitly permits it. Having the human user confirm the use of authentication info is appropriate in lots of situations. Strong authentication methods that don't reveal sensitive information are much preferred 💜 And if the URL represents a referral for an update operation, strong authentication methods SHOULD be used. For more info, check out the Security Considerations section of [RFC4513].
⚠️ The LDAP URL format lets you specify any LDAP search operation you want when the URL gets evaluated. Following an LDAP URL can cause unexpected results, like pulling down huge amounts of data or kicking off a long-lived search. Resolving an LDAP URL has the same security implications as resolving an LDAP search query.
6. Normative References 📚
- [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997.
- [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 10646", STD 63, RFC 3629, November 2003.
- [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, January 2005.
- [RFC4234] Crocker, D. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", RFC 4234, October 2005.
- [RFC4510] Zeilenga, K., Ed., "Lightweight Directory Access Protocol (LDAP): Technical Specification Road Map", RFC 4510, June 2006.
- [RFC4511] Sermersheim, J., Ed., "Lightweight Directory Access Protocol (LDAP): The Protocol", RFC 4511, June 2006.
- [RFC4512] Zeilenga, K., "Lightweight Directory Access Protocol (LDAP): Directory Information Models", RFC 4512, June 2006.
- [RFC4513] Harrison, R., Ed., "Lightweight Directory Access Protocol (LDAP): Authentication Methods and Security Mechanisms", RFC 4513, June 2006.
- [RFC4514] Zeilenga, K., Ed., "Lightweight Directory Access Protocol (LDAP): String Representation of Distinguished Names", RFC 4514, June 2006.
- [RFC4515] Smith, M. Ed. and T. Howes, "Lightweight Directory Access Protocol (LDAP): String Representation of Search Filters", RFC 4515, June 2006.
7. Informative References 🌸
- [RFC2396] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifiers (URI): Generic Syntax", RFC 2396, August 1998.
- [RFC4520] Zeilenga, K., "Internet Assigned Numbers Authority (IANA) Considerations for the Lightweight Directory Access Protocol (LDAP)", BCP 64, RFC 4520, June 2006.
8. Acknowledgements 🫶
The LDAP URL format was originally defined at the University of Michigan. This material is based on work supported by the National Science Foundation under Grant No. NCR-9416667. Huge thanks to both the University of Michigan and the National Science Foundation 🙌
This document obsoletes RFC 2255 by Tim Howes and Mark Smith. The changes in this revised spec come from discussions among the authors, discussions within the LDAP (v3) Revision Working Group (ldapbis), and discussions within other IETF Working Groups. Thank you to everyone in those groups! Several people made valuable comments on this document, and RL "Bob" Morgan, Mark Wahl, Kurt Zeilenga, Jim Sermersheim, and Hallvard Furuseth deserve special thanks for their contributions 👑
Appendix A: Changes Since RFC 2255 🦋
A.1. Technical Changes
Here's the glow-up list of what changed in the "URL Definition" section ✨
- All of the ABNF got revised to use common productions from [RFC4512].
- References to [RFC2396] got replaced with a reference to [RFC3986]. This lets literal IPv6 addresses go inside the <host> portion of the URL, and a note was added to remind you about it. Referencing [RFC3986] meant changing the ABNF and text so productions [RFC3986] doesn't define anymore aren't used. For example, <hostport> isn't defined by [RFC3986], so it got replaced with host [COLON port]. Also, [RFC3986] has new definitions for the "Reserved" and "Unreserved" character sets, so the net result is that "[" and "]" should be percent-encoded whenever they show up in data used to build an LDAP URL. (Those two characters were first added to the Reserved set by RFC 2732.)
- The <attrdesc> definition now refers to <attributeSelector> from [RFC4511]. This allows "*" in the <attrdesc> part of the URL. It's believed that existing implementations of RFC 2255 already support this.
- Avoided <prose-val> (bracketed-string) productions in the <dn>, <host>, <attrdesc>, and <exvalue> rules.
- The ABNF for <ldapurl> now groups the <dn> component with the preceding <SLASH>.
- The <extype> rule is now an <oid> from [RFC4512].
- The text about extension types now references [RFC4520].
- Rules got reordered to follow more closely the order the elements appear in the URL.
- "Bindname Extension": removed due to lack of known implementations.
A.2. Editorial Changes ✏️
Okay bestie, this is the glow-up list 💅 No big protocol drama here, just the wording, layout, references and examples getting cleaned up. Let's go through it 🧹✨
- Changed document title to include "LDAP:" prefix.
- IESG Note: removed note about lack of satisfactory mandatory authentication mechanisms.
- "Status of this Memo" section: updated boilerplate to match current I-D guidelines.
- "Abstract" section: separated from introductory material.
- "Table of Contents" and "Intellectual Property" sections: added.
- "Introduction" section: new section; separated from the Abstract. Changed the text to indicate that RFC 2255 is replaced by this document (instead of RFC 1959). Added text to indicate that LDAP URLs are used for references and referrals. Fixed typo (replaced the nonsense phrase "to perform to retrieve" with "used to retrieve"). Added a note to let the reader know that not all of the parameters of the LDAP search operation described in [RFC4511] can be expressed using this format.
- "URL Definition" section: removed second copy of
<ldapurl>grammar and following two paragraphs (editorial error in RFC 2255). Fixed line break within '!' sequence. Reformatted the ABNF to improve readability by aligning comments and adding some blank lines. Replaced "residing in the LDAP server" with "accessible from the LDAP server" in the sentence immediately following the ABNF. Removed the sentence "Individual attrdesc names are as defined for AttributeDescription in [RFC4511]." because [RFC4511]'s<attributeSelector>is now used directly in the ABNF. Reworded last paragraph to clarify which characters must be percent-encoded. Added text to indicate that LDAP URLs are used for references and referrals. Added text that refers to the ABNF from RFC 4234. Clarified and strengthened the requirements with respect to processing of URLs that contain implemented and not implemented extensions (the approach now closely matches that specified in [RFC4511] for LDAP controls). - "Defaults for Fields of the LDAP URL" section: added; formed by moving text about defaults out of the "URL Definition" section. Replaced direct reference to the attribute name
"*"with a reference to the special<alluserattrs>selector"*"defined in [RFC4511]. - "URL Processing" section: removed.
- "Examples" section: Modified examples to use example.com and example.net hostnames. Added missing '?' to the LDAP URL example whose filter contains three null bytes. Removed space after one comma within a DN. Revised the bindname example to use e-bindname. Changed the name of an attribute used in one example from "int" to "four-octet" to avoid potential confusion. Added an example that demonstrates the interaction between DN escaping and URL percent-encoding. Added some examples to show URL equivalence with respect to the
<dn>portion of the URL. Used uppercase in some examples to remind the reader that some tokens are case-insensitive. - "Security Considerations" section: Added a note about connection reuse. Added a note about using strong authentication methods for updates. Added a reference to [RFC4513]. Added note that simply opening a connection may violate some users' privacy requirements. Adopted the working group's revised LDAP terminology specification by replacing the word "connection" with "LDAP session" or "LDAP connection" as appropriate.
- "Acknowledgements" section: added statement that this document obsoletes RFC 2255. Added Kurt Zeilenga, Jim Sermersheim, and Hallvard Furuseth.
- "Normative References" section: renamed from "References" per new RFC guidelines. Changed from [1] style to [RFC4511] style throughout the document. Added references to RFC 4234 and RFC 3629. Updated all RFC 1738 references to point to the appropriate sections within [RFC3986]. Updated the LDAP references to refer to LDAPBis WG documents. Removed the reference to the LDAP Attribute Syntaxes document and added references to the [RFC4513], [RFC4520], and [RFC4510] documents.
- "Informative References" section: added.
- Header and "Authors' Addresses" sections: added "editor" next to Mark Smith's name. Updated affiliation and contact information.
- Copyright: updated the year.
- Throughout the document: surrounded the names of all ABNF productions with "<" and ">" where they are used in descriptive text.
Authors' Addresses 🎀
Mark Smith is the editor, and the crew at Pearl Crescent, LLC is where you'll find him 🌸
Mark Smith, Editor
Pearl Crescent, LLC
447 Marlpool Dr.
Saline, MI 48176
USA
Phone: +1 734 944-2856
EMail: mcs@pearlcrescent.comTim Howes is the other author, repping Opsware, Inc. 🦋
Tim Howes
Opsware, Inc.
599 N. Mathilda Ave.
Sunnyvale, CA 94085
USA
Phone: +1 408 744-7509
EMail: howes@opsware.comFull Copyright Statement 🔒
Copyright (C) The Internet Society (2006) 💜
This document is subject to the rights, licenses and restrictions contained in BCP 78, and except as set forth therein, the authors retain all their rights.
Now the serious legal bit, so read it properly 😭 It's kept word for word:
This document and the information contained herein are provided on an "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM 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.
Intellectual Property 🌈
The IETF takes no position on whether any Intellectual Property Rights or other rights that someone might claim over the technology in this document are valid or in scope, or whether anyone can get a license for them. It also doesn't say it went looking for any of those rights itself 🙈 If you want the details on rights in RFC documents, BCP 78 and BCP 79 have the procedures.
Copies of IPR disclosures sent to the IETF Secretariat, any assurances of licenses that will be available, and the results of any attempt to get a general license or permission for implementers or users are all on the IETF's online IPR repository at http://www.ietf.org/ipr.
The IETF also invites anyone to flag any copyrights, patents, patent applications or other proprietary rights that might cover technology needed to implement this standard. Send that to the IETF at ietf-ipr@ietf.org 🫶
Acknowledgement 🧚
Funding for the RFC Editor function is provided by the IETF Administrative Support Activity (IASA) 👑
📦 where this page comes from
- ietf: rfc4516 2006-06
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms