git.sur5r.net Git - openldap/blob - doc/rfc/rfc1959.txt

   1
   2
   3
   4
   5
   6
   7 Network Working Group                                           T. Howes
   8 Request for Comments: 1959                                      M. Smith
   9 Category: Standards Track                         University of Michigan
  10                                                                June 1996
  11
  12
  13                            An LDAP URL Format
  14
  15 Status of this Memo
  16
  17    This document specifies an Internet standards track protocol for the
  18    Internet community, and requests discussion and suggestions for
  19    improvements.  Please refer to the current edition of the "Internet
  20    Official Protocol Standards" (STD 1) for the standardization state
  21    and status of this protocol.  Distribution of this memo is unlimited.
  22
  23 1.  Abstract
  24
  25    LDAP is the Lightweight Directory Access Protocol, defined in [1] and
  26    [2].  This document describes a format for an LDAP Uniform Resource
  27    Locator which will allow Internet clients to have direct access to
  28    the LDAP protocol.  While LDAP currently is used only as a front end
  29    to the X.500 directory, the URL format described here is general
  30    enough to handle the case of stand-alone LDAP servers (i.e., LDAP
  31    servers not back-ended by X.500).
  32
  33 2.  URL Definition
  34
  35    An LDAP URL begins with the protocol prefix "ldap" and is defined by
  36    the following grammar.
  37
  38     <ldapurl> ::= "ldap://" [ <hostport> ] "/" <dn> [ "?" <attributes>
  39                         [ "?" <scope> "?" <filter> ] ]
  40
  41     <hostport> ::= <hostname> [ ":" <portnumber> ]
  42
  43     <dn> ::= a string as defined in RFC 1485
  44
  45     <attributes> ::= NULL | <attributelist>
  46
  47     <attributelist> ::= <attributetype>
  48                         | <attributetype> [ "," <attributelist> ]
  49
  50     <attributetype> ::= a string as defined in RFC 1777
  51
  52     <scope> ::= "base" | "one" | "sub"
  53
  54     <filter> ::= a string as defined in RFC 1558
  55
  56
  57
  58 Howes & Smith               Standards Track                     [Page 1]
  59 \f
  60 RFC 1959                   An LDAP URL Format                  June 1996
  61
  62
  63    The ldap prefix indicates an entry or entries residing in the LDAP
  64    server running on the given <hostname> at the given <portnumber>.
  65    The default port is TCP port 389.  The <dn> is an LDAP Distinguished
  66    Name using the string format described in [1], with any URL-illegal
  67    characters (e.g., spaces) escaped using the % method described in RFC
  68    1738.
  69
  70    The <attributes> construct is used to indicate which attributes
  71    should be returned from the entry or entries.  Individual
  72    <attributetype> names are as defined for AttributeType in RFC 1777.
  73    If the <attributes> part is omitted, all attributes of the entry or
  74    entries should be returned.
  75
  76    The <scope> construct is used to specify the scope of the search to
  77    perform in the given LDAP server.  The allowable scopes are "base"
  78    for a base object search, "one" for a one-level search, or "sub" for
  79    a subtree search.  If <scope> is omitted, a scope of "base" is
  80    assumed.
  81
  82    The <filter> is used to specify the search filter to apply to entries
  83    within the specified scope during the search.  It has the format
  84    specified in [4], with any URL-illegal characters escaped using the %
  85    method described in RFC 1738.  If <filter> is omitted, a filter of
  86    "(objectClass=*)" is assumed.
  87
  88    Note that if the entry resides in the X.500 namespace, it should be
  89    reachable from any LDAP server that is providing front-end access to
  90    the X.500 directory.  If the <hostport> part of the URL is missing,
  91    the URL can be resolved by contacting any X.500-back-ended LDAP
  92    server.
  93
  94 3.  Examples
  95
  96    The following are some example LDAP URLs using the format defined
  97    above.  An LDAP URL referring to the University of Michigan entry,
  98    available from any X.500-capable LDAP server:
  99
 100   ldap:///o=University%20of%20Michigan,c=US
 101
 102    An LDAP URL referring to the University of Michigan entry in a
 103    particular ldap server:
 104
 105   ldap://ldap.itd.umich.edu/o=University%20of%20Michigan,c=US
 106
 107    This URL corresponds to a base object search of the "o=University of
 108    Michigan, c=US" entry using a filter of (objectclass=*), requesting
 109    all attributes.
 110
 111
 112
 113
 114 Howes & Smith               Standards Track                     [Page 2]
 115 \f
 116 RFC 1959                   An LDAP URL Format                  June 1996
 117
 118
 119    An LDAP URL referring to only the postalAddress attribute of the
 120    University of Michigan entry:
 121
 122   ldap://ldap.itd.umich.edu/o=University%20of%20Michigan,c=US?postalAddress
 123
 124    The corresponding LDAP search operation is the same as in the
 125    previous example, except that only the postalAddress attribute is
 126    requested.
 127
 128    An LDAP URL referring to the set of entries found by querying any
 129    X.500-capable LDAP server and doing a subtree search of the
 130    University of Michigan for any entry with a common name of "Babs
 131    Jensen", retrieving all attributes:
 132
 133   ldap:///o=University%20of%20Michigan,c=US??sub?(cn=Babs%20Jensen)
 134
 135    An LDAP URL referring to all children of the c=GB entry:
 136
 137   ldap://ldap.itd.umich.edu/c=GB?objectClass?one
 138
 139 The objectClass attribute is requested to be returned along with the
 140 entries.
 141
 142 4.  Security Considerations
 143
 144    The LDAP URL format does not provide a way to specify credentials to
 145    use when resolving the URL.  Therefore, it is expected that such
 146    requests will be unauthenticated. The security implications of
 147    resolving an LDAP URL are the same as those of resolving any LDAP
 148    query. See the RFC 1777 for more details.
 149
 150 5.  Prototype Implementation Availability
 151
 152    There is a prototype implementation of the specification defined in
 153    this document available.  It is an extension to the libwww client
 154    library, provided in both source and binary forms.  Also included are
 155    binary versions of the Mosaic WWW client for various platforms.  See
 156    the following URL for more details:
 157
 158         ftp://terminator.rs.itd.umich.edu/ldap/url/
 159
 160
 161
 162
 163
 164
 165
 166
 167
 168
 169
 170 Howes & Smith               Standards Track                     [Page 3]
 171 \f
 172 RFC 1959                   An LDAP URL Format                  June 1996
 173
 174
 175 6.  Bibliography
 176
 177    [1]  Kille, S., "A String Representation of Distinguished Names",
 178         RFC 1779, March 1995.
 179
 180    [2]  Yeong, W., Howes, T., and S. Kille, "Lightweight
 181         Directory Access Protocol", RFC 1777, March 1995.
 182
 183    [3]  Howes, R., Kille, S., Yeong, W., and C. Robbins, "The String
 184         Representation of Standard Attribute Syntaxes", RFC 1778,
 185         March 1995.
 186
 187    [4]  Howes, T., "A String Representation of LDAP Search Filters",
 188         RFC 1558, December 1993.
 189
 190    [5]  Berners-Lee, T., Masinter, L., and M. McCahill, "Uniform
 191         Resource Locators (URL)", RFC 1738, December 1994.
 192
 193 7.  Acknowledgements
 194
 195    This material is based upon work supported by the National Science
 196    Foundation under Grant No. NCR-9416667.
 197
 198 8.  Authors' Addresses
 199
 200    Tim Howes
 201    University of Michigan
 202    ITD Research Systems
 203    535 W William St.
 204    Ann Arbor, MI 48103-4943
 205    USA
 206
 207    Phone: +1 313 747-4454
 208    EMail: tim@umich.edu
 209
 210
 211    Mark Smith
 212    University of Michigan
 213    ITD Research Systems
 214    535 W William St.
 215    Ann Arbor, MI 48103-4943
 216    USA
 217
 218    Phone: +1 313 764-2277
 219    EMail: mcs@umich.edu
 220
 221
 222
 223
 224
 225
 226 Howes & Smith               Standards Track                     [Page 4]
 227 \f