Netscape Directory Server Administrator's Guide: Appendix C LDAP URLs

Administrator's Guide
Netscape Directory Server

Appendix C LDAP URLs

When you access the Netscape Directory Server (Directory Server) using a web-based client such as Directory Server Gateway, you must provide an LDAP URL identifying the Directory Server you wish to access.

You also use LDAP URLs when managing Directory Server referrals or access control instructions. This appendix contains the following sections:

Components of an LDAP URL

Escaping Unsafe Characters

Examples of LDAP URLs

Components of an LDAP URL

LDAP URLs have the following syntax:

ldap[s]://hostname:port/base_dn?attributes?scope?filter
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 C-1 lists the components of an LDAP URL.

Table C-1 LDAP URL Components

Component

Description

hostname

Name (or IP address in dotted format) of the LDAP server. For example: ldap.example.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) or LDAPS port (636) is used.

base_dn

Distinguished name (DN) of an entry in the directory. This DN identifies the entry that is the starting point of the search. If no base DN is specified, the search starts at the root of the directory tree.

attributes

The attributes to be returned. To specify more than one attribute, use commas to separate 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=*).

The attributes, scope, and filter components 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 "dc=example,dc=com" that returns all attributes for entries matching "(sn=Jensen)", use the followingLDAP URL:

ldap://ldap.example.com/dc=example,dc=com??sub?(sn=Jensen)
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.

Escaping Unsafe Characters

Any "unsafe" characters in the URL need to be represented by a special sequence of characters. This is called escaping unsafe characters.

For example, a space is an unsafe character that must be represented as %20 within the URL. Thus, the distinguished name "o=example.com corporation" must be encoded as "o=example.com%20corporation".

The following table lists the characters that are considered unsafe within URLs and provides the associated escape characters to use in place of the unsafe character:

Unsafe Character

Escape Characters

space

%20

<

%3c

>

%3e

"

%22

#

%23

%

%25

{

%7b

}

%7d

|

%7c

\

%5c

^

%5e

~

%7e

[

%5b

]

%5d

`

%60

Examples of LDAP URLs

Example 1:

The following LDAP URL specifies a base search for the entry with the distinguished name dc=example,dc=com.

ldap://ldap.example.com/dc=example,dc=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 dc=example,dc=com.

Because no filter is specified, the directory uses the default filter (objectclass=*).

Example 2:

The following LDAP URL retrieves the postalAddress attribute of the entry with the DN dc=example,dc=com:

ldap://ldap.example.com/dc=example,dc=com?postalAddress

Because no search scope is specified, the search is restricted to the base entry dc=example,dc=com.

Because no filter is specified, the directory uses the default filter (objectclass=*).

Example 3:

The following LDAP URL retrieves the cn, mail, and telephoneNumber attributes of the entry for Barbara Jensen:

ldap://ldap.example.com/cn=Barbara%20Jensen,dc=example,dc=com?cn,ma il,telephoneNumber

Because no search scope is specified, the search is restricted to the base entry cn=Barbara Jensen,dc=example,dc=com.

Because no filter is specified, the directory uses the default filter (objectclass=*).

Example 4:

The following LDAP URL specifies a search for entries that have the surname Jensen and are at any level under dc=example,dc=com:

ldap://ldap.example.com/dc=example,dc=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 dc=example,dc=com and entries at all levels under the base entry.

Example 5:

The following LDAP URL specifies a search for the object class for all entries one level under dc=example,dc=com:

ldap://ldap.example.com/dc=example,dc=com?objectClass?one

Because the search scope is one, the search encompasses all entries one level under the base entry dc=example,dc=com. The search scope does not include the base entry.

Because no filter is specified,the directory uses the default filter (objectclass=*).

Note

The syntax for LDAP URLs does not include any means for specifying credentials or passwords. Search requests initiated through LDAP URLs are unauthenticated, unless the LDAP client that supports LDAP URLs provides an authentication mechanism. For example, Directory Server Gateway supports authentication.

Component	Description
hostname	Name (or IP address in dotted format) of the LDAP server. For example: `ldap.example.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) or LDAPS port (636) is used.
base_dn	Distinguished name (DN) of an entry in the directory. This DN identifies the entry that is the starting point of the search. If no base DN is specified, the search starts at the root of the directory tree.
attributes	The attributes to be returned. To specify more than one attribute, use commas to separate 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=*)`.

Unsafe Character	Escape Characters
space	%20
<	%3c
>	%3e
"	%22
#	%23
%	%25
{	%7b
}	%7d
\|	%7c
\	%5c
^	%5e
~	%7e
[	%5b
]	%5d
`	%60

Last Updated October 30, 2003


Note	The syntax for LDAP URLs does not include any means for specifying credentials or passwords. Search requests initiated through LDAP URLs are unauthenticated, unless the LDAP client that supports LDAP URLs provides an authentication mechanism. For example, Directory Server Gateway supports authentication.