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

   1 .TH SLAPD.ACCESS 5 "RELEASEDATE" "OpenLDAP LDVERSION"
   2 .\" Copyright 1998-2003 The OpenLDAP Foundation All Rights Reserved.
   3 .\" Copying restrictions apply.  See COPYRIGHT/LICENSE.
   4 .SH NAME
   5 slapd.access \- access configuration for slapd, the stand-alone LDAP daemon
   6 .SH SYNOPSIS
   7 ETCDIR/slapd.conf
   8 .SH DESCRIPTION
   9 The
  10 .BR slapd.conf (5)
  11 file contains configuration information for the
  12 .BR slapd (8)
  13 daemon. This configuration file is also used by the
  14 .BR slurpd (8)
  15 replication daemon and by the SLAPD tools
  16 .BR slapadd (8),
  17 .BR slapcat (8),
  18 and
  19 .BR slapindex (8).
  20 .LP
  21 The
  22 .B slapd.conf
  23 file consists of a series of global configuration options that apply to
  24 .B slapd
  25 as a whole (including all backends), followed by zero or more database
  26 backend definitions that contain information specific to a backend
  27 instance.
  28 .LP
  29 The general format of
  30 .B slapd.conf
  31 is as follows:
  32 .LP
  33 .nf
  34     # comment - these options apply to every database
  35     <global configuration options>
  36     # first database definition & configuration options
  37     database    <backend 1 type>
  38     <configuration options specific to backend 1>
  39     # subsequent database definitions & configuration options
  40     ...
  41 .fi
  42 .LP
  43 Both the global configuration and each backend-specific section can
  44 contain access information.  Backend-specific access control
  45 directives are used for those entries that belong to the backend,
  46 according to their naming context.  In case no access control
  47 directives are defined for a backend or those which are defined are
  48 not applicable, the directives from the global configuration section
  49 are then used.
  50 .LP
  51 For entries not held in any backend (such as a root DSE), the
  52 directives of the first backend (and any global directives) are
  53 used.
  54 .LP
  55 Arguments that should be replaced by actual text are shown in
  56 brackets <>.  The structure of the access control directives is
  57 .TP
  58 .B access to <what> "[ by <who> <access> [ <control> ] ]+"
  59 Grant access (specified by
  60 .BR <access> )
  61 to a set of entries and/or attributes (specified by
  62 .BR <what> )
  63 by one or more requestors (specified by
  64 .BR <who> ).
  65 .LP
  66 The field
  67 .BR <what>
  68 specifies the entity the access control directive applies to.
  69 It can have the forms
  70 .LP
  71 .nf
  72         *
  73         [dn[.<dnstyle>]=<DN>]
  74         [filter=<ldapfilter>]
  75         [attrs=<attrlist>]
  76 .fi
  77 .LP
  78 The wildcard
  79 .B *
  80 stands for all the entries.
  81 .LP
  82 The statement
  83 .B dn=<DN>
  84 selects the entries based on their naming context.
  85 The pattern is a string representation of the entry's DN.
  86 .BR base ,
  87 the default,
  88 or
  89 .B exact
  90 (an alias of
  91 .BR base )
  92 indicates the entry whose DN is equal to the pattern.
  93 .B one
  94 indicates all the entries immediately below the
  95 .BR pattern ,
  96 .B subtree
  97 indicates all entries in the subtree at the pattern,
  98 .B children
  99 indicates all the entries below (subordinate to) the pattern.
 100 .LP
 101 If the
 102 .B <dnstyle>
 103 qualifier is
 104 .BR regex ,
 105 then the value is a regular expression pattern,
 106 as detailed in
 107 .BR regex (7),
 108 matching a normalized string representation of the entry's DN.
 109 The regex form of the pattern does not (yet) support UTF-8.
 110 .LP
 111 The statement
 112 .B filter=<ldapfilter>
 113 selects the entries based on a valid LDAP filter as described in RFC 2254.
 114 .LP
 115 The statement
 116 .B attrs=<attrlist>
 117 selects the attributes the access control rule applies to.
 118 It is a comma-separated list of attribute types, plus the special names
 119 .BR entry ,
 120 indicating access to the entry itself, and
 121 .BR children ,
 122 indicating access to the entry's children. ObjectClass names may also
 123 be specified in this list, which will affect all the attributes that
 124 are required and/or allowed by that objectClass.
 125 .LP
 126 The last three statements are additive; they can be used in sequence
 127 to select entities the access rule applies to based on naming context,
 128 value and attribute type simultaneously.
 129 .LP
 130 The field
 131 .B <who>
 132 indicates whom the access rules apply to.
 133 Multiple
 134 .B <who>
 135 statements can appear in an access control statement, indicating the
 136 different access privileges to the same resource that apply to different
 137 accessee.
 138 It can have the forms
 139 .LP
 140 .nf
 141         *
 142         anonymous
 143         users
 144         self
 145
 146         dn[.<dnstyle>[,<modifier>]]=<DN>
 147         dnattr=<attrname>
 148         group[/<objectclass>[/<attrname>]]
 149                 [.<style>]=<group>
 150         peername[.<style>]=<peername>
 151         sockname[.<style>]=<sockname>
 152         domain[.<domainstyle>[,<modifier>]]=<domain>
 153         sockurl[.<style>]=<sockurl>
 154         set[.<style>]=<pattern>
 155
 156         ssf=<n>
 157         transport_ssf=<n>
 158         tls_ssf=<n>
 159         sasl_ssf=<n>
 160
 161         aci=<attrname>
 162 .fi
 163 .LP
 164 They may be specified in combination.
 165 .LP
 166 .nf
 167 .fi
 168 .LP
 169 The wildcard
 170 .B *
 171 refers to everybody.
 172 .LP
 173 The keyword
 174 .B anonymous
 175 means access is granted to unauthenticated clients; it is mostly used
 176 to limit access to authentication resources (e.g. the
 177 .B userPassword
 178 attribute) to unauthenticated clients for authentication purposes.
 179 .LP
 180 The keyword
 181 .B users
 182 means access is granted to authenticated clients.
 183 .LP
 184 The keyword
 185 .B self
 186 means access to an entry is allowed to the entry itself (e.g. the entry
 187 being accessed and the requesting entry must be the same).
 188 .LP
 189 The statement
 190 .B dn=<DN>
 191 means that access is granted to the matching DN.
 192 The optional style qualifier
 193 .B dnstyle
 194 allows the same choices of the dn form of the
 195 .B <what>
 196 field.  In addition, the
 197 .B regex
 198 style can exploit substring substitution of submatches in the
 199 .B <what>
 200 dn.regex clause by using the form
 201 .BR $<digit> ,
 202 with
 203 .B digit
 204 ranging from 1 to 9.
 205 .LP
 206 The statement
 207 .B dnattr=<attrname>
 208 means that access is granted to requests whose DN is listed in the
 209 entry being accessed under the
 210 .B attrname
 211 attribute.
 212 .LP
 213 The statement
 214 .B group=<group>
 215 means that access is granted to requests whose DN is listed
 216 in the group entry whose DN is given by
 217 .BR group .
 218 The optional parameters
 219 .B objectclass
 220 and
 221 .B attrname
 222 define the objectClass and the member attributeType of the group entry.
 223 The optional style qualifier
 224 .B style
 225 can be
 226 .BR regex ,
 227 which means that
 228 .B pattern
 229 will be expanded accorging to regex (7), and
 230 .B base
 231 or
 232 .B exact
 233 (an alias of
 234 .BR base ),
 235 which means that exact match will be used.
 236 .LP
 237 The statements
 238 .BR peername=<peername> ,
 239 .BR sockname=<sockname> ,
 240 .BR domain=<domain> ,
 241 and
 242 .BR sockurl=<sockurl>
 243 mean that the contacting host IP for
 244 .BR peername ,
 245 the named pipe file name for
 246 .BR sockname ,
 247 the contacting host name for
 248 .BR domain ,
 249 and the contacting URL for
 250 .BR sockurl
 251 are compared against
 252 .B pattern
 253 to determine access.
 254 The same
 255 .B style
 256 rules for pattern match described for the
 257 .B group
 258 case apply.
 259 The
 260 .BR domain
 261 clause also allows the
 262 .B subtree
 263 style, which succeeds when a fully qualified name exactly matches the
 264 .BR domain
 265 pattern, or its trailing part, after a
 266 .BR dot ,
 267 exactly matches the
 268 .BR domain
 269 pattern.
 270 The
 271 .B domain
 272 of the contacting host is determined by performing a DNS reverse lookup.
 273 As this lookup can easily be spoofed, use of the
 274 .B domain
 275 statement is strongly discouraged.  By default, reverse lookups are disabled.
 276 .LP
 277 The statement
 278 .B set=<pattern>
 279 is undocumented yet.
 280 .LP
 281 The statement
 282 .B aci=<attrname>
 283 means that the access control is determined by the values in the
 284 .B attrname
 285 of the entry itself.
 286 ACIs are experimental; they must be enabled at compile time.
 287 .LP
 288 The statements
 289 .BR ssf=<n> ,
 290 .BR transport_ssf=<n> ,
 291 .BR tls_ssf=<n> ,
 292 and
 293 .BR sasl_ssf=<n>
 294 set the required Security Strength Factor (ssf) required to grant access.
 295 .LP
 296 The field
 297 .B <access> ::= [self]{<level>|<priv>}
 298 determines the access level or the specific access privileges the
 299 .B who
 300 field will have.
 301 Its component are defined as
 302 .LP
 303 .nf
 304         <level> ::= none|auth|compare|search|read|write
 305         <priv> ::= {=|+|-}{w|r|s|c|x}+
 306 .fi
 307 .LP
 308 The modifier
 309 .B self
 310 allows special operations like having a certain access level or privilege
 311 only in case the operation involves the name of the user that's requesting
 312 the access.
 313 It implies the user that requests access is bound.
 314 An example is the
 315 .B selfwrite
 316 access to the member attribute of a group, which allows one to add/delete
 317 its own DN from the member list of a group, without affecting other members.
 318 .LP
 319 The
 320 .B level
 321 access model relies on an incremental interpretation of the access
 322 privileges.
 323 The possible levels are
 324 .BR none ,
 325 .BR auth ,
 326 .BR compare ,
 327 .BR search ,
 328 .BR read ,
 329 and
 330 .BR write .
 331 Each access level implies all the preceding ones, thus
 332 .B write
 333 access will imply all accesses.
 334 While
 335 .B none
 336 is trivial,
 337 .B auth
 338 access means that one is allowed access to an attribute to perform
 339 authentication/authorization operations (e.g.
 340 .BR bind )
 341 with no other access.
 342 This is useful to grant unauthenticated clients the least possible
 343 access level to critical resources, like passwords.
 344 .LP
 345 The
 346 .B priv
 347 access model relies on the explicit setting of access privileges
 348 for each clause.
 349 The
 350 .B =
 351 sign resets previously defined accesses; as a consequence, the final
 352 access privileges will be only those defined by the clause.
 353 The
 354 .B +
 355 and
 356 .B -
 357 signs add/remove access privileges to the existing ones.
 358 The privileges are
 359 .B w
 360 for write,
 361 .B r
 362 for read,
 363 .B s
 364 for search,
 365 .B c
 366 for compare, and
 367 .B x
 368 for authentication.
 369 More than one privilege can be added in one statement.
 370 .LP
 371 The optional field
 372 .B <control>
 373 controls the flow of access rule application.
 374 It can have the forms
 375 .LP
 376 .nf
 377         stop
 378         continue
 379         break
 380 .fi
 381 .LP
 382 where
 383 .BR stop ,
 384 the default, means access checking stops in case of match.
 385 The other two forms are used to keep on processing access clauses.
 386 In detail, the
 387 .B continue
 388 form allows for other
 389 .B <who>
 390 clauses in the same
 391 .B <access>
 392 clause to be considered, so that they may result in incrementally altering
 393 the privileges, while the
 394 .B break
 395 form allows for other
 396 .B <access>
 397 clauses that match the same target to be processed.
 398 Consider the (silly) example
 399 .LP
 400 .nf
 401         access to dn.subtree="dc=example,dc=com" attrs=cn
 402                 by * =cs break
 403
 404         access to dn.subtree="ou=People,dc=example,dc=com"
 405                 by * +r
 406 .fi
 407 .LP
 408 which allows search and compare privileges to everybody under
 409 the "dc=example,dc=com" tree, with the second rule allowing
 410 also read in the "ou=People" subtree,
 411 or the (even more silly) example
 412 .LP
 413 .nf
 414         access to dn.subtree="dc=example,dc=com" attrs=cn
 415                 by * =cs continue
 416                 by users +r
 417 .fi
 418 .LP
 419 which grants everybody search and compare privileges, and adds read
 420 privileges to authenticated clients.
 421 .SH CAVEATS
 422 It is strongly recommended to explicitly use the most appropriate
 423 DN
 424 .BR style ,
 425 to avoid possible incorrect specifications of the access rules as well
 426 as for performance (avoid unrequired regex matching when an exact
 427 match suffices) reasons.
 428 .LP
 429 An adminisistrator might create a rule of the form:
 430 .LP
 431 .nf
 432         access to dn.regex="dc=example,dc=com"
 433                 by ...
 434 .fi
 435 .LP
 436 expecting it to match all entries in the subtree "dc=example,dc=com".
 437 However, this rule actually matches any DN which contains anywhere
 438 the substring "dc=example,dc=com".  That is, the rule matches both
 439 "uid=joe,dc=example,dc=com" and "dc=example,dc=com,uid=joe".
 440 .LP
 441 To match the desired subtree, the rule would be more precisely
 442 written:
 443 .LP
 444 .nf
 445         access to dn.regex="^(.+,)?dc=example,dc=com$$"
 446                 by ...
 447 .fi
 448 .LP
 449 For performance reasons, it would be better to use the subtree style.
 450 .LP
 451 .nf
 452         access to dn.subtree="dc=example,dc=com"
 453                 by ...
 454 .fi
 455 .LP
 456 .SH FILES
 457 .TP
 458 ETCDIR/slapd.conf
 459 default slapd configuration file
 460 .SH SEE ALSO
 461 .BR slapd (8),
 462 .LP
 463 "OpenLDAP Administrator's Guide" (http://www.OpenLDAP.org/doc/admin/)
 464 .SH ACKNOWLEDGEMENTS
 465 .B OpenLDAP
 466 is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
 467 .B OpenLDAP
 468 is derived from University of Michigan LDAP 3.3 Release.