.TH SLAPD.ACCESS 5 "RELEASEDATE" "OpenLDAP LDVERSION"
-.\" Copyright 1998-2004 The OpenLDAP Foundation All Rights Reserved.
+.\" Copyright 1998-2011 The OpenLDAP Foundation All Rights Reserved.
.\" Copying restrictions apply. See COPYRIGHT/LICENSE.
+.\" $OpenLDAP$
.SH NAME
slapd.access \- access configuration for slapd, the stand-alone LDAP daemon
.SH SYNOPSIS
.BR slapd.conf (5)
file contains configuration information for the
.BR slapd (8)
-daemon. This configuration file is also used by the
-.BR slurpd (8)
-replication daemon and by the SLAPD tools
+daemon. This configuration file is also used by the SLAPD tools
.BR slapacl (8),
.BR slapadd (8),
.BR slapauth (8),
If no access controls are present, the default policy
allows anyone and everyone to read anything but restricts
updates to rootdn. (e.g., "access to * by * read").
-The rootdn can always read and write EVERYTHING!
+.LP
+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
+.B access to * by * none
+directive. If there are no access directives applicable to a backend,
+then a default read is used.
+.LP
+.B Be warned: the rootdn can always read and write EVERYTHING!
.LP
For entries not held in any backend (such as a root DSE), the
-directives of the first backend (and any global directives) are
-used.
+global directives are used.
.LP
Arguments that should be replaced by actual text are shown in
brackets <>.
.SH THE ACCESS DIRECTIVE
The structure of the access control directives is
.TP
-.B access to <what> "[ by <who> <access> [ <control> ] ]+"
+.B access to <what> "[ by <who> [ <access> ] [ <control> ] ]+"
Grant access (specified by
.BR <access> )
to a set of entries and/or attributes (specified by
.BR <what> )
by one or more requestors (specified by
.BR <who> ).
+
+.LP
+Lists of access directives are evaluated in the order they appear
+in \fIslapd.conf\fP.
+When a
+.B <what>
+clause matches the datum whose access is being evaluated, its
+.B <who>
+clause list is checked.
+When a
+.B <who>
+clause matches the accessor's properties, its
+.B <access>
+and
+.B <control>
+clauses are evaluated.
+Access control checking stops at the first match of the
+.B <what>
+and
+.B <who>
+clause, unless otherwise dictated by the
+.B <control>
+clause.
+Each
+.B <who>
+clause list is implicitly terminated by a
+.LP
+.nf
+ by * none stop
+.fi
+.LP
+clause that results in stopping the access control with no access
+privileges granted.
+Each
+.B <what>
+clause list is implicitly terminated by a
+.LP
+.nf
+ access to *
+ by * none
+.fi
+.LP
+clause that results in granting no access privileges to an otherwise
+unspecified datum.
.SH THE <WHAT> FIELD
The field
.BR <what>
It can have the forms
.LP
.nf
- [dn[.<dnstyle>]=]<dnpattern>
+ dn[.<dnstyle>]=<dnpattern>
filter=<ldapfilter>
- attrs=<attrlist>[ val[.<attrstyle>]=<attrval>]
+ attrs=<attrlist>[ val[
/matchingRule][.<attrstyle>]=<attrval>]
.fi
.LP
with
The statement
.B dn=<dnpattern>
selects the entries based on their naming context.
-The
-.B dn=
-part is optional.
The
.B <dnpattern>
is a string representation of the entry's DN.
.LP
The
.B <dnstyle>
-is also optional; however, it is recommended to specify both the
-.B dn=
-and the
-.B <dnstyle>
-to avoid ambiguities.
+is optional; however, it is recommended to specify it to avoid ambiguities.
.B Base
(synonym of
.BR baseObject ),
and/or
.BR re_format (7),
matching a normalized string representation of the entry's DN.
-The regex form of the pattern does not (yet) support UTF\-8.
+The regex form of the pattern does not (yet) support UTF-8.
.LP
The statement
.B filter=<ldapfilter>
-selects the entries based on a valid LDAP filter as described in RFC 2254.
+selects the entries based on a valid LDAP filter as described in RFC 4515.
A filter of
.B (objectClass=*)
is implied if no
is implied, i.e. all attributes are addressed.
.LP
Using the form
-.B attrs=<attr> val[
.<style>]=<attrval>
+.B attrs=<attr> val[
/matchingRule][.<attrstyle>]=<attrval>
specifies access to a particular value of a single attribute.
-In this case, only a single attribute type may be given. A value
-.B <style>
-of
+In this case, only a single attribute type may be given. The
+.B <attrstyle>
.B exact
(the default) uses the attribute's equality matching rule to compare the
-value. If the value
-.B <style>
+value, unless a different (and compatible) matching rule is specified. If the
+.B <attrstyle>
is
.BR regex ,
the provided value is used as a POSIX (''extended'') regular
-expression pattern. If the attribute has DN syntax, the value
-.B <style>
+expression pattern. If the attribute has DN syntax, the
+.B <attrstyle>
can be any of
.BR base ,
.BR onelevel ,
The dn, filter, and attrs statements are additive; they can be used in sequence
to select entities the access rule applies to based on naming context,
value and attribute type simultaneously.
+Submatches resulting from
+.B regex
+matching can be dereferenced in the
+.B <who>
+field using the syntax
+.IR ${v<n>} ,
+where
+.I <n>
+is the submatch number.
+The default syntax,
+.IR $<n> ,
+is actually an alias for
+.IR ${d<n>} ,
+that corresponds to dereferencing submatches from the
+.B dnpattern
+portion of the
+.B <what>
+field.
.SH THE <WHO> FIELD
The field
.B <who>
*
anonymous
users
- self
+ self[.<selfstyle>]
dn[.<dnstyle>[,<modifier>]]=<DN>
dnattr=<attrname>
+
+ realanonymous
+ realusers
+ realself[.<selfstyle>]
+
+ realdn[.<dnstyle>[,<modifier>]]=<DN>
+ realdnattr=<attrname>
+
group[/<objectclass>[/<attrname>]]
[.<groupstyle>]=<group>
peername[.<peernamestyle>]=<peername>
tls_ssf=<n>
sasl_ssf=<n>
- aci=<attrname>
+ dynacl/<name>[/<options>][.<dynstyle>][=<pattern>]
.fi
.LP
with
.LP
.nf
<style>={exact|regex|expand}
+ <selfstyle>={level{<n>}}
<dnstyle>={{exact|base(object)}|regex
- |one(level)|sub(tree)|children}
+ |one(level)|sub(tree)|children|level{<n>}}
<groupstyle>={exact|expand}
- <peernamestyle>={<style>|ip|path}
+ <peernamestyle>={<style>|ip|ipv6|path}
<domainstyle>={exact|regex|sub(tree)}
- <setstyle>={exact|regex}
+ <setstyle>={exact|expand}
<modifier>={expand}
+ <name>=aci <pattern>=<attrname>]
.fi
.LP
They may be specified in combination.
.B *
refers to everybody.
.LP
+The keywords prefixed by
+.B real
+act as their counterparts without prefix; the checking respectively occurs
+with the \fIauthentication\fP DN and the \fIauthorization\fP DN.
+.LP
The keyword
.B anonymous
means access is granted to unauthenticated clients; it is mostly used
.B self
means access to an entry is allowed to the entry itself (e.g. the entry
being accessed and the requesting entry must be the same).
+It allows the
+.B level{<n>}
+style, where \fI<n>\fP indicates what ancestor of the DN
+is to be used in matches.
+A positive value indicates that the <n>-th ancestor of the user's DN
+is to be considered; a negative value indicates that the <n>-th ancestor
+of the target is to be considered.
+For example, a "\fIby self.level{1} ...\fP" clause would match
+when the object "\fIdc=example,dc=com\fP" is accessed
+by "\fIcn=User,dc=example,dc=com\fP".
+A "\fIby self.level{-1} ...\fP" clause would match when the same user
+accesses the object "\fIou=Address Book,cn=User,dc=example,dc=com\fP".
.LP
The statement
.B dn=<DN>
or the form
.BR ${<digit>+} ,
for submatches higher than 9.
+Substring substitution from attribute value can
+be done in
+using the form
+.BR ${v<digit>+} .
Since the dollar character is used to indicate a substring replacement,
the dollar character that is used to indicate match up to the end of
the string must be escaped by a second dollar character, e.g.
the
.BR one(level) ,
and the
-.B children
+.BR children
forms provide
.B $0
as the match of the entire string.
the
.BR one(level) ,
and the
-.B children
+.BR children
forms also provide
.B $1
as the match of the rightmost part of the DN as defined in the
.B <by>
clause is allowed.
.LP
+The
+.BR level{<n>}
+form is an extension and a generalization of the
+.BR onelevel
+form, which matches all DNs whose <n>-th ancestor is the pattern.
+So, \fIlevel{1}\fP is equivalent to \fIonelevel\fP,
+and \fIlevel{0}\fP is equivalent to \fIbase\fP.
+.LP
It is perfectly useless to give any access privileges to a DN
that exactly matches the
.B rootdn
and
.B <attrname>
define the objectClass and the member attributeType of the group entry.
+The defaults are
+.B groupOfNames
+and
+.BR member ,
+respectively.
The optional style qualifier
.B <style>
can be
and
.BR sockurl=<sockurl>
mean that the contacting host IP (in the form
-.BR "IP=<ip>:<port>" )
+.BR "IP=<ip>:<port>"
+for IPv4, or
+.BR "IP=[<ipv6>]:<port>"
+for IPv6)
or the contacting host named pipe file name (in the form
.B "PATH=<path>"
if connecting through a named pipe) for
are dotted digit representations of the IP and the mask, while
.BR <n> ,
delimited by curly brackets, is an optional port.
+The same applies to IPv6 addresses when the special
+.B ipv6
+style is used.
When checking access privileges, the IP portion of the
.BR peername
is extracted, eliminating the
part, and it is compared against the
.B <ip>
portion of the pattern after masking with
-.BR <mask> .
+.BR <mask> :
+\fI((peername & <mask>) == <ip>)\fP.
As an example,
.B peername.ip=127.0.0.1
-allows connections only from localhost,
+and
+.B peername.ipv6=::1
+allow connections only from localhost,
.B peername.ip=192.168.1.0%255.255.255.0
allows connections from any IP in the 192.168.1 class C domain, and
.B peername.ip=192.168.1.16%255.255.255.240{9009}
is undocumented yet.
.LP
The statement
-.B aci=<attrname>
+.B dynacl/<name>[/<options>][.<dynstyle>][=<pattern>]
+means that access checking is delegated to the admin-defined method
+indicated by
+.BR <name> ,
+which can be registered at run-time by means of the
+.B moduleload
+statement.
+The fields
+.BR <options> ,
+.B <dynstyle>
+and
+.B <pattern>
+are optional, and are directly passed to the registered parsing routine.
+Dynacl is experimental; it must be enabled at compile time.
+.LP
+The statement
+.B dynacl/aci[=<attrname>]
means that the access control is determined by the values in the
.B attrname
of the entry itself.
+The optional
+.B <attrname>
+indicates what attributeType holds the ACI information in the entry.
+By default, the
+.B OpenLDAPaci
+operational attribute is used.
ACIs are experimental; they must be enabled at compile time.
.LP
The statements
set the minimum required Security Strength Factor (ssf) needed
to grant access. The value should be positive integer.
.SH THE <ACCESS> FIELD
-The field
-.B <access> ::= [self]{<level>|<priv>}
+The optional field
+.B <access> ::= [
[real]self]{<level>|<priv>}
determines the access level or the specific access privileges the
.B who
field will have.
Its component are defined as
.LP
.nf
- <level> ::= none|auth|compare|search|read|write
- <priv> ::= {=|+|-}{w|r|s|c|x|0}+
+ <level> ::= none|disclose|auth|compare|search|read|{write|add|delete}|manage
+ <priv> ::= {=|+|\-}{0|d|x|c|s|r|{w|a|z}|m}+
.fi
.LP
The modifier
allows special operations like having a certain access level or privilege
only in case the operation involves the name of the user that's requesting
the access.
-It implies the user that requests access is bound.
+It implies the user that requests access is authorized.
+The modifier
+.B realself
+refers to the authenticated DN as opposed to the authorized DN of the
+.B self
+modifier.
An example is the
.B selfwrite
access to the member attribute of a group, which allows one to add/delete
-its own DN from the member list of a group, without affecting other members.
+its own DN from the member list of a group, while being not allowed
+to affect other members.
.LP
The
.B level
privileges.
The possible levels are
.BR none ,
+.BR disclose ,
.BR auth ,
.BR compare ,
.BR search ,
.BR read ,
+.BR write ,
and
-.BR write .
+.BR manage .
Each access level implies all the preceding ones, thus
-.B write
-access will imply all accesses.
-While
-.B none
-is trivial,
+.B manage
+grants all access including administrative access.
+The
+.BR write
+access is actually the combination of
+.BR add
+and
+.BR delete ,
+which respectively restrict the write privilege to add or delete
+the specified
+.BR <what> .
+
+.LP
+The
+.B none
+access level disallows all access including disclosure on error.
+.LP
+The
+.B disclose
+access level allows disclosure of information on error.
+.LP
+The
.B auth
-access means that one is allowed access to an attribute to perform
+access level means that one is allowed access to an attribute to perform
authentication/authorization operations (e.g.
.BR bind )
with no other access.
The
.B +
and
-.B -
+.B \-
signs add/remove access privileges to the existing ones.
The privileges are
+.B m
+for manage,
.B w
for write,
+.B a
+for add,
+.B z
+for delete,
.B r
for read,
.B s
for search,
.B c
-for compare, and
+for compare,
.B x
-for authentication.
+for authentication, and
+.B d
+for disclose.
More than one of the above privileges can be added in one statement.
.B 0
indicates no privileges and is used only by itself (e.g., +0).
-.LP
+Note that
+.B +az
+is equivalent to
+.BR +w .
+.LP
+If no access is given, it defaults to
+.BR +0 .
+.SH THE <CONTROL> FIELD
The optional field
.B <control>
controls the flow of access rule application.
.LP
which grants everybody search and compare privileges, and adds read
privileges to authenticated clients.
+.LP
+One useful application is to easily grant write privileges to an
+.B updatedn
+that is different from the
+.BR rootdn .
+In this case, since the
+.B updatedn
+needs write access to (almost) all data, one can use
+.LP
+.nf
+ access to *
+ by dn.exact="cn=The Update DN,dc=example,dc=com" write
+ by * break
+.fi
+.LP
+as the first access rule.
+As a consequence, unless the operation is performed with the
+.B updatedn
+identity, control is passed straight to the subsequent rules.
+
.SH OPERATION REQUIREMENTS
Operations require different privileges on different portions of entries.
The following summary applies to primary database backends such as
-the LDBM, BDB, and HDB backends. Requirements for other backends may
+the BDB and HDB backends. Requirements for other backends may
(and often do) differ.
+
.LP
The
.B add
operation requires
-.B write (=w)
+.B add (=a)
privileges on the pseudo-attribute
.B entry
of the entry being added, and
-.B write (=w)
+.B add (=a)
privileges on the pseudo-attribute
.B children
of the entry's parent.
+When adding the suffix entry of a database,
+.B add
+access to
+.B children
+of the empty DN ("") is required. Also if
+Add content ACL checking has been configured on
+the database (see the
+.BR slapd.conf (5)
+or
+.BR slapd\-config (5)
+manual page),
+.B add (=a)
+will be required on all of the attributes being added.
+
.LP
The
.B bind
.B auth (=x)
privileges on the attribute the credentials are stored in (usually
.BR userPassword ).
+
.LP
The
.B compare
operation requires
.B compare (=c)
privileges on the attribute that is being compared.
+
.LP
The
.B delete
operation requires
-.B write (=w)
+.B delete (=z)
privileges on the pseudo-attribute
.B entry
of the entry being deleted, and
-.B write (=w)
+.B delete (=d)
privileges on the
.B children
pseudo-attribute of the entry's parent.
+
.LP
The
.B modify
operation requires
.B write (=w)
-privileges on the attibutes being modified.
+privileges on the attributes being modified.
+In detail,
+.B add (=a)
+is required to add new values,
+.B delete (=z)
+is required to delete existing values,
+and both
+.B delete
+and
+.BR "add (=az)" ,
+or
+.BR "write (=w)" ,
+are required to replace existing values.
+
.LP
The
.B modrdn
privileges on the pseudo-attribute
.B entry
of the entry whose relative DN is being modified,
-.B write (=w)
+.B delete (=z)
privileges on the pseudo-attribute
.B children
-of the old and new entry's parents, and
-.B write (=w)
+of the old entry's parents,
+.B add (=a)
+privileges on the pseudo-attribute
+.B children
+of the new entry's parents, and
+.B add (=a)
privileges on the attributes that are present in the new relative DN.
-.B Write (=w)
+.B Delete (=z)
privileges are also required on the attributes that are present
in the old relative DN if
.B deleteoldrdn
is set to 1.
+
.LP
The
.B search
-operation, for each entry, requires
+operation, requires
+.B search (=s)
+privileges on the
+.B entry
+pseudo-attribute of the searchBase
+(NOTE: this was introduced with OpenLDAP 2.4).
+Then, for each entry, it requires
.B search (=s)
privileges on the attributes that are defined in the filter.
-Then, the resulting entries are tested for
+The resulting entries are finally tested for
.B read (=r)
privileges on the pseudo-attribute
.B entry
(generally the
.B ref
attribute).
+
.LP
Some internal operations and some
.B controls
attribute of the authorizing identity and/or on the
.B authzFrom
attribute of the authorized identity.
+In general, when an internal lookup is performed for authentication
+or authorization purposes, search-specific privileges (see the access
+requirements for the search operation illustrated above) are relaxed to
+.BR auth .
+
+.LP
+Access control to search entries is checked by the frontend,
+so it is fully honored by all backends; for all other operations
+and for the discovery phase of the search operation,
+full ACL semantics is only supported by the primary backends, i.e.
+.BR back\-bdb (5),
+and
+.BR back\-hdb (5).
+
+Some other backend, like
+.BR back\-sql (5),
+may fully support them; others may only support a portion of the
+described semantics, or even differ in some aspects.
+The relevant details are described in the backend-specific man pages.
+
.SH CAVEATS
It is strongly recommended to explicitly use the most appropriate
.B <dnstyle>
and
.B <who>
clauses, to avoid possible incorrect specifications of the access rules
-as well as for performance (avoid unrequired regex matching when an exact
+as well as for performance (avoid unnecessary regex matching when an exact
match suffices) reasons.
.LP
An administrator might create a rule of the form:
default slapd configuration file
.SH SEE ALSO
.BR slapd (8),
+.BR slapd\-* (5),
.BR slapacl (8),
.BR regex (7),
.BR re_format (7)
.LP
"OpenLDAP Administrator's Guide" (http://www.OpenLDAP.org/doc/admin/)
.SH ACKNOWLEDGEMENTS
-.B OpenLDAP
-is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
-.B OpenLDAP
-is derived from University of Michigan LDAP 3.3 Release.
+.so ../Project
projects / openldap / blobdiff