LDAP URLs

What is an LDAP URL?

An LDAP URL is a structured string used to identify and describe resources or search operations within an LDAP directory service. Unlike a typical web URL, which locates web or API resources, an LDAP URL can specify directory entries, search parameters, and even tie in server-specific features vital for referrals, application configuration, and automated directory access. LDAP URLs are key elements in client-to-directory communications, referral responses, and in defining how services and applications interact with directories like Active Directory and OpenLDAP.

For example:
ldap://localhost/
This refers to the root of a local LDAP server. While it looks like familiar web URLs, its ldap: scheme and field structure are unique to directory protocols.

Where and Why Are LDAP URLs Used?

LDAP URLs appear wherever software needs to reference a portion of a directory or instruct a client how to connect or search:

• Client connections: Libraries and tools use LDAP URLs (often as connection strings or options) to locate servers and define operations.
• Referrals: When an LDAP server cannot fulfill a request directly, it returns a referral—an LDAP URL pointing the client to an alternate server or subtree.
• Configuration files: Many directory-aware applications require LDAP URLs to specify connection targets and base DNs.
• Scripting and automation: Automation tools compose and parse LDAP URLs to interact with directory data programmatically.

Common workflows include authenticating users against LDAP, directory synchronization, and handling cross-directory referrals.

LDAP URL Syntax and Structure

The formal structure of LDAP URLs was originally defined by RFC 2255. However, RFC 2255 is now obsolete and has been superseded by RFC 4516 (as detailed in the LDAPv3 roadmap in RFC 4510). RFC 4516 is the authoritative standard for LDAP URL syntax and semantics. Both RFC 2255 and RFC 4516 specify a consistent, layered URL structure, but RFC 4516 reflects modern usage and standardizes several behaviors.

The canonical LDAP URL syntax is:

ldap://hostport[/dn[?attributes[?scope[?filter[?extensions]]]]]

Components (RFC 4516, Section 2)

• scheme: Required. ldap (for plain LDAP, usually over TCP). ldaps is widely used for LDAP over SSL/TLS, but was introduced after RFC 2255 and formalized in practice; support varies by vendor and context.
• hostport: Required. The host address or FQDN, optionally followed by a colon and port number (e.g., ldap.example.com:389).
• dn: Optional. The base Distinguished Name to operate on. If omitted, the root DSE is used by default.
• attributes: Optional. A comma-separated attribute list to return. Empty means all user attributes.
• scope: Optional. Search depth: base (entry only), one (immediate children), or sub (entire subtree). Defaults to base.
• filter: Optional. LDAP search filter, in the format defined by RFC 2254, and must be URL-encoded if containing special characters.
• extensions: Optional. Comma-separated list of extensions for additional or proprietary behaviors. Most implementations ignore or do not support LDAP URL extensions.

Important:
When omitting intermediate fields, RFC 2255 and RFC 4516 require that all positionally implied question mark (?) delimiters be present. As stated in RFC 4516 Section 2.1, this ensures unambiguous field parsing.

Example

A complete LDAP URL illustrating all fields:

ldap://ldap.example.com:389/ou=users,dc=example,dc=com?cn,sn,mail?sub?(department=Engineering)

This example specifies a search on ldap.example.com (port 389), under the DN ou=users,dc=example,dc=com, retrieving the cn, sn, and mail attributes for all subtree entries where department is Engineering.

Delimiter Rules

If a field is omitted, retain its placeholder using the ? delimiter.
Example omitting attributes:

ldap://ldap.example.com/dc=example,dc=com??sub?(objectClass=person)

Here, attributes is omitted, so two questions marks ?? are used before specifying scope.
Reference: RFC 4516 Section 2.1—All omitted intermediate fields must be denoted by their delimiters.

Understanding LDAP URL Fields

Host and Port

• Host: Specifies the LDAP server. If omitted, defaults to the local server or context-dependent behavior (e.g., referral source).
• Port: Defaults to 389 for LDAP and 636 for LDAPS if not specified.

Distinguished Name (DN)

• The base DN indicating the entry or subtree to operate upon. An empty DN designates the root DSE (Directory Service Entry).

Attributes

• Comma-separated list of LDAP attributes to return in the response. Omitting the field or leaving it empty requests all user attributes.

Scope

• Determines search depth:
  • base: The DN itself only.
  • one: Its direct children.
  • sub: The full subtree under the DN.
• Defaults to base if omitted.

Filter

• LDAP filter, using standard syntax as in RFC 2254.
• Special characters in filters must be percent-encoded for URL safety.

Extensions

• Optional, comma-separated extensions for advanced or vendor-specific options.
• Warning: Not all LDAP libraries or servers support extensions; use cautiously and test for interoperability.

Default Values Table

LDAP vs LDAPS URLs

LDAP can be accessed via two main schemes in URLs:

• ldap:// — Standard, unencrypted LDAP over TCP (port 389). RFC 2255 and RFC 4516 define this officially.
• ldaps:// — LDAP over SSL/TLS, commonly on port 636.
  • Note: The ldaps:// scheme is a widely adopted convention (formalized in practice after RFC 2255) but was not part of the earliest LDAP URL standards.
  • Vendor and library support for LDAPS URLs is common, but not universal. Always verify your target environment and library support.

Security Considerations

• LDAPS (ldaps://) encrypts all LDAP communication from the start. This provides confidentiality and integrity.
• StartTLS, initiated on a standard ldap:// connection, is a modern and standards-recommended way (per newer LDAP security RFCs) to secure an existing LDAP connection. It is often preferred over direct LDAPS in environments where contemporary encryption negotiation or certificate validation is required.
• Best practice: Prefer StartTLS on ldap:// connections where supported; otherwise, use ldaps:// for encryption. Avoid plaintext LDAP for sensitive operations.

Common Use Cases and Practical Examples

1. Connecting to Active Directory

Query for user objects and their email addresses in Active Directory:

ldap://ad.example.com/CN=Users,DC=example,DC=com?mail?sub?(objectClass=user)

2. Referrals

A referral returned from an LDAP server might look like:

ldap://directory2.example.net/ou=partners,dc=example,dc=net?uid?one?(partnerID=12345)

This instructs a client (e.g., during a search) to redirect and search the specified DN on another server.

3. Configuration Strings

A configuration file could specify:

ldaps://ldap.company.com:636/dc=company,dc=com

Signaling a secure connection to the LDAP server, with all operations starting at the given DN.

Common Pitfalls and Misconceptions

• Delimiter omission: Intermediate fields that are omitted must still be identified with ? delimiters.
  • Correct: ldap://host/dn??sub?(filter)
  • Incorrect: ldap://host/dn?sub?(filter) (missing a ? per RFC 4516 Section 2.1)
• Assuming universal LDAPS support: Not all servers or client libraries support ldaps://. Always confirm in your environment.
• Optional fields confusion: Aside from scheme and hostport, all LDAP URL fields are technically optional, but delimiter placeholders are not.
• Varying support for URL extensions: Implementations may ignore or incompletely support the extensions field; do not assume full interoperability or feature support.
• Improper filter encoding: Failing to percent-encode special characters in LDAP filters can result in errors or unexpected behavior.

Security and Interoperability Best Practices

• Always encrypt sensitive connections: Use ldaps:// or StartTLS on ldap:// connections to protect authentication and sensitive data.
• StartTLS is recommended where possible: StartTLS provides upgradeable security and is the preferred approach in modern LDAP deployments, as endorsed by current RFCs.
• Validate compatibility: Not all servers, libraries, or middleware support every field or extension in LDAP URLs (notably, the extensions field or features standardized in RFC 2255/4516). Always test your URLs in each real-world target environment—vendor quirks and partial implementations can affect functionality.
• Escape user-provided data: Percent-encode DN and filter values to safeguard against injection or malformed URLs.
• Consult authoritative RFCs and vendor docs: Implementation gaps exist between theoretical standard and actual parser/library behavior. Cross-reference RFC 4516 along with server and client documentation when designing for interoperability.

Further Reading and References

• RFC 4516: LDAP: Uniform Resource Locator (URL)
  (Current, standard specification for LDAP URLs, superseding RFC 2255)
• RFC 2255: The LDAP URL Format
  (Obsolete, but commonly referenced in legacy material)
• RFC 1959: An LDAP URL Format
  (Obsolete precursor to RFC 2255)
• RFC 4510: LDAPv3 Technical Specification Roadmap
  (Lists RFC 4516 as the authoritative LDAP URL standard)

For precise, up-to-date syntax and behavioral details, always refer to RFC 4516 alongside your LDAP server or client documentation.

Sources

• www.rfc-editor.org — rfc2255
• www.rfc-editor.org — rfc1959
• www.rfc-editor.org — rfc4510