From a801eaba579234a498979ddd19c48af1a89318ce Mon Sep 17 00:00:00 2001 From: Howard Chu Date: Tue, 21 Aug 2012 21:59:36 -0700 Subject: [PATCH] Whitespace cleanup --- doc/guide/admin/access-control.sdf | 238 ++++++++++++++--------------- 1 file changed, 119 insertions(+), 119 deletions(-) diff --git a/doc/guide/admin/access-control.sdf b/doc/guide/admin/access-control.sdf index 16ad9d1865..0f132b54b1 100644 --- a/doc/guide/admin/access-control.sdf +++ b/doc/guide/admin/access-control.sdf @@ -6,26 +6,26 @@ H1: Access Control H2: Introduction -As the directory gets populated with more and more data of varying sensitivity, +As the directory gets populated with more and more data of varying sensitivity, controlling the kinds of access granted to the directory becomes more and more -critical. For instance, the directory may contain data of a confidential nature -that you may need to protect by contract or by law. Or, if using the directory -to control access to other services, inappropriate access to the directory may -create avenues of attack to your sites security that result in devastating +critical. For instance, the directory may contain data of a confidential nature +that you may need to protect by contract or by law. Or, if using the directory +to control access to other services, inappropriate access to the directory may +create avenues of attack to your sites security that result in devastating damage to your assets. Access to your directory can be configured via two methods, the first using -{{SECT:The slapd Configuration File}} and the second using the {{slapd-config}}(5) +{{SECT:The slapd Configuration File}} and the second using the {{slapd-config}}(5) format ({{SECT:Configuring slapd}}). -The default access control policy is allow read by all clients. Regardless of -what access control policy is defined, the {{rootdn}} is always allowed full +The default access control policy is allow read by all clients. Regardless of +what access control policy is defined, the {{rootdn}} is always allowed full rights (i.e. auth, search, compare, read and write) on everything and anything. -As a consequence, it's useless (and results in a performance penalty) to explicitly +As a consequence, it's useless (and results in a performance penalty) to explicitly list the {{rootdn}} among the {{}} clauses. -The following sections will describe Access Control Lists in greater depth and +The following sections will describe Access Control Lists in greater depth and follow with some examples and recommendations. See {{slapd.access}}(5) for complete details. @@ -45,7 +45,7 @@ access line is: > ::= [val[.]=] | , > ::= | entry | children > ::= * | [anonymous | users | self -> | dn[.]= | dn.=] +> | dn[.]= | dn.=] > [dnattr=] > [group[/[/][.]]=] > [peername[.]=] @@ -220,11 +220,11 @@ an entry and/or attribute, slapd compares the entry and/or attribute to the {{EX:}} selectors given in the configuration file. For each entry, access controls provided in the database which holds the entry (or the global access directives if not held in any database) apply -first, followed by the global access directives. However, when dealing with -an access list, because the global access list is effectively appended -to each per-database list, if the resulting list is non-empty then the -access list will end with an implicit {{EX:access to * by * none}} directive. -If there are no access directives applicable to a backend, then a default +first, followed by the global access directives. However, when dealing with +an access list, because the global access list is effectively appended +to each per-database list, if the resulting list is non-empty then the +access list will end with an implicit {{EX:access to * by * none}} directive. +If there are no access directives applicable to a backend, then a default read is used. Within this @@ -313,8 +313,8 @@ are also under {{EX:dc=com}} entries. Also note that if no {{EX:access to}} directive matches or no {{EX:by }} clause, {{B:access is denied}}. That is, every {{EX:access to}} directive ends with an implicit {{EX:by * none}} clause. When dealing -with an access list, because the global access list is effectively appended -to each per-database list, if the resulting list is non-empty then the access +with an access list, because the global access list is effectively appended +to each per-database list, if the resulting list is non-empty then the access list will end with an implicit {{EX:access to * by * none}} directive. If there are no access directives applicable to a backend, then a default read is used. @@ -383,7 +383,7 @@ The general form of the olcAccess configuration is: > ::= [val[.]=] | , > ::= | entry | children > ::= * | [anonymous | users | self -> | dn[.]= | dn.=] +> | dn[.]= | dn.=] > [dnattr=] > [group[/[/][.]]=] > [peername[.]=] @@ -559,11 +559,11 @@ to the {{EX:}} selectors given in the configuration. For each entry, access controls provided in the database which holds the entry (or the global access directives if not held in any database) apply first, followed by the global access directives (which are held in -the {{EX:frontend}} database definition). However, when dealing with -an access list, because the global access list is effectively appended -to each per-database list, if the resulting list is non-empty then the -access list will end with an implicit {{EX:access to * by * none}} directive. -If there are no access directives applicable to a backend, then a default +the {{EX:frontend}} database definition). However, when dealing with +an access list, because the global access list is effectively appended +to each per-database list, if the resulting list is non-empty then the +access list will end with an implicit {{EX:access to * by * none}} directive. +If there are no access directives applicable to a backend, then a default read is used. Within this priority, @@ -651,10 +651,10 @@ would never be reached, since all entries under {{EX:dc=example,dc=com}} are also under {{EX:dc=com}} entries. Also note that if no {{EX:olcAccess: to}} directive matches or no {{EX:by -}} clause, {{B:access is denied}}. When dealing with an access list, -because the global access list is effectively appended to each per-database -list, if the resulting list is non-empty then the access list will end with -an implicit {{EX:access to * by * none}} directive. If there are no access +}} clause, {{B:access is denied}}. When dealing with an access list, +because the global access list is effectively appended to each per-database +list, if the resulting list is non-empty then the access list will end with +an implicit {{EX:access to * by * none}} directive. If there are no access directives applicable to a backend, then a default read is used. The next example again shows the importance of ordering, both of @@ -730,7 +730,7 @@ when you read them back using slapcat or ldapsearch they will contain The numeric index may be used to specify a particular value to change when using ldapmodify to edit the access rules. This index can be used -instead of (or in addition to) the actual access value. Using this +instead of (or in addition to) the actual access value. Using this numeric index is very helpful when multiple access rules are being managed. For example, if we needed to change the second rule above to grant @@ -792,43 +792,43 @@ Generally one should start with some basic ACLs such as: > by users read > by * none -The first ACL allows users to update (but not read) their passwords, anonymous -users to authenticate against this attribute, and (implicitly) denying all +The first ACL allows users to update (but not read) their passwords, anonymous +users to authenticate against this attribute, and (implicitly) denying all access to others. -The second ACL allows users full access to their entry, authenticated users read -access to anything, and (implicitly) denying all access to others (in this case, -anonymous users). +The second ACL allows users full access to their entry, authenticated users read +access to anything, and (implicitly) denying all access to others (in this case, +anonymous users). H3: Matching Anonymous and Authenticated users An anonymous user has a empty DN. While the {{dn.exact=""}} or {{dn.regex="^$"}} - could be used, {{slapd}}(8)) offers an anonymous shorthand which should be + could be used, {{slapd}}(8)) offers an anonymous shorthand which should be used instead. > access to * > by anonymous none > by * read -denies all access to anonymous users while granting others read. +denies all access to anonymous users while granting others read. -Authenticated users have a subject DN. While {{dn.regex=".+"}} will match any -authenticated user, OpenLDAP provides the users short hand which should be used +Authenticated users have a subject DN. While {{dn.regex=".+"}} will match any +authenticated user, OpenLDAP provides the users short hand which should be used instead. > access to * > by users read > by * none -This ACL grants read permissions to authenticated users while denying others +This ACL grants read permissions to authenticated users while denying others (i.e.: anonymous users). H3: Controlling rootdn access -You could specify the {{rootdn}} in {{slapd.conf}}(5) or {{slapd.d}} without -specifying a {{rootpw}}. Then you have to add an actual directory entry with +You could specify the {{rootdn}} in {{slapd.conf}}(5) or {{slapd.d}} without +specifying a {{rootpw}}. Then you have to add an actual directory entry with the same dn, e.g.: > dn: cn=Manager,o=MyOrganization @@ -838,8 +838,8 @@ the same dn, e.g.: > objectClass: top > userPassword: {SSHA}someSSHAdata -Then binding as the {{rootdn}} will require a regular bind to that DN, which -in turn requires auth access to that entry's DN and {{userPassword}}, and this +Then binding as the {{rootdn}} will require a regular bind to that DN, which +in turn requires auth access to that entry's DN and {{userPassword}}, and this can be restricted via ACLs. E.g.: > access to dn.base="cn=Manager,o=MyOrganization" @@ -848,37 +848,37 @@ can be restricted via ACLs. E.g.: > by users none > by * none -The ACLs above will only allow binding using rootdn from localhost and +The ACLs above will only allow binding using rootdn from localhost and 192.168.0.0/24. H3: Managing access with Groups -There are a few ways to do this. One approach is illustrated here. Consider the +There are a few ways to do this. One approach is illustrated here. Consider the following DIT layout: > +-dc=example,dc=com > +---cn=administrators,dc=example,dc=com -> +---cn=fred blogs,dc=example,dc=com +> +---cn=fred blogs,dc=example,dc=com and the following group object (in LDIF format): > dn: cn=administrators,dc=example,dc=com > cn: administrators of this region > objectclass: groupOfNames (important for the group acl feature) -> member: cn=fred blogs,dc=example,dc=com +> member: cn=fred blogs,dc=example,dc=com > member: cn=somebody else,dc=example,dc=com -One can then grant access to the members of this this group by adding appropriate +One can then grant access to the members of this this group by adding appropriate {{by group}} clause to an access directive in {{slapd.conf}}(5). For instance, -> access to dn.children="dc=example,dc=com" -> by self write -> by group.exact="cn=Administrators,dc=example,dc=com" write +> access to dn.children="dc=example,dc=com" +> by self write +> by group.exact="cn=Administrators,dc=example,dc=com" write > by * auth -Like by {{dn}} clauses, one can also use {{expand}} to expand the group name -based upon the regular expression matching of the target, that is, the to {{dn.regex}}). +Like by {{dn}} clauses, one can also use {{expand}} to expand the group name +based upon the regular expression matching of the target, that is, the to {{dn.regex}}). For instance, > access to dn.regex="(.+,)?ou=People,(dc=[^,]+,dc=[^,]+)$" @@ -888,9 +888,9 @@ For instance, > by * auth -The above illustration assumed that the group members are to be found in the -{{member}} attribute type of the {{groupOfNames}} object class. If you need to -use a different group object and/or a different attribute type then use the +The above illustration assumed that the group members are to be found in the +{{member}} attribute type of the {{groupOfNames}} object class. If you need to +use a different group object and/or a different attribute type then use the following {{slapd.conf}}(5) (abbreviated) syntax: > access to @@ -901,15 +901,15 @@ For example: > access to * > by group/organizationalRole/roleOccupant="cn=Administrator,dc=example,dc=com" write -In this case, we have an ObjectClass {{organizationalRole}} which contains the +In this case, we have an ObjectClass {{organizationalRole}} which contains the administrator DN's in the {{roleOccupant}} attribute. For instance: > dn: cn=Administrator,dc=example,dc=com > cn: Administrator > objectclass: organizationalRole -> roleOccupant: cn=Jane Doe,dc=example,dc=com +> roleOccupant: cn=Jane Doe,dc=example,dc=com -Note: the specified member attribute type MUST be of DN or {{NameAndOptionalUID}} syntax, +Note: the specified member attribute type MUST be of DN or {{NameAndOptionalUID}} syntax, and the specified object class SHOULD allow the attribute type. Dynamic Groups are also supported in Access Control. Please see {{slapo-dynlist}}(5) @@ -918,9 +918,9 @@ and the {{SECT:Dynamic Lists}} overlay section. H3: Granting access to a subset of attributes -You can grant access to a set of attributes by specifying a list of attribute names -in the ACL {{to}} clause. To be useful, you also need to grant access to the -{{entry}} itself. Also note how {{children}} controls the ability to add, delete, +You can grant access to a set of attributes by specifying a list of attribute names +in the ACL {{to}} clause. To be useful, you also need to grant access to the +{{entry}} itself. Also note how {{children}} controls the ability to add, delete, and rename entries. > # mail: self may write, authenticated users may read @@ -928,32 +928,32 @@ and rename entries. > by self write > by users read > by * none -> +> > # cn, sn: self my write, all may read > access to attrs=cn,sn > by self write > by * read -> +> > # immediate children: only self can add/delete entries under this entry > access to attrs=children > by self write -> +> > # entry itself: self may write, all may read > access to attrs=entry > by self write > by * read -> +> > # other attributes: self may write, others have no access > access to * > by self write > by * none -ObjectClass names may also be specified in this list, which will affect -all the attributes that are required and/or allowed by that {{objectClass}}. -Actually, names in {{attrlist}} that are prefixed by {{@}} are directly treated -as objectClass names. A name prefixed by {{!}} is also treated as an objectClass, -but in this case the access rule affects the attributes that are not required -nor allowed by that {{objectClass}}. +ObjectClass names may also be specified in this list, which will affect +all the attributes that are required and/or allowed by that {{objectClass}}. +Actually, names in {{attrlist}} that are prefixed by {{@}} are directly treated +as objectClass names. A name prefixed by {{!}} is also treated as an objectClass, +but in this case the access rule affects the attributes that are not required +nor allowed by that {{objectClass}}. H3: Allowing a user write to all entries below theirs @@ -975,7 +975,7 @@ Let's say, you have it like this: > ou=domains > associatedDomain= > ou=users -> uid= +> uid= > uid= > ou=addressbooks > uid= @@ -988,72 +988,72 @@ and, for another domain : > ou=domains > associatedDomain= > ou=users -> uid= +> uid= > uid= > ou=addressbooks > uid= > cn= > cn= -then, if you wanted user {{uid=}} to {{B:ONLY}} create an entry +then, if you wanted user {{uid=}} to {{B:ONLY}} create an entry for its own thing, you could write an ACL like this: > # this rule lets users of "associatedDomain=" > # write under "ou=addressbook,associatedDomain=,ou=domains,o=", > # i.e. a user can write ANY entry below its domain's address book; -> # this permission is necessary, but not sufficient, the next +> # this permission is necessary, but not sufficient, the next > # will restrict this permission further -> -> +> +> > access to dn.regex="^ou=addressbook,associatedDomain=([^,]+),ou=domains,o=$" attrs=children > by dn.regex="^uid=([^,]+),ou=users,associatedDomain=$1,ou=domains,o=$$" write > by * none -> -> +> +> > # Note that above the "by" clause needs a "regex" style to make sure > # it expands to a DN that starts with a "uid=" pattern > # while substituting the associatedDomain submatch from the "what" clause. -> -> +> +> > # This rule lets a user with "uid=" of "" > # write (i.e. add, modify, delete) the entry whose DN is exactly > # "uid=,ou=addressbook,associatedDomain=,ou=domains,o=" > # and ANY entry as subtree of it -> -> +> +> > access to dn.regex="^(.+,)?uid=([^,]+),ou=addressbook,associatedDomain=([^,]+),ou=domains,o=$" > by dn.exact,expand="uid=$2,ou=users,associatedDomain=$3,ou=domains,o=" write -> by * none -> -> +> by * none +> +> > # Note that above the "by" clause uses the "exact" style with the "expand" > # modifier because now the whole pattern can be rebuilt by means of the > # submatches from the "what" clause, so a "regex" compilation and evaluation > # is no longer required. -H3: Tips for using regular expressions in Access Control +H3: Tips for using regular expressions in Access Control -Always use {{dn.regex=}} when you intend to use regular expression +Always use {{dn.regex=}} when you intend to use regular expression matching. {{dn=}} alone defaults to {{dn.exact}}. -Use {{(.+)}} instead of {{(.*)}} when you want at least one char to be matched. +Use {{(.+)}} instead of {{(.*)}} when you want at least one char to be matched. {{(.*)}} matches the empty string as well. -Don't use regular expressions for matches that can be done otherwise in a safer +Don't use regular expressions for matches that can be done otherwise in a safer and cheaper manner. Examples: > dn.regex=".*dc=example,dc=com" is unsafe and expensive: - * unsafe because any string containing {{dc=example,dc=com }}will match, + * unsafe because any string containing {{dc=example,dc=com }}will match, not only those that end with the desired pattern; use {{.*dc=example,dc=com$}} instead. * unsafe also because it would allow any {{attributeType}} ending with {{dc}} - as naming attribute for the first RDN in the string, e.g. a custom attributeType -{{mydc}} would match as well. If you really need a regular expression that allows -just {{dc=example,dc=com}} or any of its subtrees, use {{^(.+,)?dc=example,dc=com$}}, -which means: anything to the left of dc=..., if any (the question mark after the + as naming attribute for the first RDN in the string, e.g. a custom attributeType +{{mydc}} would match as well. If you really need a regular expression that allows +just {{dc=example,dc=com}} or any of its subtrees, use {{^(.+,)?dc=example,dc=com$}}, +which means: anything to the left of dc=..., if any (the question mark after the pattern within brackets), must end with a comma; * expensive because if you don't need submatches, you could use scoping styles, e.g. @@ -1067,25 +1067,25 @@ to exclude {{dc=example,dc=com}} from the matching patterns, or > dn.onelevel="dc=example,dc=com" -to allow exactly one sublevel matches only. +to allow exactly one sublevel matches only. -Always use {{^}} and {{$}} in regexes, whenever appropriate, because -{{ou=(.+),ou=(.+),ou=addressbooks,o=basedn}} will match +Always use {{^}} and {{$}} in regexes, whenever appropriate, because +{{ou=(.+),ou=(.+),ou=addressbooks,o=basedn}} will match {{something=bla,ou=xxx,ou=yyy,ou=addressbooks,o=basedn,ou=addressbooks,o=basedn,dc=some,dc=org}} -Always use {{([^,]+)}} to indicate exactly one RDN, because {{(.+)}} can -include any number of RDNs; e.g. {{ou=(.+),dc=example,dc=com}} will match +Always use {{([^,]+)}} to indicate exactly one RDN, because {{(.+)}} can +include any number of RDNs; e.g. {{ou=(.+),dc=example,dc=com}} will match {{ou=My,o=Org,dc=example,dc=com}}, which might not be what you want. -Never add the rootdn to the by clauses. ACLs are not even processed for operations -performed with rootdn identity (otherwise there would be no reason to define a +Never add the rootdn to the by clauses. ACLs are not even processed for operations +performed with rootdn identity (otherwise there would be no reason to define a rootdn at all). Use shorthands. The user directive matches authenticated users and the anonymous directive matches anonymous users. -Don't use the {{dn.regex}} form for clauses if all you need is scoping -and/or substring replacement; use scoping styles (e.g. {{exact}}, {{onelevel}}, +Don't use the {{dn.regex}} form for clauses if all you need is scoping +and/or substring replacement; use scoping styles (e.g. {{exact}}, {{onelevel}}, {{children}} or {{subtree}}) and the style modifier expand to cause substring expansion. For instance, @@ -1098,8 +1098,8 @@ although correct, can be safely and efficiently replaced by > access to dn.regex=".+,(dc=[^,]+,dc=[^,]+)$" > by dn.onelevel,expand="ou=Admin,$1" write -where the regex in the {{}} clause is more compact, and the one in the {{}} -clause is replaced by a much more efficient scoping style of onelevel with substring expansion. +where the regex in the {{}} clause is more compact, and the one in the {{}} +clause is replaced by a much more efficient scoping style of onelevel with substring expansion. H3: Granting and Denying access based on security strength factors (ssf) @@ -1132,17 +1132,17 @@ Consider this example: > access to * > by anonymous auth -> +> > access to * > by self write -> +> > access to * -> by users read +> by users read -You may think this will allow any user to login, to read everything and change -his own data if he is logged in. But in this example only the login works and -an ldapsearch returns no data. The Problem is that SLAPD goes through its access -config line by line and stops as soon as it finds a match in the part of the +You may think this will allow any user to login, to read everything and change +his own data if he is logged in. But in this example only the login works and +an ldapsearch returns no data. The Problem is that SLAPD goes through its access +config line by line and stops as soon as it finds a match in the part of the access rule.(here: {{to *}}) To get what we wanted the file has to read: @@ -1150,7 +1150,7 @@ To get what we wanted the file has to read: > access to * > by anonymous auth > by self write -> by users read +> by users read The general rule is: "special access rules first, generic access rules last" @@ -1160,12 +1160,12 @@ information. H2: Sets - Granting rights based on relationships -Sets are best illustrated via examples. The following sections will present +Sets are best illustrated via examples. The following sections will present a few set ACL examples in order to facilitate their understanding. (Sets in Access Controls FAQ Entry: {{URL:http://www.openldap.org/faq/data/cache/1133.html}}) -Note: Sets are considered experimental. +Note: Sets are considered experimental. H3: Groups of Groups @@ -1330,8 +1330,8 @@ restrict it. For example, let's only allow executive secretaries to have this po > attrs=carLicense,homePhone,mobile,pager,telephoneNumber > by self write > by set="this/manager & user" write -> by set="this/manager/secretary & -> [cn=executive,ou=group,dc=example,dc=com]/member* & +> by set="this/manager/secretary & +> [cn=executive,ou=group,dc=example,dc=com]/member* & > user" write > by * read -- 2.39.5