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 should have read access on the target server to attributes used on the
  83 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 bind DN above.
  94 .TP
  95 .B idassert-authcdn "<administrative DN for proxyAuthz purposes>"
  96 DN which is used to propagate the client's identity to the target
  97 by means of the proxyAuthz control when the client does not
  98 belong to the DIT fragment that is being proxyied by back-ldap.
  99 This is useful when operations performed by users bound to another
 100 backend are propagated through back-ldap.
 101 This requires the entry with
 102 .B idassert-authcdn
 103 identity on the remote server to have
 104 .B proxyAuthz
 105 privileges on a wide set of DNs, e.g.
 106 .BR authzTo=dn.subtree:"" ,
 107 and the remote server to have
 108 .B authz-policy
 109 set to
 110 .B to
 111 or
 112 .BR both .
 113 See
 114 .BR slapd.conf (5)
 115 for details on these statements and for remarks and drawbacks about
 116 their usage.
 117 .TP
 118 .B idassert-passwd <password>
 119 Password used with the proxy authzDN above.
 120 .TP
 121 .B idassert-mode <mode> [<flags>]
 122 defines what type of
 123 .I identity assertion
 124 is used.
 125 The supported modes are:
 126
 127 \fB<mode> := {legacy|anonymous|none|<id>|self}\fP
 128
 129 \fB<flags> := {override}\fP
 130
 131 \fB<id> := {u:<ID>|[dn:]<DN>}\fP
 132
 133 The default is
 134 .BR legacy ,
 135 which implies that the proxy will bind as
 136 .I idassert-authcdn
 137 and assert the client's identity when it is not anonymous.
 138 Direct binds are always proxied.
 139 The other modes imply that the proxy will always bind as
 140 .IR idassert-authcdn ,
 141 unless restricted by
 142 .BR idassert-authzFrom
 143 rules (see below), in which case the operation will fail;
 144 eventually, it will assert some other identity according to
 145 .BR <mode> .
 146 Other identity assertion modes are
 147 .BR anonymous
 148 and
 149 .BR self ,
 150 which respectively mean that the
 151 .I empty
 152 or the
 153 .IR client 's
 154 identity
 155 will be asserted;
 156 .BR none ,
 157 which means that no proxyAuthz control will be used, so the
 158 .I idassert-authcdn
 159 identity will be asserted.
 160 Moreover, if a string prefixed with
 161 .B u:
 162 or
 163 .B dn:
 164 is used as
 165 .BR <mode> ,
 166 that identity will be asserted.
 167 Ths string is also treated as a DN if it is not prefixed
 168 by any recognized type indicator.  Whether or not the
 169 .B dn:
 170 prefix is present, the string must pass DN validation and normalization.
 171 For all modes that require the use of the
 172 .I proxyAuthz
 173 control, on the remote server the proxy identity must have appropriate
 174 .I authzTo
 175 permissions, or the asserted identities must have appropriate
 176 .I authzFrom
 177 permissions.  Note, however, that the ID assertion feature is mostly
 178 useful when the asserted identities do not exist on the remote server.
 179 When the
 180 .B override
 181 flag is used, identity assertion takes place even when the database
 182 is authorizing for the identity of the client, i.e. after binding
 183 with the provided identity, and thus authenticating it, the proxy
 184 performs the identity assertion using the configured identity and
 185 authentication method.
 186 .RE
 187 .TP
 188 .B idassert-authzFrom <authz-regexp>
 189 if defined, selects what
 190 .I local
 191 identities are authorized to exploit the identity assertion feature.
 192 The string
 193 .B <authz-regexp>
 194 follows the rules defined for the
 195 .I authzFrom
 196 attribute.
 197 See
 198 .BR slapd.conf (5),
 199 section related to
 200 .BR authz-policy ,
 201 for details on the syntax of this field.
 202 .TP
 203 .B idassert-method <method> [<saslargs>]
 204 where valid method values are
 205
 206 \fB<method> := {none|simple|sasl}\fP
 207
 208 \fB<saslargs> := [mech=<mech>] [realm=<realm>] [authcid=<authcid>] [cred=<cred>] [authz={native|proxyauthz}]\fP
 209
 210 If method is
 211 .IR sasl ,
 212 extra parameters can be given as described above.
 213 The default is
 214 .BR simple ;
 215 .B none
 216 inhibits proxy authorization;
 217 .B sasl
 218 uses a SASL bind with the above parameters; if required,
 219 .I authorization
 220 is performed by means of native SASL mechanism, and no proxyAuthz
 221 is used for subsequent operations.
 222 .RE
 223 .TP
 224 .B proxy-whoami
 225 Turns on proxying of the WhoAmI extended operation. If this option is
 226 given, back-ldap will replace slapd's original WhoAmI routine with its
 227 own. On slapd sessions that were authenticated by back-ldap, the WhoAmI
 228 request will be forwarded to the remote LDAP server. Other sessions will
 229 be handled by the local slapd, as before. This option is mainly useful
 230 in conjunction with Proxy Authorization.
 231 .TP
 232 .B rebind-as-user
 233 If this option is given, the client's bind credentials are remembered
 234 for rebinds when chasing referrals.
 235 .TP
 236 .\".B suffixmassage <suffix> <massaged (remote) suffix>
 237 .\"DNs ending with <suffix> in a request are changed to end with <remote
 238 .\"suffix> before sending the request to the remote server, and <remote
 239 .\"suffix> in the results are changed back to <suffix> before returning
 240 .\"them to the client.
 241 .\"The <suffix> field must be defined as a valid suffix
 242 .\"for the current database.
 243 .\".TP
 244 .\".B map "{attribute | objectclass} [<local name> | *] {<foreign name> | *}"
 245 .\"Map attribute names and object classes from the foreign server to
 246 .\"different values on the local slapd.
 247 .\"The reason is that some attributes might not be part of the local
 248 .\"slapd's schema, some attribute names might be different but serve the
 249 .\"same purpose, etc.
 250 .\"If local or foreign name is `*', the name is preserved.
 251 .\"If local name is omitted, the foreign name is removed.
 252 .\"Unmapped names are preseved if both local and foreign name are `*',
 253 .\"and removed if local name is omitted and foreign name is `*'.
 254 .\".TP
 255 .\".B rewrite*
 256 .\"The rewrite options are described in the "REWRITING" section of the
 257 .\".BR slapd-meta (5)
 258 .\"manual page.
 259 .TP
 260 .B suffixmassage, map, rewrite*
 261 These directives are no longer supported by back-ldap; their
 262 functionality is now delegated to the
 263 .B rwm
 264 overlay; see
 265 .BR slapo-rwm (5)
 266 for details.
 267 However, to ease update from existing configurations, back-ldap still
 268 recognizes them and automatically instantiates the
 269 .B rwm
 270 overlay if available and not instantiated yet.
 271 This behavior may change in the future.
 272 .\".SH EXAMPLES
 273 .\"The following directives map the object class `groupOfNames' to
 274 .\"the object class `groupOfUniqueNames' and the attribute type
 275 .\"`member' to the attribute type `uniqueMember':
 276 .\".LP
 277 .\".RS
 278 .\".nf
 279 .\"map objectclass groupOfNames groupOfUniqueNames
 280 .\"map attribute uniqueMember member
 281 .\".fi
 282 .\".RE
 283 .\".LP
 284 .\"This presents a limited attribute set from the foreign
 285 .\"server:
 286 .\".LP
 287 .\".RS
 288 .\".nf
 289 .\"map attribute cn *
 290 .\"map attribute sn *
 291 .\"map attribute manager *
 292 .\"map attribute description *
 293 .\"map attribute *
 294 .\".fi
 295 .\".RE
 296 .\".LP
 297 .\"These lines map cn, sn, manager, and description to themselves, and
 298 .\"any other attribute gets "removed" from the object before it is sent
 299 .\"to the client (or sent up to the LDAP server).  This is obviously a
 300 .\"simplistic example, but you get the point.
 301 .SH PROXY CACHE OVERLAY
 302 The proxy cache overlay
 303 allows caching of LDAP search requests (queries) in a local database.
 304 See
 305 .BR slapo-pcache (5)
 306 for details.
 307 .SH FILES
 308 .TP
 309 ETCDIR/slapd.conf
 310 default slapd configuration file
 311 .SH SEE ALSO
 312 .BR slapd.conf (5),
 313 .BR slapd\-meta (5),
 314 .BR slapo\-pcache (5),
 315 .BR slapo\-rwm (5),
 316 .BR slapd (8),
 317 .BR ldap (3).
 318 .SH AUTHOR
 319 Howard Chu, with enhancements by Pierangelo Masarati