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,mail,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.
|
|
