Working With LDAP URLs

Home » Active Directory Url Example » Working With LDAP URLs

Maybe your like

Directory SDK for Java 4.0 Programmer's Guide: Working with LDAP URLs
Previous Next Contents Index

Chapter 10 Working with LDAP URLs

This chapter describes what LDAP URLs are and explains how to use LDAP URLs to search and retrieve data from the directory.

The chapter contains the following sections:

  • "Understanding LDAP URLs"

  • "Examples of LDAP URLs"

  • "Getting the Components of an LDAP URL"

  • "Processing an LDAP URL"
Understanding LDAP URLs
An LDAP URL is a URL that begins with the ldap:// protocol prefix (or ldaps://, if the server is communicating over an SSL connection) and specifies a search request to be sent to an LDAP server.

In the LDAP Java classes, you can represent an LDAP URL as an LDAPUrl object. You can invoke methods of this object to parse an LDAP URL into its components and to process a search request specified by an LDAP URL.

LDAP URLs have the following syntax:

ldap[s]://<hostname>:<port>/<base_dn>?<attributes>?<scope>?<filter> (RFC 2255, The LDAP URL Format, also specifies that a "bindname" extension can be present at the end of the URL. At this point in time, the LDAP Java classes do not handle this extension.)

The ldap:// protocol is used to connect to LDAP servers over unsecured connections, and the ldaps:// protocol is used to connect to LDAP servers over SSL connections.

Table 10.1 lists the components of an LDAP URL.

Table 10.1 Components of an LDAP URL
Component Description
<hostname> Name (or IP address in dotted format) of the LDAP server (for example, ldap.netscape.com or 192.202.185.90).
<port> Port number of the LDAP server (for example, 696). If no port is specified, the standard LDAP port (389) is used.
<base_dn> Distinguished name (DN) of an entry in the directory. This DN identifies the entry that is starting point of the search. If this component is empty, the search starts at the root DN.
<attributes> The attributes to be returned. To specify more than one attribute, use commas to delimit the attributes (for example, "cn,mail,telephoneNumber"). If no attributes are specified in the URL, all attributes are returned.
<scope> The scope of the search, which can be one of these values:
  • base retrieves information only about the distinguished name (<base_dn>) specified in the URL.
  • one retrieves information about entries one level below the distinguished name (<base_dn>) specified in the URL. The base entry is not included in this scope.
  • sub retrieves information about entries at all levels below the distinguished name (<base_dn>) specified in the URL. The base entry is included in this scope.
If no scope is specified, the server performs a base search.
<filter> Search filter to apply to entries within the specified scope of the search. If no filter is specified, the server uses the filter (objectClass=*).

Any "unsafe" characters in the URL need to be represented by a special sequence of characters (this is often called escaping unsafe characters). For example, a space must be represented as %20. Thus, the distinguished name "ou=Product Development" must be encoded as "ou=Product%20Development".

Note that <attributes>, <scope>, and <filter> are identified by their positions in the URL. If you do not want to specify any attributes, you still need to include the question marks delimiting that field.

For example, to specify a subtree search starting from "o=Airius.com" that returns all attributes for entries matching "(sn=Jensen)", use the following URL:

ldap://ldap.netscape.com/o=Airius.com??sub?(sn=Jensen) Note that the two consecutive question marks — ?? — indicate that no attributes have been specified. Since no specific attributes are identified in the URL, all attributes are returned in the search.

Examples of LDAP URLs
The following LDAP URL specifies a base search for the entry with the distinguished name "o=Airius.com".

ldap://ldap.netscape.com/o=Airius.com

  • Because no port number is specified, the standard LDAP port number (389) is used.

  • Because no attributes are specified, the search returns all attributes.

  • Because no search scope is specified, the search is restricted to the base entry "o=Airius.com".

  • Because no filter is specified, the default filter "(objectclass=*)" is used.
The following LDAP URL retrieves the postalAddress attribute of the o=Airius.com entry:

ldap://ldap.netscape.com/o=Airius.com?postalAddress

  • Because no search scope is specified, the search is restricted to the base entry "o=Airius.com".

  • Because no filter is specified, the default filter "(objectclass=*)" is used.
The following LDAP URL retrieves the cn, mail, and telephoneNumber attributes of the entry for Barbara Jensen:

ldap://ldap.netscape.com/ uid=bjensen,ou=People,o=Airius.com?cn,mail,telephoneNumber

  • Because no search scope is specified, the search is restricted to the base entry "uid=bjensen,ou=People,o=Airius.com".

  • Because no filter is specified, the default filter "(objectclass=*)" is used.
The following LDAP URL specifies a search for entries that have the last name Jensen and are at any level under "o=Airius.com":

ldap://ldap.netscape.com/o=Airius.com??sub?(sn=Jensen)

  • Because no attributes are specified, the search returns all attributes.

  • Because the search scope is sub, the search encompasses the base entry "o=Airius.com" and entries at all levels under the base entry.
The following LDAP URL specifies a search for the object class for all entries one level under "o=Airius.com":

ldap://ldap.netscape.com/o=Airius.com?objectClass?one

  • Because the search scope is one, the search encompasses all entries one level under the base entry "o=Airius.com". The search scope does not include the base entry.

  • Because no filter is specified, the default filter "(objectclass=*)" is used.
Important The syntax for LDAP URLs does not include any means for specifying credentials or passwords. Search requests initiated through LDAP URLs are unauthenticated.

Getting the Components of an LDAP URL
To get the individual components of an LDAP URL, pass the URL to the LDAPUrl constructor to create a new LDAPUrl object, then use the following methods:

  • To get an array of the attributes that should be returned in the search results, use the getAttributeArray method. To get these attributes as an enumeration, use the getAttributes method.

  • To get the hostname of the LDAP server, use the getHost method.

  • To get the port number of the LDAP server, use the getPort method.

  • To get the base DN, use the getDN method.

  • To get the scope of the search, use the getScope method.

  • To get the search filter, use the getFilter method.
Processing an LDAP URL
To process the search request specified by an LDAP URL, you can invoke one of the following methods, passing in the LDAPUrl object:

  • If the URL specifies a base search for a single entry, invoke the read method of the LDAPConnection object to read the entry from the directory.

  • Otherwise, invoke the search method of the LDAPConnection object to perform the search.
Both methods create a new LDAPConnection object, connect to the LDAP server specified in the URL, perform the search, and disconnect.

© Copyright 1999 Netscape Communications Corporation. All rights reserved.

Tag » Active Directory Url Example