]> git.sur5r.net Git - openldap/blob - doc/guide/admin/access-control.sdf
Merge remote-tracking branch 'origin/mdb.master'
[openldap] / doc / guide / admin / access-control.sdf
1 # $OpenLDAP$
2 # Copyright 1999-2012 The OpenLDAP Foundation, All Rights Reserved.
3 # COPYING RESTRICTIONS APPLY, see COPYRIGHT.
4
5 H1: Access Control
6
7 H2: Introduction
8
9 As the directory gets populated with more and more data of varying sensitivity, 
10 controlling the kinds of access granted to the directory becomes more and more
11 critical. For instance, the directory may contain data of a confidential nature 
12 that you may need to protect by contract or by law. Or, if using the directory 
13 to control access to other services, inappropriate access to the directory may 
14 create avenues of attack to your sites security that result in devastating 
15 damage to your assets.
16
17 Access to your directory can be configured via two methods, the first using
18 {{SECT:The slapd Configuration File}} and the second using the {{slapd-config}}(5) 
19 format ({{SECT:Configuring slapd}}).
20
21 The default access control policy is allow read by all clients. Regardless of 
22 what access control policy is defined, the {{rootdn}} is always allowed full 
23 rights (i.e. auth, search, compare, read and write) on everything and anything.
24
25 As a consequence, it's useless (and results in a performance penalty) to explicitly 
26 list the {{rootdn}} among the {{<by>}} clauses.
27
28 The following sections will describe Access Control Lists in greater depth and 
29 follow with some examples and recommendations. See {{slapd.access}}(5) for
30 complete details.
31
32 H2: Access Control via Static Configuration
33
34 Access to entries and attributes is controlled by the
35 access configuration file directive. The general form of an
36 access line is:
37
38 >    <access directive> ::= access to <what>
39 >        [by <who> [<access>] [<control>] ]+
40 >    <what> ::= * |
41 >        [dn[.<basic-style>]=<regex> | dn.<scope-style>=<DN>]
42 >        [filter=<ldapfilter>] [attrs=<attrlist>]
43 >    <basic-style> ::= regex | exact
44 >    <scope-style> ::= base | one | subtree | children
45 >    <attrlist> ::= <attr> [val[.<basic-style>]=<regex>] | <attr> , <attrlist>
46 >    <attr> ::= <attrname> | entry | children
47 >    <who> ::= * | [anonymous | users | self
48 >            | dn[.<basic-style>]=<regex> | dn.<scope-style>=<DN>] 
49 >        [dnattr=<attrname>]
50 >        [group[/<objectclass>[/<attrname>][.<basic-style>]]=<regex>]
51 >        [peername[.<basic-style>]=<regex>]
52 >        [sockname[.<basic-style>]=<regex>]
53 >        [domain[.<basic-style>]=<regex>]
54 >        [sockurl[.<basic-style>]=<regex>]
55 >        [set=<setspec>]
56 >        [aci=<attrname>]
57 >    <access> ::= [self]{<level>|<priv>}
58 >    <level> ::= none | disclose | auth | compare | search | read | write | manage
59 >    <priv> ::= {=|+|-}{m|w|r|s|c|x|d|0}+
60 >    <control> ::= [stop | continue | break]
61
62 where the <what> part selects the entries and/or attributes to which
63 the access applies, the {{EX:<who>}} part specifies which entities
64 are granted access, and the {{EX:<access>}} part specifies the
65 access granted. Multiple {{EX:<who> <access> <control>}} triplets
66 are supported, allowing many entities to be granted different access
67 to the same set of entries and attributes. Not all of these access
68 control options are described here; for more details see the
69 {{slapd.access}}(5) man page.
70
71
72 H3: What to control access to
73
74 The <what> part of an access specification determines the entries
75 and attributes to which the access control applies.  Entries are
76 commonly selected in two ways: by DN and by filter.  The following
77 qualifiers select entries by DN:
78
79 >    to *
80 >    to dn[.<basic-style>]=<regex>
81 >    to dn.<scope-style>=<DN>
82
83 The first form is used to select all entries.  The second form may
84 be used to select entries by matching a regular expression against
85 the target entry's {{normalized DN}}.   (The second form is not
86 discussed further in this document.)  The third form is used to
87 select entries which are within the requested scope of DN.  The
88 <DN> is a string representation of the Distinguished Name, as
89 described in {{REF:RFC4514}}.
90
91 The scope can be either {{EX:base}}, {{EX:one}}, {{EX:subtree}},
92 or {{EX:children}}.  Where {{EX:base}} matches only the entry with
93 provided DN, {{EX:one}} matches the entries whose parent is the
94 provided DN, {{EX:subtree}} matches all entries in the subtree whose
95 root is the provided DN, and {{EX:children}} matches all entries
96 under the DN (but not the entry named by the DN).
97
98 For example, if the directory contained entries named:
99
100 >    0: o=suffix
101 >    1: cn=Manager,o=suffix
102 >    2: ou=people,o=suffix
103 >    3: uid=kdz,ou=people,o=suffix
104 >    4: cn=addresses,uid=kdz,ou=people,o=suffix
105 >    5: uid=hyc,ou=people,o=suffix
106
107 \Then:
108 . {{EX:dn.base="ou=people,o=suffix"}} match 2;
109 . {{EX:dn.one="ou=people,o=suffix"}} match 3, and 5;
110 . {{EX:dn.subtree="ou=people,o=suffix"}} match 2, 3, 4, and 5; and
111 . {{EX:dn.children="ou=people,o=suffix"}} match 3, 4, and 5.
112
113
114 Entries may also be selected using a filter:
115
116 >    to filter=<ldap filter>
117
118 where <ldap filter> is a string representation of an LDAP
119 search filter, as described in {{REF:RFC4515}}.  For example:
120
121 >    to filter=(objectClass=person)
122
123 Note that entries may be selected by both DN and filter by
124 including both qualifiers in the <what> clause.
125
126 >    to dn.one="ou=people,o=suffix" filter=(objectClass=person)
127
128 Attributes within an entry are selected by including a comma-separated
129 list of attribute names in the <what> selector:
130
131 >    attrs=<attribute list>
132
133 A specific value of an attribute is selected by using a single
134 attribute name and also using a value selector:
135
136 >    attrs=<attribute> val[.<style>]=<regex>
137
138 There are two special {{pseudo}} attributes {{EX:entry}} and
139 {{EX:children}}.  To read (and hence return) a target entry, the
140 subject must have {{EX:read}} access to the target's {{entry}}
141 attribute.  To perform a search, the subject must have
142 {{EX:search}} access to the search base's {{entry}} attribute.
143 To add or delete an entry, the subject must have
144 {{EX:write}} access to the entry's {{EX:entry}} attribute AND must
145 have {{EX:write}} access to the entry's parent's {{EX:children}}
146 attribute.  To rename an entry, the subject must have {{EX:write}}
147 access to entry's {{EX:entry}} attribute AND have {{EX:write}}
148 access to both the old parent's and new parent's {{EX:children}}
149 attributes.  The complete examples at the end of this section should
150 help clear things up.
151
152 Lastly, there is a special entry selector {{EX:"*"}} that is used to
153 select any entry.  It is used when no other {{EX:<what>}}
154 selector has been provided.  It's equivalent to "{{EX:dn=.*}}"
155
156
157 H3: Who to grant access to
158
159 The <who> part identifies the entity or entities being granted
160 access. Note that access is granted to "entities" not "entries."
161 The following table summarizes entity specifiers:
162
163 !block table; align=Center; coltags="EX,N"; \
164     title="Table 6.3: Access Entity Specifiers"
165 Specifier|Entities
166 *|All, including anonymous and authenticated users
167 anonymous|Anonymous (non-authenticated) users
168 users|Authenticated users
169 self|User associated with target entry
170 dn[.<basic-style>]=<regex>|Users matching a regular expression
171 dn.<scope-style>=<DN>|Users within scope of a DN
172 !endblock
173
174 The DN specifier behaves much like <what> clause DN specifiers.
175
176 Other control factors are also supported.  For example, a {{EX:<who>}}
177 can be restricted by an entry listed in a DN-valued attribute in
178 the entry to which the access applies:
179
180 >    dnattr=<dn-valued attribute name>
181
182 The dnattr specification is used to give access to an entry
183 whose DN is listed in an attribute of the entry (e.g., give
184 access to a group entry to whoever is listed as the owner of
185 the group entry).
186
187 Some factors may not be appropriate in all environments (or any).
188 For example, the domain factor relies on IP to domain name lookups.
189 As these can easily be spoofed, the domain factor should be avoided.
190
191
192 H3: The access to grant
193
194 The kind of <access> granted can be one of the following:
195
196 !block table; colaligns="LRL"; coltags="EX,EX,N"; align=Center; \
197     title="Table 6.4: Access Levels"
198 Level        Privileges    Description
199 none        =0             no access
200 disclose    =d             needed for information disclosure on error
201 auth        =dx            needed to authenticate (bind)
202 compare     =cdx           needed to compare
203 search      =scdx          needed to apply search filters
204 read        =rscdx         needed to read search results
205 write       =wrscdx        needed to modify/rename
206 manage      =mwrscdx       needed to manage
207 !endblock
208
209 Each level implies all lower levels of access. So, for example,
210 granting someone {{EX:write}} access to an entry also grants them
211 {{EX:read}}, {{EX:search}}, {{EX:compare}}, {{EX:auth}} and
212 {{EX:disclose}} access.  However, one may use the privileges specifier
213 to grant specific permissions.
214
215
216 H3: Access Control Evaluation
217
218 When evaluating whether some requester should be given access to
219 an entry and/or attribute, slapd compares the entry and/or attribute
220 to the {{EX:<what>}} selectors given in the configuration file.
221 For each entry, access controls provided in the database which holds
222 the entry (or the global access directives if not held in any database) apply
223 first, followed by the global access directives. However, when dealing with 
224 an access list, because the global access list is effectively appended 
225 to each per-database list, if the resulting list is non-empty then the 
226 access list will end with an implicit {{EX:access to * by * none}} directive. 
227 If there are no access directives applicable to a backend, then a default 
228 read is used.
229
230 Within this
231 priority, access directives are examined in the order in which they
232 appear in the config file.  Slapd stops with the first {{EX:<what>}}
233 selector that matches the entry and/or attribute. The corresponding
234 access directive is the one slapd will use to evaluate access.
235
236 Next, slapd compares the entity requesting access to the {{EX:<who>}}
237 selectors within the access directive selected above in the order
238 in which they appear. It stops with the first {{EX:<who>}} selector
239 that matches the requester. This determines the access the entity
240 requesting access has to the entry and/or attribute.
241
242 Finally, slapd compares the access granted in the selected
243 {{EX:<access>}} clause to the access requested by the client. If
244 it allows greater or equal access, access is granted. Otherwise,
245 access is denied.
246
247 The order of evaluation of access directives makes their placement
248 in the configuration file important. If one access directive is
249 more specific than another in terms of the entries it selects, it
250 should appear first in the config file. Similarly, if one {{EX:<who>}}
251 selector is more specific than another it should come first in the
252 access directive. The access control examples given below should
253 help make this clear.
254
255
256
257 H3: Access Control Examples
258
259 The access control facility described above is quite powerful.  This
260 section shows some examples of its use for descriptive purposes.
261
262 A simple example:
263
264 >    access to * by * read
265
266 This access directive grants read access to everyone.
267
268 >    access to *
269 >        by self write
270 >        by anonymous auth
271 >        by * read
272
273 This directive allows the user to modify their entry, allows anonymous
274 to authentication against these entries, and allows all others to
275 read these entries.  Note that only the first {{EX:by <who>}} clause
276 which matches applies.  Hence, the anonymous users are granted
277 {{EX:auth}}, not {{EX:read}}.  The last clause could just as well
278 have been "{{EX:by users read}}".
279
280 It is often desirable to restrict operations based upon the level
281 of protection in place.  The following shows how security strength
282 factors (SSF) can be used.
283
284 >    access to *
285 >        by ssf=128 self write
286 >        by ssf=64 anonymous auth
287 >        by ssf=64 users read
288
289 This directive allows users to modify their own entries if security
290 protections have of strength 128 or better have been established,
291 allows authentication access to anonymous users, and read access
292 when 64 or better security protections have been established.  If
293 client has not establish sufficient security protections, the
294 implicit {{EX:by * none}} clause would be applied.
295
296 The following example shows the use of a style specifiers to select
297 the entries by DN in two access directives where ordering is
298 significant.
299
300 >    access to dn.children="dc=example,dc=com"
301 >         by * search
302 >    access to dn.children="dc=com"
303 >         by * read
304
305 Read access is granted to entries under the {{EX:dc=com}} subtree,
306 except for those entries under the {{EX:dc=example,dc=com}} subtree,
307 to which search access is granted.  No access is granted to
308 {{EX:dc=com}} as neither access directive matches this DN.  If the
309 order of these access directives was reversed, the trailing directive
310 would never be reached, since all entries under {{EX:dc=example,dc=com}}
311 are also under {{EX:dc=com}} entries.
312
313 Also note that if no {{EX:access to}} directive matches or no {{EX:by
314 <who>}} clause, {{B:access is denied}}.  That is, every {{EX:access
315 to}} directive ends with an implicit {{EX:by * none}} clause. When dealing
316 with an access list, because the global access list is effectively appended 
317 to each per-database list, if the resulting list is non-empty then the access 
318 list will end with an implicit {{EX:access to * by * none}} directive. If
319 there are no access directives applicable to a backend, then a default read is
320 used.
321
322 The next example again shows the importance of ordering, both of
323 the access directives and the {{EX:by <who>}} clauses.  It also
324 shows the use of an attribute selector to grant access to a specific
325 attribute and various {{EX:<who>}} selectors.
326
327 >    access to dn.subtree="dc=example,dc=com" attrs=homePhone
328 >        by self write
329 >        by dn.children="dc=example,dc=com" search
330 >        by peername.regex=IP:10\..+ read
331 >    access to dn.subtree="dc=example,dc=com"
332 >        by self write
333 >        by dn.children="dc=example,dc=com" search
334 >        by anonymous auth
335
336 This example applies to entries in the "{{EX:dc=example,dc=com}}"
337 subtree. To all attributes except {{EX:homePhone}}, an entry can
338 write to itself, entries under {{EX:example.com}} entries can search
339 by them, anybody else has no access (implicit {{EX:by * none}})
340 excepting for authentication/authorization (which is always done
341 anonymously).  The {{EX:homePhone}} attribute is writable by the
342 entry, searchable by entries under {{EX:example.com}}, readable by
343 clients connecting from network 10, and otherwise not readable
344 (implicit {{EX:by * none}}).  All other access is denied by the
345 implicit {{EX:access to * by * none}}.
346
347 Sometimes it is useful to permit a particular DN to add or
348 remove itself from an attribute. For example, if you would like to
349 create a group and allow people to add and remove only
350 their own DN from the member attribute, you could accomplish
351 it with an access directive like this:
352
353 >    access to attrs=member,entry
354 >         by dnattr=member selfwrite
355
356 The dnattr {{EX:<who>}} selector says that the access applies to
357 entries listed in the {{EX:member}} attribute. The {{EX:selfwrite}} access
358 selector says that such members can only add or delete their
359 own DN from the attribute, not other values. The addition of
360 the entry attribute is required because access to the entry is
361 required to access any of the entry's attributes.
362
363 !if 0
364 For more details on how to use the {{EX:access}} directive,
365 consult the {{Advanced Access Control}} chapter.
366 !endif
367
368
369 H2: Access Control via Dynamic Configuration
370
371 Access to slapd entries and attributes is controlled by the
372 olcAccess attribute, whose values are a sequence of access directives.
373 The general form of the olcAccess configuration is:
374
375 >    olcAccess: <access directive>
376 >    <access directive> ::= to <what>
377 >        [by <who> [<access>] [<control>] ]+
378 >    <what> ::= * |
379 >        [dn[.<basic-style>]=<regex> | dn.<scope-style>=<DN>]
380 >        [filter=<ldapfilter>] [attrs=<attrlist>]
381 >    <basic-style> ::= regex | exact
382 >    <scope-style> ::= base | one | subtree | children
383 >    <attrlist> ::= <attr> [val[.<basic-style>]=<regex>] | <attr> , <attrlist>
384 >    <attr> ::= <attrname> | entry | children
385 >    <who> ::= * | [anonymous | users | self
386 >            | dn[.<basic-style>]=<regex> | dn.<scope-style>=<DN>] 
387 >        [dnattr=<attrname>]
388 >        [group[/<objectclass>[/<attrname>][.<basic-style>]]=<regex>]
389 >        [peername[.<basic-style>]=<regex>]
390 >        [sockname[.<basic-style>]=<regex>]
391 >        [domain[.<basic-style>]=<regex>]
392 >        [sockurl[.<basic-style>]=<regex>]
393 >        [set=<setspec>]
394 >        [aci=<attrname>]
395 >    <access> ::= [self]{<level>|<priv>}
396 >    <level> ::= none | disclose | auth | compare | search | read | write | manage
397 >    <priv> ::= {=|+|-}{m|w|r|s|c|x|d|0}+
398 >    <control> ::= [stop | continue | break]
399
400 where the <what> part selects the entries and/or attributes to which
401 the access applies, the {{EX:<who>}} part specifies which entities
402 are granted access, and the {{EX:<access>}} part specifies the
403 access granted. Multiple {{EX:<who> <access> <control>}} triplets
404 are supported, allowing many entities to be granted different access
405 to the same set of entries and attributes. Not all of these access
406 control options are described here; for more details see the
407 {{slapd.access}}(5) man page.
408
409
410 H3: What to control access to
411
412 The <what> part of an access specification determines the entries
413 and attributes to which the access control applies.  Entries are
414 commonly selected in two ways: by DN and by filter.  The following
415 qualifiers select entries by DN:
416
417 >    to *
418 >    to dn[.<basic-style>]=<regex>
419 >    to dn.<scope-style>=<DN>
420
421 The first form is used to select all entries.  The second form may
422 be used to select entries by matching a regular expression against
423 the target entry's {{normalized DN}}.   (The second form is not
424 discussed further in this document.)  The third form is used to
425 select entries which are within the requested scope of DN.  The
426 <DN> is a string representation of the Distinguished Name, as
427 described in {{REF:RFC4514}}.
428
429 The scope can be either {{EX:base}}, {{EX:one}}, {{EX:subtree}},
430 or {{EX:children}}.  Where {{EX:base}} matches only the entry with
431 provided DN, {{EX:one}} matches the entries whose parent is the
432 provided DN, {{EX:subtree}} matches all entries in the subtree whose
433 root is the provided DN, and {{EX:children}} matches all entries
434 under the DN (but not the entry named by the DN).
435
436 For example, if the directory contained entries named:
437
438 >    0: o=suffix
439 >    1: cn=Manager,o=suffix
440 >    2: ou=people,o=suffix
441 >    3: uid=kdz,ou=people,o=suffix
442 >    4: cn=addresses,uid=kdz,ou=people,o=suffix
443 >    5: uid=hyc,ou=people,o=suffix
444
445 \Then:
446 . {{EX:dn.base="ou=people,o=suffix"}} match 2;
447 . {{EX:dn.one="ou=people,o=suffix"}} match 3, and 5;
448 . {{EX:dn.subtree="ou=people,o=suffix"}} match 2, 3, 4, and 5; and
449 . {{EX:dn.children="ou=people,o=suffix"}} match 3, 4, and 5.
450
451
452 Entries may also be selected using a filter:
453
454 >    to filter=<ldap filter>
455
456 where <ldap filter> is a string representation of an LDAP
457 search filter, as described in {{REF:RFC4515}}.  For example:
458
459 >    to filter=(objectClass=person)
460
461 Note that entries may be selected by both DN and filter by
462 including both qualifiers in the <what> clause.
463
464 >    to dn.one="ou=people,o=suffix" filter=(objectClass=person)
465
466 Attributes within an entry are selected by including a comma-separated
467 list of attribute names in the <what> selector:
468
469 >    attrs=<attribute list>
470
471 A specific value of an attribute is selected by using a single
472 attribute name and also using a value selector:
473
474 >    attrs=<attribute> val[.<style>]=<regex>
475
476 There are two special {{pseudo}} attributes {{EX:entry}} and
477 {{EX:children}}.  To read (and hence return) a target entry, the
478 subject must have {{EX:read}} access to the target's {{entry}}
479 attribute.  To perform a search, the subject must have
480 {{EX:search}} access to the search base's {{entry}} attribute.
481 To add or delete an entry, the subject must have
482 {{EX:write}} access to the entry's {{EX:entry}} attribute AND must
483 have {{EX:write}} access to the entry's parent's {{EX:children}}
484 attribute.  To rename an entry, the subject must have {{EX:write}}
485 access to entry's {{EX:entry}} attribute AND have {{EX:write}}
486 access to both the old parent's and new parent's {{EX:children}}
487 attributes.  The complete examples at the end of this section should
488 help clear things up.
489
490 Lastly, there is a special entry selector {{EX:"*"}} that is used to
491 select any entry.  It is used when no other {{EX:<what>}}
492 selector has been provided.  It's equivalent to "{{EX:dn=.*}}"
493
494
495 H3: Who to grant access to
496
497 The <who> part identifies the entity or entities being granted
498 access. Note that access is granted to "entities" not "entries."
499 The following table summarizes entity specifiers:
500
501 !block table; align=Center; coltags="EX,N"; \
502     title="Table 5.3: Access Entity Specifiers"
503 Specifier|Entities
504 *|All, including anonymous and authenticated users
505 anonymous|Anonymous (non-authenticated) users
506 users|Authenticated users
507 self|User associated with target entry
508 dn[.<basic-style>]=<regex>|Users matching a regular expression
509 dn.<scope-style>=<DN>|Users within scope of a DN
510 !endblock
511
512 The DN specifier behaves much like <what> clause DN specifiers.
513
514 Other control factors are also supported.  For example, a {{EX:<who>}}
515 can be restricted by an entry listed in a DN-valued attribute in
516 the entry to which the access applies:
517
518 >    dnattr=<dn-valued attribute name>
519
520 The dnattr specification is used to give access to an entry
521 whose DN is listed in an attribute of the entry (e.g., give
522 access to a group entry to whoever is listed as the owner of
523 the group entry).
524
525 Some factors may not be appropriate in all environments (or any).
526 For example, the domain factor relies on IP to domain name lookups.
527 As these can easily be spoofed, the domain factor should be avoided.
528
529
530 H3: The access to grant
531
532 The kind of <access> granted can be one of the following:
533
534 !block table; colaligns="LRL"; coltags="EX,EX,N"; align=Center; \
535     title="Table 5.4: Access Levels"
536 Level        Privileges    Description
537 none         =0            no access
538 disclose     =d            needed for information disclosure on error
539 auth         =dx           needed to authenticate (bind)
540 compare      =cdx          needed to compare
541 search       =scdx         needed to apply search filters
542 read         =rscdx        needed to read search results
543 write        =wrscdx       needed to modify/rename
544 manage       =mwrscdx      needed to manage
545 !endblock
546
547 Each level implies all lower levels of access. So, for example,
548 granting someone {{EX:write}} access to an entry also grants them
549 {{EX:read}}, {{EX:search}}, {{EX:compare}}, {{EX:auth}} and
550 {{EX:disclose}} access.  However, one may use the privileges specifier
551 to grant specific permissions.
552
553
554 H3: Access Control Evaluation
555
556 When evaluating whether some requester should be given access to
557 an entry and/or attribute, slapd compares the entry and/or attribute
558 to the {{EX:<what>}} selectors given in the configuration.  For
559 each entry, access controls provided in the database which holds
560 the entry (or the global access directives if not held in any database) apply
561 first, followed by the global access directives (which are held in
562 the {{EX:frontend}} database definition). However, when dealing with 
563 an access list, because the global access list is effectively appended 
564 to each per-database list, if the resulting list is non-empty then the 
565 access list will end with an implicit {{EX:access to * by * none}} directive. 
566 If there are no access directives applicable to a backend, then a default 
567 read is used.
568
569 Within this priority,
570 access directives are examined in the order in which they appear
571 in the configuration attribute.  Slapd stops with the first
572 {{EX:<what>}} selector that matches the entry and/or attribute. The
573 corresponding access directive is the one slapd will use to evaluate
574 access.
575
576 Next, slapd compares the entity requesting access to the {{EX:<who>}}
577 selectors within the access directive selected above in the order
578 in which they appear. It stops with the first {{EX:<who>}} selector
579 that matches the requester. This determines the access the entity
580 requesting access has to the entry and/or attribute.
581
582 Finally, slapd compares the access granted in the selected
583 {{EX:<access>}} clause to the access requested by the client. If
584 it allows greater or equal access, access is granted. Otherwise,
585 access is denied.
586
587 The order of evaluation of access directives makes their placement
588 in the configuration file important. If one access directive is
589 more specific than another in terms of the entries it selects, it
590 should appear first in the configuration. Similarly, if one {{EX:<who>}}
591 selector is more specific than another it should come first in the
592 access directive. The access control examples given below should
593 help make this clear.
594
595
596
597 H3: Access Control Examples
598
599 The access control facility described above is quite powerful.  This
600 section shows some examples of its use for descriptive purposes.
601
602 A simple example:
603
604 >    olcAccess: to * by * read
605
606 This access directive grants read access to everyone.
607
608 >    olcAccess: to *
609 >        by self write
610 >        by anonymous auth
611 >        by * read
612
613 This directive allows the user to modify their entry, allows anonymous
614 to authenticate against these entries, and allows all others to
615 read these entries.  Note that only the first {{EX:by <who>}} clause
616 which matches applies.  Hence, the anonymous users are granted
617 {{EX:auth}}, not {{EX:read}}.  The last clause could just as well
618 have been "{{EX:by users read}}".
619
620 It is often desirable to restrict operations based upon the level
621 of protection in place.  The following shows how security strength
622 factors (SSF) can be used.
623
624 >    olcAccess: to *
625 >        by ssf=128 self write
626 >        by ssf=64 anonymous auth
627 >        by ssf=64 users read
628
629 This directive allows users to modify their own entries if security
630 protections of strength 128 or better have been established,
631 allows authentication access to anonymous users, and read access
632 when strength 64 or better security protections have been established.  If
633 the client has not establish sufficient security protections, the
634 implicit {{EX:by * none}} clause would be applied.
635
636 The following example shows the use of style specifiers to select
637 the entries by DN in two access directives where ordering is
638 significant.
639
640 >    olcAccess: to dn.children="dc=example,dc=com"
641 >         by * search
642 >    olcAccess: to dn.children="dc=com"
643 >         by * read
644
645 Read access is granted to entries under the {{EX:dc=com}} subtree,
646 except for those entries under the {{EX:dc=example,dc=com}} subtree,
647 to which search access is granted.  No access is granted to
648 {{EX:dc=com}} as neither access directive matches this DN.  If the
649 order of these access directives was reversed, the trailing directive
650 would never be reached, since all entries under {{EX:dc=example,dc=com}}
651 are also under {{EX:dc=com}} entries.
652
653 Also note that if no {{EX:olcAccess: to}} directive matches or no {{EX:by
654 <who>}} clause, {{B:access is denied}}.  When dealing with an access list, 
655 because the global access list is effectively appended to each per-database 
656 list, if the resulting list is non-empty then the access list will end with 
657 an implicit {{EX:access to * by * none}} directive. If there are no access 
658 directives applicable to a backend, then a default read is used.
659
660 The next example again shows the importance of ordering, both of
661 the access directives and the {{EX:by <who>}} clauses.  It also
662 shows the use of an attribute selector to grant access to a specific
663 attribute and various {{EX:<who>}} selectors.
664
665 >    olcAccess: to dn.subtree="dc=example,dc=com" attrs=homePhone
666 >        by self write
667 >        by dn.children=dc=example,dc=com" search
668 >        by peername.regex=IP:10\..+ read
669 >    olcAccess: to dn.subtree="dc=example,dc=com"
670 >        by self write
671 >        by dn.children="dc=example,dc=com" search
672 >        by anonymous auth
673
674 This example applies to entries in the "{{EX:dc=example,dc=com}}"
675 subtree. To all attributes except {{EX:homePhone}}, an entry can
676 write to itself, entries under {{EX:example.com}} entries can search
677 by them, anybody else has no access (implicit {{EX:by * none}})
678 excepting for authentication/authorization (which is always done
679 anonymously).  The {{EX:homePhone}} attribute is writable by the
680 entry, searchable by entries under {{EX:example.com}}, readable by
681 clients connecting from network 10, and otherwise not readable
682 (implicit {{EX:by * none}}).  All other access is denied by the
683 implicit {{EX:access to * by * none}}.
684
685 Sometimes it is useful to permit a particular DN to add or
686 remove itself from an attribute. For example, if you would like to
687 create a group and allow people to add and remove only
688 their own DN from the member attribute, you could accomplish
689 it with an access directive like this:
690
691 >    olcAccess: to attrs=member,entry
692 >         by dnattr=member selfwrite
693
694 The dnattr {{EX:<who>}} selector says that the access applies to
695 entries listed in the {{EX:member}} attribute. The {{EX:selfwrite}} access
696 selector says that such members can only add or delete their
697 own DN from the attribute, not other values. The addition of
698 the entry attribute is required because access to the entry is
699 required to access any of the entry's attributes.
700
701
702
703 H3: Access Control Ordering
704
705 Since the ordering of {{EX:olcAccess}} directives is essential to their
706 proper evaluation, but LDAP attributes normally do not preserve the
707 ordering of their values, OpenLDAP uses a custom schema extension to
708 maintain a fixed ordering of these values. This ordering is maintained
709 by prepending a {{EX:"{X}"}} numeric index to each value, similarly to
710 the approach used for ordering the configuration entries. These index
711 tags are maintained automatically by slapd and do not need to be specified
712 when originally defining the values. For example, when you create the
713 settings
714
715 >    olcAccess: to attrs=member,entry
716 >         by dnattr=member selfwrite
717 >    olcAccess: to dn.children="dc=example,dc=com"
718 >         by * search
719 >    olcAccess: to dn.children="dc=com"
720 >         by * read
721
722 when you read them back using slapcat or ldapsearch they will contain
723
724 >    olcAccess: {0}to attrs=member,entry
725 >         by dnattr=member selfwrite
726 >    olcAccess: {1}to dn.children="dc=example,dc=com"
727 >         by * search
728 >    olcAccess: {2}to dn.children="dc=com"
729 >         by * read
730
731 The numeric index may be used to specify a particular value to change
732 when using ldapmodify to edit the access rules. This index can be used
733 instead of (or in addition to) the actual access value. Using this 
734 numeric index is very helpful when multiple access rules are being managed.
735
736 For example, if we needed to change the second rule above to grant
737 write access instead of search, we could try this LDIF:
738
739 >    changetype: modify
740 >    delete: olcAccess
741 >    olcAccess: to dn.children="dc=example,dc=com" by * search
742 >    -
743 >    add: olcAccess
744 >    olcAccess: to dn.children="dc=example,dc=com" by * write
745 >    -
746
747 But this example {{B:will not}} guarantee that the existing values remain in
748 their original order, so it will most likely yield a broken security
749 configuration. Instead, the numeric index should be used:
750
751 >    changetype: modify
752 >    delete: olcAccess
753 >    olcAccess: {1}
754 >    -
755 >    add: olcAccess
756 >    olcAccess: {1}to dn.children="dc=example,dc=com" by * write
757 >    -
758
759 This example deletes whatever rule is in value #1 of the {{EX:olcAccess}}
760 attribute (regardless of its value) and adds a new value that is
761 explicitly inserted as value #1. The result will be
762
763 >    olcAccess: {0}to attrs=member,entry
764 >         by dnattr=member selfwrite
765 >    olcAccess: {1}to dn.children="dc=example,dc=com"
766 >         by * write
767 >    olcAccess: {2}to dn.children="dc=com"
768 >         by * read
769
770 which is exactly what was intended.
771
772 !if 0
773 For more details on how to use the {{EX:access}} directive,
774 consult the {{Advanced Access Control}} chapter.
775 !endif
776
777
778 H2: Access Control Common Examples
779
780 H3: Basic ACLs
781
782 Generally one should start with some basic ACLs such as:
783
784 >    access to attr=userPassword
785 >        by self =xw
786 >        by anonymous auth
787 >        by * none
788 >
789 >
790 >      access to *
791 >        by self write
792 >        by users read
793 >        by * none
794
795 The first ACL allows users to update (but not read) their passwords, anonymous 
796 users to authenticate against this attribute, and (implicitly) denying all 
797 access to others.
798
799 The second ACL allows users full access to their entry, authenticated users read 
800 access to anything, and (implicitly) denying all access to others (in this case, 
801 anonymous users). 
802
803
804 H3: Matching Anonymous and Authenticated users
805
806 An anonymous user has a empty DN. While the {{dn.exact=""}} or {{dn.regex="^$"}}
807  could be used, {{slapd}}(8)) offers an anonymous shorthand which should be 
808 used instead.
809
810 >    access to *
811 >      by anonymous none
812 >      by * read
813
814 denies all access to anonymous users while granting others read. 
815
816 Authenticated users have a subject DN. While {{dn.regex=".+"}} will match any 
817 authenticated user, OpenLDAP provides the users short hand which should be used 
818 instead.
819
820 >    access to *
821 >      by users read
822 >      by * none
823
824 This ACL grants read permissions to authenticated users while denying others 
825 (i.e.: anonymous users).
826
827
828 H3: Controlling rootdn access
829
830 You could specify the {{rootdn}} in {{slapd.conf}}(5) or {{slapd.d}} without 
831 specifying a {{rootpw}}. Then you have to add an actual directory entry with 
832 the same dn, e.g.:
833
834 >    dn: cn=Manager,o=MyOrganization
835 >    cn: Manager
836 >    sn: Manager
837 >    objectClass: person
838 >    objectClass: top
839 >    userPassword: {SSHA}someSSHAdata
840
841 Then binding as the {{rootdn}} will require a regular bind to that DN, which 
842 in turn requires auth access to that entry's DN and {{userPassword}}, and this 
843 can be restricted via ACLs. E.g.:
844
845 >    access to dn.base="cn=Manager,o=MyOrganization"
846 >      by peername.regex=127\.0\.0\.1 auth
847 >      by peername.regex=192\.168\.0\..* auth
848 >      by users none
849 >      by * none
850
851 The ACLs above will only allow binding using rootdn from localhost and 
852 192.168.0.0/24.
853
854
855 H3: Managing access with Groups
856
857 There are a few ways to do this. One approach is illustrated here. Consider the 
858 following DIT layout:
859
860 >    +-dc=example,dc=com
861 >    +---cn=administrators,dc=example,dc=com
862 >    +---cn=fred blogs,dc=example,dc=com 
863
864 and the following group object (in LDIF format):
865
866 >    dn: cn=administrators,dc=example,dc=com
867 >    cn: administrators of this region
868 >    objectclass: groupOfNames  (important for the group acl feature)
869 >    member: cn=fred blogs,dc=example,dc=com 
870 >    member: cn=somebody else,dc=example,dc=com
871
872 One can then grant access to the members of this this group by adding appropriate 
873 {{by group}} clause to an access directive in {{slapd.conf}}(5). For instance,
874
875 >    access to dn.children="dc=example,dc=com" 
876 >        by self write 
877 >        by group.exact="cn=Administrators,dc=example,dc=com" write  
878 >        by * auth
879
880 Like by {{dn}} clauses, one can also use {{expand}} to expand the group name 
881 based upon the regular expression matching of the target, that is, the to {{dn.regex}}). 
882 For instance,
883
884 >    access to dn.regex="(.+,)?ou=People,(dc=[^,]+,dc=[^,]+)$"
885 >             attrs=children,entry,uid
886 >        by group.expand="cn=Managers,$2" write
887 >        by users read
888 >        by * auth
889
890
891 The above illustration assumed that the group members are to be found in the 
892 {{member}} attribute type of the {{groupOfNames}} object class. If you need to 
893 use a different group object and/or a different attribute type then use the 
894 following {{slapd.conf}}(5) (abbreviated) syntax:
895
896 >    access to <what>
897 >            by group/<objectclass>/<attributename>=<DN> <access>
898
899 For example:
900
901 >    access to *
902 >      by group/organizationalRole/roleOccupant="cn=Administrator,dc=example,dc=com" write
903
904 In this case, we have an ObjectClass {{organizationalRole}} which contains the 
905 administrator DN's in the {{roleOccupant}} attribute. For instance:
906
907 >    dn: cn=Administrator,dc=example,dc=com
908 >    cn: Administrator
909 >    objectclass: organizationalRole
910 >    roleOccupant: cn=Jane Doe,dc=example,dc=com 
911
912 Note: the specified member attribute type MUST be of DN or {{NameAndOptionalUID}} syntax, 
913 and the specified object class SHOULD allow the attribute type.
914
915 Dynamic Groups are also supported in Access Control. Please see {{slapo-dynlist}}(5)
916 and the {{SECT:Dynamic Lists}} overlay section.
917
918
919 H3:  Granting access to a subset of attributes
920
921 You can grant access to a set of attributes by specifying a list of attribute names 
922 in the ACL {{to}} clause. To be useful, you also need to grant access to the 
923 {{entry}} itself. Also note how {{children}} controls the ability to add, delete, 
924 and rename entries.
925
926 >    # mail: self may write, authenticated users may read
927 >    access to attrs=mail
928 >      by self write
929 >      by users read
930 >      by * none
931 >    
932 >    # cn, sn: self my write, all may read
933 >    access to attrs=cn,sn
934 >      by self write
935 >      by * read
936 >    
937 >    # immediate children: only self can add/delete entries under this entry
938 >    access to attrs=children
939 >      by self write
940 >    
941 >    # entry itself: self may write, all may read
942 >    access to attrs=entry
943 >      by self write
944 >      by * read
945 >    
946 >    # other attributes: self may write, others have no access
947 >    access to *
948 >      by self write
949 >      by * none
950
951 ObjectClass names may also be specified in this list, which will affect 
952 all the attributes that are required and/or allowed by that {{objectClass}}. 
953 Actually, names in {{attrlist}} that are prefixed by {{@}} are directly treated 
954 as objectClass names. A name prefixed by {{!}} is also treated as an objectClass, 
955 but in this case the access rule affects the attributes that are not required 
956 nor allowed by that {{objectClass}}. 
957
958
959 H3: Allowing a user write to all entries below theirs
960
961 For a setup where a user can write to its own record and to all of its children:
962
963 >    access to dn.regex="(.+,)?(uid=[^,]+,o=Company)$"
964 >       by dn.exact,expand="$2" write
965 >       by anonymous auth
966
967 (Add more examples for above)
968
969
970 H3: Allowing entry creation
971
972 Let's say, you have it like this:
973
974 >        o=<basedn>
975 >            ou=domains
976 >                associatedDomain=<somedomain>
977 >                    ou=users
978 >                        uid=<someuserid>            
979 >                        uid=<someotheruserid>
980 >                    ou=addressbooks
981 >                        uid=<someuserid>
982 >                            cn=<someone>
983 >                            cn=<someoneelse>
984
985 and, for another domain <someotherdomain>:
986
987 >        o=<basedn>
988 >            ou=domains
989 >                associatedDomain=<someotherdomain>
990 >                    ou=users
991 >                        uid=<someuserid>            
992 >                        uid=<someotheruserid>
993 >                    ou=addressbooks
994 >                        uid=<someotheruserid>
995 >                            cn=<someone>
996 >                            cn=<someoneelse>
997
998 then, if you wanted user {{uid=<someuserid>}} to {{B:ONLY}} create an entry 
999 for its own thing, you could write an ACL like this:
1000
1001 >    # this rule lets users of "associatedDomain=<matcheddomain>"
1002 >    # write under "ou=addressbook,associatedDomain=<matcheddomain>,ou=domains,o=<basedn>",
1003 >    # i.e. a user can write ANY entry below its domain's address book;
1004 >    # this permission is necessary, but not sufficient, the next 
1005 >    # will restrict this permission further
1006 >    
1007 >    
1008 >    access to dn.regex="^ou=addressbook,associatedDomain=([^,]+),ou=domains,o=<basedn>$" attrs=children
1009 >            by dn.regex="^uid=([^,]+),ou=users,associatedDomain=$1,ou=domains,o=<basedn>$$" write
1010 >            by * none
1011 >    
1012 >    
1013 >    # Note that above the "by" clause needs a "regex" style to make sure
1014 >    # it expands to a DN that starts with a "uid=<someuserid>" pattern
1015 >    # while substituting the associatedDomain submatch from the "what" clause.
1016 >    
1017 >    
1018 >    # This rule lets a user with "uid=<matcheduid>" of "<associatedDomain=matcheddomain>"
1019 >    # write (i.e. add, modify, delete) the entry whose DN is exactly
1020 >    # "uid=<matcheduid>,ou=addressbook,associatedDomain=<matcheddomain>,ou=domains,o=<basedn>"
1021 >    # and ANY entry as subtree of it
1022 >    
1023 >    
1024 >    access to dn.regex="^(.+,)?uid=([^,]+),ou=addressbook,associatedDomain=([^,]+),ou=domains,o=<basedn>$"
1025 >            by dn.exact,expand="uid=$2,ou=users,associatedDomain=$3,ou=domains,o=<basedn>" write
1026 >            by * none 
1027 >    
1028 >    
1029 >    # Note that above the "by" clause uses the "exact" style with the "expand"
1030 >    # modifier because now the whole pattern can be rebuilt by means of the
1031 >    # submatches from the "what" clause, so a "regex" compilation and evaluation
1032 >    # is no longer required.
1033
1034
1035 H3: Tips for using regular expressions in Access Control 
1036
1037 Always use {{dn.regex=<pattern>}} when you intend to use regular expression 
1038 matching. {{dn=<pattern>}} alone defaults to {{dn.exact<pattern>}}.
1039
1040 Use {{(.+)}} instead of {{(.*)}} when you want at least one char to be matched. 
1041 {{(.*)}} matches the empty string as well.
1042
1043 Don't use regular expressions for matches that can be done otherwise in a safer 
1044 and cheaper manner. Examples:
1045
1046 >    dn.regex=".*dc=example,dc=com"
1047
1048 is unsafe and expensive:
1049
1050     * unsafe because any string containing {{dc=example,dc=com }}will match, 
1051 not only those that end with the desired pattern; use {{.*dc=example,dc=com$}} instead.
1052     * unsafe also because it would allow any {{attributeType}} ending with {{dc}}
1053  as naming attribute for the first RDN in the string, e.g. a custom attributeType 
1054 {{mydc}} would match as well. If you really need a regular expression that allows 
1055 just {{dc=example,dc=com}} or any of its subtrees, use {{^(.+,)?dc=example,dc=com$}}, 
1056 which means: anything to the left of dc=..., if any (the question mark after the 
1057 pattern within brackets), must end with a comma;
1058     * expensive because if you don't need submatches, you could use scoping styles, e.g.
1059
1060 >    dn.subtree="dc=example,dc=com"
1061
1062 to include {{dc=example,dc=com}} in the matching patterns,
1063
1064 >    dn.children="dc=example,dc=com"
1065
1066 to exclude {{dc=example,dc=com}} from the matching patterns, or
1067
1068 >    dn.onelevel="dc=example,dc=com"
1069
1070 to allow exactly one sublevel matches only. 
1071
1072 Always use {{^}} and {{$}} in regexes, whenever appropriate, because 
1073 {{ou=(.+),ou=(.+),ou=addressbooks,o=basedn}} will match 
1074 {{something=bla,ou=xxx,ou=yyy,ou=addressbooks,o=basedn,ou=addressbooks,o=basedn,dc=some,dc=org}}
1075
1076 Always use {{([^,]+)}} to indicate exactly one RDN, because {{(.+)}} can 
1077 include any number of RDNs; e.g. {{ou=(.+),dc=example,dc=com}} will match 
1078 {{ou=My,o=Org,dc=example,dc=com}}, which might not be what you want.
1079
1080 Never add the rootdn to the by clauses. ACLs are not even processed for operations 
1081 performed with rootdn identity (otherwise there would be no reason to define a 
1082 rootdn at all).
1083
1084 Use shorthands. The user directive matches authenticated users and the anonymous
1085 directive matches anonymous users.
1086
1087 Don't use the {{dn.regex}} form for <by> clauses if all you need is scoping 
1088 and/or substring replacement; use scoping styles (e.g. {{exact}}, {{onelevel}}, 
1089 {{children}} or {{subtree}}) and the style modifier expand to cause substring expansion.
1090
1091 For instance,
1092
1093 >    access to dn.regex=".+,dc=([^,]+),dc=([^,]+)$"
1094 >      by dn.regex="^[^,],ou=Admin,dc=$1,dc=$2$$" write
1095
1096 although correct, can be safely and efficiently replaced by
1097
1098 >    access to dn.regex=".+,(dc=[^,]+,dc=[^,]+)$"
1099 >      by dn.onelevel,expand="ou=Admin,$1" write
1100
1101 where the regex in the {{<what>}} clause is more compact, and the one in the {{<by>}} 
1102 clause is replaced by a much more efficient scoping style of onelevel with substring expansion. 
1103
1104
1105 H3: Granting and Denying access based on security strength factors (ssf)
1106
1107 You can restrict access based on the security strength factor (SSF)
1108
1109 >    access to dn="cn=example,cn=edu"
1110 >          by * ssf=256 read
1111
1112 0 (zero) implies no protection,
1113 1 implies integrity protection only,
1114 56 DES or other weak ciphers,
1115 112 triple DES and other strong ciphers,
1116 128 RC4, Blowfish and other modern strong ciphers.
1117
1118 Other possibilities:
1119
1120 >    transport_ssf=<n>
1121 >    tls_ssf=<n>
1122 >    sasl_ssf=<n>
1123
1124 256 is recommended.
1125
1126 See {{slapd.conf}}(5) for information on {{ssf}}.
1127
1128
1129 H3: When things aren't working as expected
1130
1131 Consider this example:
1132
1133 >    access to *
1134 >      by anonymous auth
1135 >    
1136 >    access to *
1137 >      by self write
1138 >    
1139 >    access to *
1140 >      by users read 
1141
1142 You may think this will allow any user to login, to read everything and change 
1143 his own data if he is logged in. But in this example only the login works and 
1144 an ldapsearch returns no data. The Problem is that SLAPD goes through its access 
1145 config line by line and stops as soon as it finds a match in the part of the 
1146 access rule.(here: {{to *}})
1147
1148 To get what we wanted the file has to read:
1149
1150 >    access to *
1151 >      by anonymous auth
1152 >      by self write
1153 >      by users read 
1154
1155 The general rule is: "special access rules first, generic access rules last"
1156
1157 See also {{slapd.access}}(5), loglevel 128 and {{slapacl}}(8) for debugging
1158 information.
1159
1160
1161 H2: Sets - Granting rights based on relationships
1162
1163 Sets are best illustrated via examples. The following sections will present 
1164 a few set ACL examples in order to facilitate their understanding.
1165
1166 (Sets in Access Controls FAQ Entry: {{URL:http://www.openldap.org/faq/data/cache/1133.html}})
1167
1168 Note: Sets are considered experimental. 
1169
1170
1171 H3: Groups of Groups
1172
1173 The OpenLDAP ACL for groups doesn't expand groups within groups, which are
1174 groups that have another group as a member. For example:
1175
1176 > dn: cn=sudoadm,ou=group,dc=example,dc=com
1177 > cn: sudoadm
1178 > objectClass: groupOfNames
1179 > member: uid=john,ou=people,dc=example,dc=com
1180 > member: cn=accountadm,ou=group,dc=example,dc=com
1181 >
1182 > dn: cn=accountadm,ou=group,dc=example,dc=com
1183 > cn: accountadm
1184 > objectClass: groupOfNames
1185 > member: uid=mary,ou=people,dc=example,dc=com
1186
1187 If we use standard group ACLs with the above entries and allow members of the
1188 {{F:sudoadm}} group to write somewhere, {{F:mary}} won't be included:
1189
1190 > access to dn.subtree="ou=sudoers,dc=example,dc=com"
1191 >         by group.exact="cn=sudoadm,ou=group,dc=example,dc=com" write
1192 >         by * read
1193
1194 With sets we can make the ACL be recursive and consider group within groups. So
1195 for each member that is a group, it is further expanded:
1196
1197 > access to dn.subtree="ou=sudoers,dc=example,dc=com"
1198 >       by set="[cn=sudoadm,ou=group,dc=example,dc=com]/member* & user" write
1199 >       by * read
1200
1201 This set ACL means: take the {{F:cn=sudoadm}} DN, check its {{F:member}}
1202 attribute(s) (where the "{{F:*}}" means recursively) and intersect the result
1203 with the authenticated user's DN. If the result is non-empty, the ACL is
1204 considered a match and write access is granted.
1205
1206 The following drawing explains how this set is built:
1207 !import "set-recursivegroup.png"; align="center"; title="Building a recursive group"
1208 FT[align="Center"] Figure X.Y: Populating a recursive group set
1209
1210 First we get the {{F:uid=john}} DN. This entry doesn't have a {{F:member}}
1211 attribute, so the expansion stops here.  Now we get to {{F:cn=accountadm}}.
1212 This one does have a {{F:member}} attribute, which is {{F:uid=mary}}. The
1213 {{F:uid=mary}} entry, however, doesn't have member, so we stop here again. The
1214 end comparison is:
1215
1216 > {"uid=john,ou=people,dc=example,dc=com","uid=mary,ou=people,dc=example,dc=com"} & user
1217
1218 If the authenticated user's DN is any one of those two, write access is
1219 granted. So this set will include {{F:mary}} in the {{F:sudoadm}} group and she
1220 will be allowed the write access.
1221
1222 H3: Group ACLs without DN syntax
1223
1224 The traditional group ACLs, and even the previous example about recursive groups, require
1225 that the members are specified as DNs instead of just usernames.
1226
1227 With sets, however, it's also possible to use simple names in group ACLs, as this example will
1228 show.
1229
1230 Let's say we want to allow members of the {{F:sudoadm}} group to write to the
1231 {{F:ou=suders}} branch of our tree. But our group definition now is using {{F:memberUid}} for
1232 the group members:
1233
1234 > dn: cn=sudoadm,ou=group,dc=example,dc=com
1235 > cn: sudoadm
1236 > objectClass: posixGroup
1237 > gidNumber: 1000
1238 > memberUid: john
1239
1240 With this type of group, we can't use group ACLs. But with a set ACL we can
1241 grant the desired access:
1242
1243 > access to dn.subtree="ou=sudoers,dc=example,dc=com"
1244 >       by set="[cn=sudoadm,ou=group,dc=example,dc=com]/memberUid & user/uid" write
1245 >       by * read
1246
1247 We use a simple intersection where we compare the {{F:uid}} attribute
1248 of the connecting (and authenticated) user with the {{F:memberUid}} attributes
1249 of the group. If they match, the intersection is non-empty and the ACL will
1250 grant write access.
1251
1252 This drawing illustrates this set when the connecting user is authenticated as
1253 {{F:uid=john,ou=people,dc=example,dc=com}}:
1254 !import "set-memberUid.png"; align="center"; title="Sets with memberUid"
1255 FT[align="Center"] Figure X.Y: Sets with {{F:memberUid}}
1256
1257 In this case, it's a match. If it were {{F:mary}} authenticating, however, she
1258 would be denied write access to {{F:ou=sudoers}} because her {{F:uid}}
1259 attribute is not listed in the group's {{F:memberUid}}.
1260
1261 H3: Following references
1262
1263 We will now show a quite powerful example of what can be done with sets. This
1264 example tends to make OpenLDAP administrators smile after they have understood
1265 it and its implications.
1266
1267 Let's start with an user entry:
1268
1269 > dn: uid=john,ou=people,dc=example,dc=com
1270 > uid: john
1271 > objectClass: inetOrgPerson
1272 > givenName: John
1273 > sn: Smith
1274 > cn: john
1275 > manager: uid=mary,ou=people,dc=example,dc=com
1276
1277 Writing an ACL to allow the manager to update some attributes is quite simple
1278 using sets:
1279
1280 > access to dn.exact="uid=john,ou=people,dc=example,dc=com"
1281 >    attrs=carLicense,homePhone,mobile,pager,telephoneNumber
1282 >    by self write
1283 >    by set="this/manager & user" write
1284 >    by * read
1285
1286 In that set, {{F:this}} expands to the entry being accessed, so that
1287 {{F:this/manager}} expands to {{F:uid=mary,ou=people,dc=example,dc=com}} when
1288 john's entry is accessed.  If the manager herself is accessing John's entry,
1289 the ACL will match and write access to those attributes will be granted.
1290
1291 So far, this same behavior can be obtained with the {{F:dnattr}} keyword. With
1292 sets, however, we can further enhance this ACL. Let's say we want to allow the
1293 secretary of the manager to also update these attributes. This is how we do it:
1294
1295 > access to dn.exact="uid=john,ou=people,dc=example,dc=com"
1296 >    attrs=carLicense,homePhone,mobile,pager,telephoneNumber
1297 >    by self write
1298 >    by set="this/manager & user" write
1299 >    by set="this/manager/secretary & user" write
1300 >    by * read
1301
1302 Now we need a picture to help explain what is happening here (entries shortened
1303 for clarity):
1304
1305 !import "set-following-references.png"; align="center"; title="Sets jumping through entries"
1306 FT[align="Center"] Figure X.Y: Sets jumping through entries
1307
1308 In this example, Jane is the secretary of Mary, which is the manager of John.
1309 This whole relationship is defined with the {{F:manager}} and {{F:secretary}}
1310 attributes, which are both of the distinguishedName syntax (i.e., full DNs).
1311 So, when the {{F:uid=john}} entry is being accessed, the
1312 {{F:this/manager/secretary}} set becomes
1313 {{F:{"uid=jane,ou=people,dc=example,dc=com"}}} (follow the references in the
1314 picture):
1315
1316 > this = [uid=john,ou=people,dc=example,dc=com]
1317 > this/manager = \
1318 >   [uid=john,ou=people,dc=example,dc=com]/manager = uid=mary,ou=people,dc=example,dc=com
1319 > this/manager/secretary = \
1320 >   [uid=mary,ou=people,dc=example,dc=com]/secretary = uid=jane,ou=people,dc=example,dc=com
1321
1322 The end result is that when Jane accesses John's entry, she will be granted
1323 write access to the specified attributes. Better yet, this will happen to any
1324 entry she accesses which has Mary as the manager.
1325
1326 This is all cool and nice, but perhaps gives too much power to secretaries. Maybe we need to further
1327 restrict it. For example, let's only allow executive secretaries to have this power:
1328
1329 > access to dn.exact="uid=john,ou=people,dc=example,dc=com"
1330 >   attrs=carLicense,homePhone,mobile,pager,telephoneNumber
1331 >   by self write
1332 >   by set="this/manager & user" write
1333 >   by set="this/manager/secretary & 
1334 >           [cn=executive,ou=group,dc=example,dc=com]/member* & 
1335 >           user" write
1336 >   by * read
1337
1338 It's almost the same ACL as before, but we now also require that the connecting user be a member
1339 of the (possibly nested) {{F:cn=executive}} group.
1340
1341