git.sur5r.net Git - openldap/blob - doc/man/man5/slapd-ldap.5

   1 .TH SLAPD-LDAP 5 "RELEASEDATE" "OpenLDAP LDVERSION"
   2 .\" Copyright 1998-2005 The OpenLDAP Foundation All Rights Reserved.
   3 .\" Copying restrictions apply.  See COPYRIGHT/LICENSE.
   4 .\" $OpenLDAP$
   5 .SH NAME
   6 slapd-ldap \- LDAP backend to slapd
   7 .SH SYNOPSIS
   8 ETCDIR/slapd.conf
   9 .SH DESCRIPTION
  10 The LDAP backend to
  11 .BR slapd (8)
  12 is not an actual database; instead it acts as a proxy to forward incoming
  13 requests to another LDAP server. While processing requests it will also
  14 chase referrals, so that referrals are fully processed instead of being
  15 returned to the slapd client.
  16
  17 Sessions that explicitly Bind to the back-ldap database always create their
  18 own private connection to the remote LDAP server. Anonymous sessions will
  19 share a single anonymous connection to the remote server. For sessions bound
  20 through other mechanisms, all sessions with the same DN will share the
  21 same connection. This connection pooling strategy can enhance the proxy's
  22 efficiency by reducing the overhead of repeatedly making/breaking multiple
  23 connections.
  24
  25 The ldap database can also act as an information service, i.e. the identity
  26 of locally authenticated clients is asserted to the remote server, possibly
  27 in some modified form.
  28 For this purpose, the proxy binds to the remote server with some
  29 administrative identity, and, if required, authorizes the asserted identity.
  30 See the
  31 .IR idassert- *
  32 rules below.
  33 The administrative identity of the proxy, on the remote server, must be
  34 allowed to authorize by means of appropriate
  35 .B authzTo
  36 rules; see
  37 .BR slapd.conf (5)
  38 for details.
  39
  40 .SH CONFIGURATION
  41 These
  42 .B slapd.conf
  43 options apply to the LDAP backend database.
  44 That is, they must follow a "database ldap" line and come before any
  45 subsequent "backend" or "database" lines.
  46 Other database options are described in the
  47 .BR slapd.conf (5)
  48 manual page.
  49 .LP
  50 Note: It is strongly recommended to set
  51 .LP
  52 .RS
  53 .nf
  54 lastmod  off
  55 .fi
  56 .RE
  57 .LP
  58 for every
  59 .B ldap
  60 and
  61 .B meta
  62 database.
  63 This is because operational attributes related to entry creation and
  64 modification should not be used, as they could be passed to the target
  65 servers, generating an error.
  66 .TP
  67 .B uri <ldapurl>
  68 LDAP server to use.  Multiple URIs can be set in in a single
  69 .B ldapurl
  70 argument, resulting in the underlying library automatically
  71 call the first server of the list that responds, e.g.
  72
  73 \fBuri "ldap://host/ ldap://backup-host"\fP
  74
  75 The URI list is space- or comma-separated.
  76 .\".TP
  77 .\".B server <hostport>
  78 .\"Obsolete option; same as `uri ldap://<hostport>/'.
  79 .TP
  80 .B acl-authcDN "<administrative DN for access control purposes>"
  81 DN which is used to query the target server for acl checking; it
  82 is supposed to have read access on the target server to attributes used
  83 on the proxy for acl checking.
  84 There is no risk of giving away such values; they are only used to
  85 check permissions.
  86 .B The acl-authcDN identity is by no means implicitly used by the proxy
  87 .B when the client connects anonymously.
  88 See the
  89 .B idassert-*
  90 feature instead.
  91 .TP
  92 .B acl-passwd <password>
  93 Password used with the
  94 .B
  95 acl-authcDN
  96 above.
  97 .TP
  98 .B idassert-authcdn "<administrative DN for proxyAuthz purposes>"
  99 DN which is used to propagate the client's identity to the target
 100 by means of the proxyAuthz control when the client does not
 101 belong to the DIT fragment that is being proxyied by back-ldap.
 102 This is useful when operations performed by users bound to another
 103 backend are propagated through back-ldap.
 104 This requires the entry with
 105 .B idassert-authcdn
 106 identity on the remote server to have
 107 .B proxyAuthz
 108 privileges on a wide set of DNs, e.g.
 109 .BR authzTo=dn.subtree:"" ,
 110 and the remote server to have
 111 .B authz-policy
 112 set to
 113 .B to
 114 or
 115 .BR both .
 116 See
 117 .BR slapd.conf (5)
 118 for details on these statements and for remarks and drawbacks about
 119 their usage.
 120 .TP
 121 .B idassert-passwd <password>
 122 Password used with the proxy authzDN above.
 123 .TP
 124 .B idassert-mode <mode> [<flags>]
 125 defines what type of
 126 .I identity assertion
 127 is used.
 128 The supported modes are:
 129
 130 \fB<mode> := {legacy|anonymous|none|<id>|self}\fP
 131
 132 \fB<flags> := {override}\fP
 133
 134 \fB<id> := {u:<ID>|[dn:]<DN>}\fP
 135
 136 The default is
 137 .BR legacy ,
 138 which implies that the proxy will bind as
 139 .I idassert-authcdn
 140 and assert the client's identity when it is not anonymous.
 141 Direct binds are always proxied.
 142 The other modes imply that the proxy will always bind as
 143 .IR idassert-authcdn ,
 144 unless restricted by
 145 .BR idassert-authzFrom
 146 rules (see below), in which case the operation will fail;
 147 eventually, it will assert some other identity according to
 148 .BR <mode> .
 149 Other identity assertion modes are
 150 .BR anonymous
 151 and
 152 .BR self ,
 153 which respectively mean that the
 154 .I empty
 155 or the
 156 .IR client 's
 157 identity
 158 will be asserted;
 159 .BR none ,
 160 which means that no proxyAuthz control will be used, so the
 161 .I idassert-authcdn
 162 identity will be asserted.
 163 Moreover, if a string prefixed with
 164 .B u:
 165 or
 166 .B dn:
 167 is used as
 168 .BR <mode> ,
 169 that identity will be asserted.
 170 Ths string is also treated as a DN if it is not prefixed
 171 by any recognized type indicator.  Whether or not the
 172 .B dn:
 173 prefix is present, the string must pass DN validation and normalization.
 174 For all modes that require the use of the
 175 .I proxyAuthz
 176 control, on the remote server the proxy identity must have appropriate
 177 .I authzTo
 178 permissions, or the asserted identities must have appropriate
 179 .I authzFrom
 180 permissions.  Note, however, that the ID assertion feature is mostly
 181 useful when the asserted identities do not exist on the remote server.
 182 When the
 183 .B override
 184 flag is used, identity assertion takes place even when the database
 185 is authorizing for the identity of the client, i.e. after binding
 186 with the provided identity, and thus authenticating it, the proxy
 187 performs the identity assertion using the configured identity and
 188 authentication method.
 189 .RE
 190 .TP
 191 .B idassert-authzFrom <authz-regexp>
 192 if defined, selects what
 193 .I local
 194 identities are authorized to exploit the identity assertion feature.
 195 The string
 196 .B <authz-regexp>
 197 follows the rules defined for the
 198 .I authzFrom
 199 attribute.
 200 See
 201 .BR slapd.conf (5),
 202 section related to
 203 .BR authz-policy ,
 204 for details on the syntax of this field.
 205 .TP
 206 .B idassert-method <method> [<saslargs>]
 207 where valid method values are
 208
 209 \fB<method> := {none|simple|sasl}\fP
 210
 211 \fB<saslargs> := [mech=<mech>] [realm=<realm>] [authcid=<authcid>] [cred=<cred>] [authz={native|proxyauthz}]\fP
 212
 213 If method is
 214 .IR sasl ,
 215 extra parameters can be given as described above.
 216 The default is
 217 .BR simple ;
 218 .B none
 219 inhibits proxy authorization;
 220 .B sasl
 221 uses a SASL bind with the above parameters; if required,
 222 .I authorization
 223 is performed by means of native SASL mechanism, and no proxyAuthz
 224 is used for subsequent operations.
 225 .RE
 226 .TP
 227 .B proxy-whoami
 228 Turns on proxying of the WhoAmI extended operation. If this option is
 229 given, back-ldap will replace slapd's original WhoAmI routine with its
 230 own. On slapd sessions that were authenticated by back-ldap, the WhoAmI
 231 request will be forwarded to the remote LDAP server. Other sessions will
 232 be handled by the local slapd, as before. This option is mainly useful
 233 in conjunction with Proxy Authorization.
 234 .TP
 235 .B rebind-as-user
 236 If this option is given, the client's bind credentials are remembered
 237 for rebinds when chasing referrals.
 238 .TP
 239 .\".B suffixmassage <suffix> <massaged (remote) suffix>
 240 .\"DNs ending with <suffix> in a request are changed to end with <remote
 241 .\"suffix> before sending the request to the remote server, and <remote
 242 .\"suffix> in the results are changed back to <suffix> before returning
 243 .\"them to the client.
 244 .\"The <suffix> field must be defined as a valid suffix
 245 .\"for the current database.
 246 .\".TP
 247 .\".B map "{attribute | objectclass} [<local name> | *] {<foreign name> | *}"
 248 .\"Map attribute names and object classes from the foreign server to
 249 .\"different values on the local slapd.
 250 .\"The reason is that some attributes might not be part of the local
 251 .\"slapd's schema, some attribute names might be different but serve the
 252 .\"same purpose, etc.
 253 .\"If local or foreign name is `*', the name is preserved.
 254 .\"If local name is omitted, the foreign name is removed.
 255 .\"Unmapped names are preseved if both local and foreign name are `*',
 256 .\"and removed if local name is omitted and foreign name is `*'.
 257 .\".TP
 258 .\".B rewrite*
 259 .\"The rewrite options are described in the "REWRITING" section of the
 260 .\".BR slapd-meta (5)
 261 .\"manual page.
 262 .TP
 263 .B suffixmassage, map, rewrite*
 264 These directives are no longer supported by back-ldap; their
 265 functionality is now delegated to the
 266 .B rwm
 267 overlay; see
 268 .BR slapo-rwm (5)
 269 for details.
 270 However, to ease update from existing configurations, back-ldap still
 271 recognizes them and automatically instantiates the
 272 .B rwm
 273 overlay if available and not instantiated yet.
 274 This behavior may change in the future.
 275 .\".SH EXAMPLES
 276 .\"The following directives map the object class `groupOfNames' to
 277 .\"the object class `groupOfUniqueNames' and the attribute type
 278 .\"`member' to the attribute type `uniqueMember':
 279 .\".LP
 280 .\".RS
 281 .\".nf
 282 .\"map objectclass groupOfNames groupOfUniqueNames
 283 .\"map attribute uniqueMember member
 284 .\".fi
 285 .\".RE
 286 .\".LP
 287 .\"This presents a limited attribute set from the foreign
 288 .\"server:
 289 .\".LP
 290 .\".RS
 291 .\".nf
 292 .\"map attribute cn *
 293 .\"map attribute sn *
 294 .\"map attribute manager *
 295 .\"map attribute description *
 296 .\"map attribute *
 297 .\".fi
 298 .\".RE
 299 .\".LP
 300 .\"These lines map cn, sn, manager, and description to themselves, and
 301 .\"any other attribute gets "removed" from the object before it is sent
 302 .\"to the client (or sent up to the LDAP server).  This is obviously a
 303 .\"simplistic example, but you get the point.
 304 .SH PROXY CACHE OVERLAY
 305 The proxy cache overlay
 306 allows caching of LDAP search requests (queries) in a local database.
 307 See
 308 .BR slapo-pcache (5)
 309 for details.
 310 .SH FILES
 311 .TP
 312 ETCDIR/slapd.conf
 313 default slapd configuration file
 314 .SH SEE ALSO
 315 .BR slapd.conf (5),
 316 .BR slapd\-meta (5),
 317 .BR slapo\-pcache (5),
 318 .BR slapo\-rwm (5),
 319 .BR slapd (8),
 320 .BR ldap (3).
 321 .SH AUTHOR
 322 Howard Chu, with enhancements by Pierangelo Masarati