Appendix B. LDAP URLs

To query a directory a client must send the server several different pieces of information. To make it possible to group all of this information together into one standards-based string format, LDAP developers proposed a standard LDAP URL syntax, which follows the URL standard (RFC 3986). In this appendix we will take a look at the format of LDAP URLs.

The LDAP URL

The LDAP URL is composed of eight different parts:

  1. The protocol, which is usually LDAP (ldap://), though the non-standard LDAPS protocol (ldaps://) is used.
  2. The domain name (or IP address) of the server. The default is localhost.
  3. The port number of the server. The default is the standard LDAP port, 389.
  4. The base DN for the search.
  5. The list of attributes to be returned. The default is to return all the attributes.
  6. The scope specifier. The default is to use the base scope.
  7. The search filter. The default is (objectclass=*).
  8. The extension field. If the server supports extensions, parameters for those extensions can be passed in the last field.

Combining seven of the eight parts (we will skip the extension field) we can create a URL that looks something like this:

ldap://example.com:389/ou=Users,dc=example,dc=com?mail?sub?(uid=matt)

This URL is composed of the seven parts in this way:

<protocol>://<domain>:<port>/<basedn>?<attrs>?<scope>?<filter>

Where we have to use an extension we would simply append a question mark (?) and the extension information to the end of the given URL.

Using this URL to perform an LDAP search, the result would be as follows:

To use LDAPS (the non-standard practice of using LDAP over a dedicated SSL/TLS port), use ldaps:// instead of ldap://.

In many cases it is convenient to shorten the URL and accept the default options. For example, the default domain is localhost (or the IP address 127.0.0.1), the address of the server on which the URL is executed. And the default port is 389 (unless the protocol is ldaps:// instead of ldap://, in which case the default port is the LDAP port 636).

The port can be left off in most cases. But the domain portion of the URL can be omitted too:

ldap:///ou=Users,dc=example,dc=com?mail?sub?(uid=matt)

Note that there are now three slashes at the beginning, ldap:///. The domain name, which normally appears between the second and third slash, is not specified. If this URL were used, the LDAP application would connect to the localhost (the default host) at port 389 (the default LDAP port), and then proceed to run the search.

Now let's say that instead of wanting the LDAP server to return just the mail attribute, we want it to return all of the standard (non-operational) attributes. To do this, we simply leave the attribute specification empty:

ldap:///ou=Users,dc=example,dc=com??sub?(uid=matt)

Now, the attribute position has no value, though the two adjacent question marks (??) indicate where the empty attribute position is.

In the previous two examples, when we have omitted specific field values, we have had to leave the designators in the URL, so we have ldap:/// for the domain portion of the URL, and ? without a value for the attribute specification (which looks like ?? in the given example).

But when we drop values from the end of the URL we do not need to leave the empty position designators. For example, if we were to drop the filter from the end, we do not need to leave trailing ? at the end of the URL. Here's an example:

ldap:///ou=Users,dc=example,dc=com?mail?sub

In this example the mail attributes for every entry under ou=Users,dc=example,dc=com are returned.