# $OpenLDAP$
-# Copyright 1999-2006 The OpenLDAP Foundation, All Rights Reserved.
+# Copyright 1999-2008 The OpenLDAP Foundation, All Rights Reserved.
# COPYING RESTRICTIONS APPLY, see COPYRIGHT.
H1: The slapd Configuration File
This directive grants access (specified by <accesslevel>) to a set
of entries and/or attributes (specified by <what>) by one or more
-requesters (specified by <who>). See the {{SECT:The access
-Configuration Directive}} section of this chapter for a summary of
-basic usage.
+requestors (specified by <who>). See the {{SECT:Access Control}} section of
+this guide for basic usage.
!if 0
More details discussion of this directive can be found in the
> readonly off
-H4: replica
-
-> replica uri=ldap[s]://<hostname>[:<port>] | host=<hostname>[:<port>]
-> [bindmethod={simple|sasl}]
-> ["binddn=<DN>"]
-> [saslmech=<mech>]
-> [authcid=<identity>]
-> [authzid=<identity>]
-> [credentials=<password>]
-
-This directive specifies a replication site for this database. The
-{{EX:uri=}} parameter specifies a scheme, a host and optionally a port where
-the slave slapd instance can be found. Either a domain name
-or IP address may be used for <hostname>. If <port> is not
-given, the standard LDAP port number (389 or 636) is used.
-
-{{EX:host}} is deprecated in favor of the {{EX:uri}} parameter.
-
-{{EX:uri}} allows the replica LDAP server to be specified as an LDAP
-URI such as {{EX:ldap://slave.example.com:389}} or
-{{EX:ldaps://slave.example.com:636}}.
-
-The {{EX:binddn=}} parameter gives the DN to bind as for updates
-to the slave slapd. It should be a DN which has read/write access
-to the slave slapd's database. It must also match the {{EX:updatedn}}
-directive in the slave slapd's config file. Generally, this DN
-{{should not}} be the same as the {{EX:rootdn}} of the master
-database. Since DNs are likely to contain embedded spaces, the
-entire {{EX:"binddn=<DN>"}} string should be enclosed in double
-quotes.
-
-The {{EX:bindmethod}} is {{EX:simple}} or {{EX:sasl}}, depending
-on whether simple password-based authentication or {{TERM:SASL}}
-authentication is to be used when connecting to the slave slapd.
-
-Simple authentication should not be used unless adequate data
-integrity and confidentiality protections are in place (e.g. TLS
-or {{TERM:IPsec}}). Simple authentication requires specification of
-{{EX:binddn}} and {{EX:credentials}} parameters.
-
-SASL authentication is generally recommended. SASL authentication
-requires specification of a mechanism using the {{EX:saslmech}} parameter.
-Depending on the mechanism, an authentication identity and/or
-credentials can be specified using {{EX:authcid}} and {{EX:credentials}}
-respectively. The {{EX:authzid}} parameter may be used to specify
-an authorization identity.
-
-See the chapter entitled {{SECT:Replication with slurpd}} for more
-information on how to use this directive.
-
-H4: replogfile <filename>
-
-This directive specifies the name of the replication log file to
-which slapd will log changes. The replication log is typically
-written by slapd and read by slurpd. Normally, this directive is
-only used if slurpd is being used to replicate the database.
-However, you can also use it to generate a transaction log, if
-slurpd is not running. In this case, you will need to periodically
-truncate the file, since it will grow indefinitely otherwise.
-
-See the chapter entitled {{SECT:Replication with slurpd}} for more
-information on how to use this directive.
-
H4: rootdn <DN>
> [type=refreshOnly|refreshAndPersist]
> [interval=dd:hh:mm:ss]
> [retry=[<retry interval> <# of retries>]+]
-> [searchbase=<base DN>]
+> searchbase=<base DN>
> [filter=<filter str>]
> [scope=sub|one|base]
> [attrs=<attr list>]
for more information on how to use this directive.
-H4: updatedn <DN>
-
-This directive is only applicable in a {{slave}} (or {{shadow}})
-{{slapd(8)}} instance. It specifies the DN allowed to make changes to
-the replica. This may be the DN
-{{slurpd}}(8) binds as when making changes to the replica or the DN
-associated with a SASL identity.
-
-
-Entry-based Example:
-
-> updatedn "cn=Update Daemon,dc=example,dc=com"
-
-SASL-based Example:
-
-> updatedn "uid=slurpd,cn=example.com,cn=digest-md5,cn=auth"
-
-See the {{SECT:Replication with slurpd}} chapter for more information
-on how to use this directive.
-
H4: updateref <URL>
This directive is only applicable in a {{slave}} (or {{shadow}})
\Default:
> directory /usr/local/var/openldap-data
-
-
-H2: The access Configuration Directive
-
-Access to entries and attributes is controlled by the
-access configuration file directive. The general form of an
-access line is:
-
-> <access directive> ::= access to <what>
-> [by <who> [<access>] [<control>] ]+
-> <what> ::= * |
-> [dn[.<basic-style>]=<regex> | dn.<scope-style>=<DN>]
-> [filter=<ldapfilter>] [attrs=<attrlist>]
-> <basic-style> ::= regex | exact
-> <scope-style> ::= base | one | subtree | children
-> <attrlist> ::= <attr> [val[.<basic-style>]=<regex>] | <attr> , <attrlist>
-> <attr> ::= <attrname> | entry | children
-> <who> ::= * | [anonymous | users | self
-> | dn[.<basic-style>]=<regex> | dn.<scope-style>=<DN>]
-> [dnattr=<attrname>]
-> [group[/<objectclass>[/<attrname>][.<basic-style>]]=<regex>]
-> [peername[.<basic-style>]=<regex>]
-> [sockname[.<basic-style>]=<regex>]
-> [domain[.<basic-style>]=<regex>]
-> [sockurl[.<basic-style>]=<regex>]
-> [set=<setspec>]
-> [aci=<attrname>]
-> <access> ::= [self]{<level>|<priv>}
-> <level> ::= none | disclose | auth | compare | search | read | write | manage
-> <priv> ::= {=|+|-}{m|w|r|s|c|x|d|0}+
-> <control> ::= [stop | continue | break]
-
-where the <what> part selects the entries and/or attributes to which
-the access applies, the {{EX:<who>}} part specifies which entities
-are granted access, and the {{EX:<access>}} part specifies the
-access granted. Multiple {{EX:<who> <access> <control>}} triplets
-are supported, allowing many entities to be granted different access
-to the same set of entries and attributes. Not all of these access
-control options are described here; for more details see the
-{{slapd.access}}(5) man page.
-
-
-H3: What to control access to
-
-The <what> part of an access specification determines the entries
-and attributes to which the access control applies. Entries are
-commonly selected in two ways: by DN and by filter. The following
-qualifiers select entries by DN:
-
-> to *
-> to dn[.<basic-style>]=<regex>
-> to dn.<scope-style>=<DN>
-
-The first form is used to select all entries. The second form may
-be used to select entries by matching a regular expression against
-the target entry's {{normalized DN}}. (The second form is not
-discussed further in this document.) The third form is used to
-select entries which are within the requested scope of DN. The
-<DN> is a string representation of the Distinguished Name, as
-described in {{REF:RFC4514}}.
-
-The scope can be either {{EX:base}}, {{EX:one}}, {{EX:subtree}},
-or {{EX:children}}. Where {{EX:base}} matches only the entry with
-provided DN, {{EX:one}} matches the entries whose parent is the
-provided DN, {{EX:subtree}} matches all entries in the subtree whose
-root is the provided DN, and {{EX:children}} matches all entries
-under the DN (but not the entry named by the DN).
-
-For example, if the directory contained entries named:
-
-> 0: o=suffix
-> 1: cn=Manager,o=suffix
-> 2: ou=people,o=suffix
-> 3: uid=kdz,ou=people,o=suffix
-> 4: cn=addresses,uid=kdz,ou=people,o=suffix
-> 5: uid=hyc,ou=people,o=suffix
-
-\Then:
-. {{EX:dn.base="ou=people,o=suffix"}} match 2;
-. {{EX:dn.one="ou=people,o=suffix"}} match 3, and 5;
-. {{EX:dn.subtree="ou=people,o=suffix"}} match 2, 3, 4, and 5; and
-. {{EX:dn.children="ou=people,o=suffix"}} match 3, 4, and 5.
-
-
-Entries may also be selected using a filter:
-
-> to filter=<ldap filter>
-
-where <ldap filter> is a string representation of an LDAP
-search filter, as described in {{REF:RFC4515}}. For example:
-
-> to filter=(objectClass=person)
-
-Note that entries may be selected by both DN and filter by
-including both qualifiers in the <what> clause.
-
-> to dn.one="ou=people,o=suffix" filter=(objectClass=person)
-
-Attributes within an entry are selected by including a comma-separated
-list of attribute names in the <what> selector:
-
-> attrs=<attribute list>
-
-A specific value of an attribute is selected by using a single
-attribute name and also using a value selector:
-
-> attrs=<attribute> val[.<style>]=<regex>
-
-There are two special {{pseudo}} attributes {{EX:entry}} and
-{{EX:children}}. To read (and hence return) a target entry, the
-subject must have {{EX:read}} access to the target's {{entry}}
-attribute. To add or delete an entry, the subject must have
-{{EX:write}} access to the entry's {{EX:entry}} attribute AND must
-have {{EX:write}} access to the entry's parent's {{EX:children}}
-attribute. To rename an entry, the subject must have {{EX:write}}
-access to entry's {{EX:entry}} attribute AND have {{EX:write}}
-access to both the old parent's and new parent's {{EX:children}}
-attributes. The complete examples at the end of this section should
-help clear things up.
-
-Lastly, there is a special entry selector {{EX:"*"}} that is used to
-select any entry. It is used when no other {{EX:<what>}}
-selector has been provided. It's equivalent to "{{EX:dn=.*}}"
-
-
-H3: Who to grant access to
-
-The <who> part identifies the entity or entities being granted
-access. Note that access is granted to "entities" not "entries."
-The following table summarizes entity specifiers:
-
-!block table; align=Center; coltags="EX,N"; \
- title="Table 6.3: Access Entity Specifiers"
-Specifier|Entities
-*|All, including anonymous and authenticated users
-anonymous|Anonymous (non-authenticated) users
-users|Authenticated users
-self|User associated with target entry
-dn[.<basic-style>]=<regex>|Users matching a regular expression
-dn.<scope-style>=<DN>|Users within scope of a DN
-!endblock
-
-The DN specifier behaves much like <what> clause DN specifiers.
-
-Other control factors are also supported. For example, a {{EX:<who>}}
-can be restricted by an entry listed in a DN-valued attribute in
-the entry to which the access applies:
-
-> dnattr=<dn-valued attribute name>
-
-The dnattr specification is used to give access to an entry
-whose DN is listed in an attribute of the entry (e.g., give
-access to a group entry to whoever is listed as the owner of
-the group entry).
-
-Some factors may not be appropriate in all environments (or any).
-For example, the domain factor relies on IP to domain name lookups.
-As these can easily spoofed, the domain factor should not be avoided.
-
-
-H3: The access to grant
-
-The kind of <access> granted can be one of the following:
-
-!block table; colaligns="LRL"; coltags="EX,EX,N"; align=Center; \
- title="Table 6.4: Access Levels"
-Level Privileges Description
-none =0 no access
-disclose =d needed for information disclosure on error
-auth =dx needed to authenticate (bind)
-compare =cdx needed to compare
-search =scdx needed to apply search filters
-read =rscdx needed to read search results
-write =wrscdx needed to modify/rename
-manage =mwrscdx needed to manage
-!endblock
-
-Each level implies all lower levels of access. So, for example,
-granting someone {{EX:write}} access to an entry also grants them
-{{EX:read}}, {{EX:search}}, {{EX:compare}}, {{EX:auth}} and
-{{EX:disclose}} access. However, one may use the privileges specifier
-to grant specific permissions.
-
-
-H3: Access Control Evaluation
-
-When evaluating whether some requester should be given access to
-an entry and/or attribute, slapd compares the entry and/or attribute
-to the {{EX:<what>}} selectors given in the configuration file.
-For each entry, access controls provided in the database which holds
-the entry (or the first database if not held in any database) apply
-first, followed by the global access directives. Within this
-priority, access directives are examined in the order in which they
-appear in the config file. Slapd stops with the first {{EX:<what>}}
-selector that matches the entry and/or attribute. The corresponding
-access directive is the one slapd will use to evaluate access.
-
-Next, slapd compares the entity requesting access to the {{EX:<who>}}
-selectors within the access directive selected above in the order
-in which they appear. It stops with the first {{EX:<who>}} selector
-that matches the requester. This determines the access the entity
-requesting access has to the entry and/or attribute.
-
-Finally, slapd compares the access granted in the selected
-{{EX:<access>}} clause to the access requested by the client. If
-it allows greater or equal access, access is granted. Otherwise,
-access is denied.
-
-The order of evaluation of access directives makes their placement
-in the configuration file important. If one access directive is
-more specific than another in terms of the entries it selects, it
-should appear first in the config file. Similarly, if one {{EX:<who>}}
-selector is more specific than another it should come first in the
-access directive. The access control examples given below should
-help make this clear.
-
-
-
-H3: Access Control Examples
-
-The access control facility described above is quite powerful. This
-section shows some examples of its use for descriptive purposes.
-
-A simple example:
-
-> access to * by * read
-
-This access directive grants read access to everyone.
-
-> access to *
-> by self write
-> by anonymous auth
-> by * read
-
-This directive allows the user to modify their entry, allows anonymous
-to authentication against these entries, and allows all others to
-read these entries. Note that only the first {{EX:by <who>}} clause
-which matches applies. Hence, the anonymous users are granted
-{{EX:auth}}, not {{EX:read}}. The last clause could just as well
-have been "{{EX:by users read}}".
-
-It is often desirable to restrict operations based upon the level
-of protection in place. The following shows how security strength
-factors (SSF) can be used.
-
-> access to *
-> by ssf=128 self write
-> by ssf=64 anonymous auth
-> by ssf=64 users read
-
-This directive allows users to modify their own entries if security
-protections have of strength 128 or better have been established,
-allows authentication access to anonymous users, and read access
-when 64 or better security protections have been established. If
-client has not establish sufficient security protections, the
-implicit {{EX:by * none}} clause would be applied.
-
-The following example shows the use of a style specifiers to select
-the entries by DN in two access directives where ordering is
-significant.
-
-> access to dn.children="dc=example,dc=com"
-> by * search
-> access to dn.children="dc=com"
-> by * read
-
-Read access is granted to entries under the {{EX:dc=com}} subtree,
-except for those entries under the {{EX:dc=example,dc=com}} subtree,
-to which search access is granted. No access is granted to
-{{EX:dc=com}} as neither access directive matches this DN. If the
-order of these access directives was reversed, the trailing directive
-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:access to}} directive matches or no {{EX:by
-<who>}} clause, {{B:access is denied}}. That is, every {{EX:access
-to}} directive ends with an implicit {{EX:by * none}} clause and
-every access list ends with an implicit {{EX:access to * by * none}}
-directive.
-
-The next example again shows the importance of ordering, both of
-the access directives and the {{EX:by <who>}} clauses. It also
-shows the use of an attribute selector to grant access to a specific
-attribute and various {{EX:<who>}} selectors.
-
-> access to dn.subtree="dc=example,dc=com" attr=homePhone
-> by self write
-> by dn.children="dc=example,dc=com" search
-> by peername.regex=IP:10\..+ read
-> access to dn.subtree="dc=example,dc=com"
-> by self write
-> by dn.children="dc=example,dc=com" search
-> by anonymous auth
-
-This example applies to entries in the "{{EX:dc=example,dc=com}}"
-subtree. To all attributes except {{EX:homePhone}}, an entry can
-write to itself, entries under {{EX:example.com}} entries can search
-by them, anybody else has no access (implicit {{EX:by * none}})
-excepting for authentication/authorization (which is always done
-anonymously). The {{EX:homePhone}} attribute is writable by the
-entry, searchable by entries under {{EX:example.com}}, readable by
-clients connecting from network 10, and otherwise not readable
-(implicit {{EX:by * none}}). All other access is denied by the
-implicit {{EX:access to * by * none}}.
-
-Sometimes it is useful to permit a particular DN to add or
-remove itself from an attribute. For example, if you would like to
-create a group and allow people to add and remove only
-their own DN from the member attribute, you could accomplish
-it with an access directive like this:
-
-> access to attr=member,entry
-> by dnattr=member selfwrite
-
-The dnattr {{EX:<who>}} selector says that the access applies to
-entries listed in the {{EX:member}} attribute. The {{EX:selfwrite}} access
-selector says that such members can only add or delete their
-own DN from the attribute, not other values. The addition of
-the entry attribute is required because access to the entry is
-required to access any of the entry's attributes.
-
-!if 0
-For more details on how to use the {{EX:access}} directive,
-consult the {{Advanced Access Control}} chapter.
-!endif
-
-
-H2: Configuration File Example
-
-The following is an example configuration file, interspersed
-with explanatory text. It defines two databases to handle
-different parts of the {{TERM:X.500}} tree; both are {{TERM:BDB}}
-database instances. The line numbers shown are provided for
-reference only and are not included in the actual file. First, the
-global configuration section:
-
-E: 1. # example config file - global configuration section
-E: 2. include /usr/local/etc/schema/core.schema
-E: 3. referral ldap://root.openldap.org
-E: 4. access to * by * read
-
-Line 1 is a comment. Line 2 includes another config file
-which contains {{core}} schema definitions.
-The {{EX:referral}} directive on line 3
-means that queries not local to one of the databases defined
-below will be referred to the LDAP server running on the
-standard port (389) at the host {{EX:root.openldap.org}}.
-
-Line 4 is a global access control. It applies to all
-entries (after any applicable database-specific access
-controls).
-
-The next section of the configuration file defines a BDB
-backend that will handle queries for things in the
-"dc=example,dc=com" portion of the tree. The
-database is to be replicated to two slave slapds, one on
-truelies, the other on judgmentday. Indices are to be
-maintained for several attributes, and the {{EX:userPassword}}
-attribute is to be protected from unauthorized access.
-
-E: 5. # BDB definition for the example.com
-E: 6. database bdb
-E: 7. suffix "dc=example,dc=com"
-E: 8. directory /usr/local/var/openldap-data
-E: 9. rootdn "cn=Manager,dc=example,dc=com"
-E: 10. rootpw secret
-E: 11. # replication directives
-E: 12. replogfile /usr/local/var/openldap/slapd.replog
-E: 13. replica uri=ldap://slave1.example.com:389
-E: 14. binddn="cn=Replicator,dc=example,dc=com"
-E: 15. bindmethod=simple credentials=secret
-E: 16. replica uri=ldaps://slave2.example.com:636
-E: 17. binddn="cn=Replicator,dc=example,dc=com"
-E: 18. bindmethod=simple credentials=secret
-E: 19. # indexed attribute definitions
-E: 20. index uid pres,eq
-E: 21. index cn,sn,uid pres,eq,approx,sub
-E: 22. index objectClass eq
-E: 23. # database access control definitions
-E: 24. access to attr=userPassword
-E: 25. by self write
-E: 26. by anonymous auth
-E: 27. by dn.base="cn=Admin,dc=example,dc=com" write
-E: 28. by * none
-E: 29. access to *
-E: 30. by self write
-E: 31. by dn.base="cn=Admin,dc=example,dc=com" write
-E: 32. by * read
-
-Line 5 is a comment. The start of the database definition is marked
-by the database keyword on line 6. Line 7 specifies the DN suffix
-for queries to pass to this database. Line 8 specifies the directory
-in which the database files will live.
-
-Lines 9 and 10 identify the database {{super-user}} entry and associated
-password. This entry is not subject to access control or size or
-time limit restrictions.
-
-Lines 11 through 18 are for replication. Line 12 specifies the
-replication log file (where changes to the database are logged -
-this file is written by slapd and read by slurpd). Lines 13 through
-15 specify the hostname and port for a replicated host, the DN to
-bind as when performing updates, the bind method (simple) and the
-credentials (password) for the binddn. Lines 16 through 18 specify
-a second replication site. See the {{SECT:Replication with slurpd}}
-chapter for more information on these directives.
-
-Lines 20 through 22 indicate the indices to maintain for various
-attributes.
-
-Lines 24 through 32 specify access control for entries in this
-database. As this is the first database, the controls also apply
-to entries not held in any database (such as the Root DSE). For
-all applicable entries, the {{EX:userPassword}} attribute is writable
-by the entry itself and by the "admin" entry. It may be used for
-authentication/authorization purposes, but is otherwise not readable.
-All other attributes are writable by the entry and the "admin"
-entry, but may be read by all users (authenticated or not).
-
-The next section of the example configuration file defines another
-BDB database. This one handles queries involving the
-{{EX:dc=example,dc=net}} subtree but is managed by the same entity
-as the first database. Note that without line 39, the read access
-would be allowed due to the global access rule at line 4.
-
-E: 33. # BDB definition for example.net
-E: 34. database bdb
-E: 35. suffix "dc=example,dc=net"
-E: 36. directory /usr/local/var/openldap-data-net
-E: 37. rootdn "cn=Manager,dc=example,dc=com"
-E: 38. index objectClass eq
-E: 39. access to * by users read
projects / openldap / blobdiff