Note that in the following text the term {{user}} is used to describe
a person or application entity who is connecting to the LDAP server
via an LDAP client, such as {{ldapsearch}}(1). That is, the term
-{{user}} not ony applies to both an individual using an LDAP client,
+{{user}} not only applies to both an individual using an LDAP client,
but to an application entity which issues LDAP client operations
without direct user control. For example, an e-mail server which
uses LDAP operations to access information held in an LDAP server
Some mechanisms, such as PLAIN and LOGIN, offer no greater security over
LDAP "simple" authentication. Like "simple" authentication, such
mechanisms should not be used unless you have adequate security
-protections in place. It is recommended that these mechanism be
+protections in place. It is recommended that these mechanisms be
used only in conjunction with {{TERM[expand]TLS}} (TLS). Use of
PLAIN and LOGIN are not discussed further in this document.
of DIGEST-MD5. Use of {{SECT:DIGEST-MD5}} is discussed below.
The KERBEROS_V4 mechanism utilizes Kerberos IV to provide secure
-authentication services. There are also GSSAPI based mechanisms
+authentication services. There is also a GSSAPI based mechanism
which is generally used in conjunction with Kerberos V. Kerberos
is viewed as a secure, distributed authentication system suitable
for both small and large enterprises. Use of {{SECT:KERBEROS_V4}}
The EXTERNAL mechanism utilizes authentication services provided
by lower level network services such as {{TERM:TLS}} (TLS). When
-used in conjunction with TLS X.509-based public key technology,
+used in conjunction with TLS {{TERM:X.509}}-based public key technology,
EXTERNAL offers strong authentication. Use of EXTERNAL is discussed
in the {{SECT:Using TLS}} chapter.
V4 as an example mechanism. The steps necessary for your site's
authentication mechanism will be similar, but a guide to every
mechanism available under SASL is beyond the scope of this chapter.
-The next section after that describes the second step of mapping
-authentication identities to DN's.
-
-
-H3: GSSAPI
-
-This section describes the use of the SASL GSSAPI mechanism and
-Kerberos V with OpenLDAP. It will be assumed that you have Kerberos
-V deployed, you are familiar with the operation of the system, and that
-your users are trained its use. This section also assumes you have
-familiarized yourself with the use of the GSSAPI mechanism by reading
-{{Configuring GSSAPI and Cyrus SASL}} (provided with Cyrus SASL in
-the {{FILE:doc/gssapi}} file) and successfully experimented with
-the Cyrus provided sample_server and sample_client applications.
-General information about Kerberos is available at
-{{URL:http://web.mit.edu/kerberos/www/}}.
-
-To use the GSSAPI mechanism with {{slapd}}(8) one must create a service
-key with a principal for {{ldap}} service within the realm for the host
-on which the service runs. For example, if your run {{slapd}} on
-{{EX:directory.example.com}} and your realm is {{EX:EXAMPLE.COM}},
-you need to create a service key with the principal:
-
-> ldap/directory.example.com@EXAMPLE.COM
-
-When {{slapd}}(8) runs, it must have access to this key. This is
-generally done by placing the key into a keytab, such as
-{{FILE:/etc/krb5.keytab}}.
-
-To use the GSSAPI mechanism to authenticate to the directory, the
-user obtains a Ticket Granting Ticket (TGT) prior to running the
-LDAP client. When using OpenLDAP client tools, the user may mandate
-use of the GSSAPI mechanism by specifying {{EX:-Y GSSAPI}} as a
-command option.
-
-For the purposes of authentication and authorization, {{slapd}}(8)
-associates a non-mapped authentication DN of the form:
-
-> uid=principal,cn=GSSAPI,cn=auth
-
-If the user principal is within the same realm, the realm is
-trimmed from the principal. Continuting our example, a user
-with the Kerberos principal {{EX:kurt@EXAMPLE.COM}} would have
-the associated DN:
-
-> uid=kurt,cn=GSSAPI,cn=auth
-
-and the principal {{EX:ursula@@FORIEGN.REALM}} would have the
-associated DN:
-
-> uid=ursula@FOREIGN-REALM,cn=GSSAPI,cn=auth
-
+The second step is described in the section
+{{SECT:Mapping Authentication identities to LDAP entries}}.
H3: KERBEROS_V4
This section describes the use of the SASL KERBEROS_V4 mechanism
with OpenLDAP. It will be assumed that you are familiar with the
-workings of Kerberos IV security system, and that your site has
+workings of the Kerberos IV security system, and that your site has
Kerberos IV deployed. Your users should be familiar with
-authentication policy, are aware of how to receive credentials in
+authentication policy, how to receive credentials in
a Kerberos ticket cache, and how to refresh expired credentials.
Client programs will need to be able to obtain a session key for
So in our above example, if the user's name were "adamson", the
authentication request DN would be:
-> uid=ADAMSON,cn=EXAMPLE.COM,cn=KERBEROS_V4,cn=AUTH
+> uid=adamsom,cn=example.com,cn=kerberos_v4,cn=auth
This authentication request DN by itself could be placed into ACL's
and {{EX:groupOfNames}} "member" attributes, since it is of legitimate
-LDAP DN format. The next section, however, tells how to map that
+LDAP DN format. The section
+{{SECT:Mapping Authentication identities to LDAP entries}},
+however, tells how to map that
DN into the DN of a person's own LDAP entry.
Also note that this example, being for Kerberos, shows the <realm>
portion of the DN being filled in with the Kerberos realm of the
-company. Several other authentication mechanisms do not emply the
+company. Several other authentication mechanisms do not employ the
concept of a realm, so the ",cn=<realm>" portion of the authentication
request DN would not appear.
+H3: GSSAPI
+
+This section describes the use of the SASL GSSAPI mechanism and
+Kerberos V with OpenLDAP. Since Kerberos V is being used, the information
+is very similar to the previous section.
+It will be assumed that you have Kerberos
+V deployed, you are familiar with the operation of the system, and that
+your users are trained in its use. This section also assumes you have
+familiarized yourself with the use of the GSSAPI mechanism by reading
+{{Configuring GSSAPI and Cyrus SASL}} (provided with Cyrus SASL in
+the {{FILE:doc/gssapi}} file) and successfully experimented with
+the Cyrus provided sample_server and sample_client applications.
+General information about Kerberos is available at
+{{URL:http://web.mit.edu/kerberos/www/}}.
+
+To use the GSSAPI mechanism with {{slapd}}(8) one must create a service
+key with a principal for {{ldap}} service within the realm for the host
+on which the service runs. For example, if you run {{slapd}} on
+{{EX:directory.example.com}} and your realm is {{EX:EXAMPLE.COM}},
+you need to create a service key with the principal:
+
+> ldap/directory.example.com@EXAMPLE.COM
+
+When {{slapd}}(8) runs, it must have access to this key. This is
+generally done by placing the key into a keytab, such as
+{{FILE:/etc/krb5.keytab}}.
+
+To use the GSSAPI mechanism to authenticate to the directory, the
+user obtains a Ticket Granting Ticket (TGT) prior to running the
+LDAP client. When using OpenLDAP client tools, the user may mandate
+use of the GSSAPI mechanism by specifying {{EX:-Y GSSAPI}} as a
+command option.
+
+For the purposes of authentication and authorization, {{slapd}}(8)
+associates a non-mapped authentication request DN of the form:
+
+> uid=<principal>,cn=<realm>,cn=gssapi,cn=auth
+
+Continuing our example, a user
+with the Kerberos principal {{EX:kurt@EXAMPLE.COM}} would have
+the associated DN:
+
+> uid=kurt,cn=example.com,cn=gssapi,cn=auth
+
+and the principal {{EX:ursula@FOREIGN.REALM}} would have the
+associated DN:
+
+> uid=ursula,cn=foreign.realm,cn=gssapi,cn=auth
+
+
+H3: DIGEST-MD5
+
+This section describes the use of the SASL DIGEST-MD5 mechanism using
+secrets stored either in the directory itself or in Cyrus SASL's own
+database. DIGEST-MD5 relies on the client and the server sharing a
+"secret", usually a password. The server generates a challenge and the
+client a response proving that it knows the shared secret. This is much
+more secure than simply sending the secret over the wire.
+
+Cyrus SASL supports several shared-secret mechanisms. To do this, it
+needs access to the plaintext password (unlike mechanisms which pass
+plaintext passwords over the wire, where the server can store a hashed
+version of the password).
+
+Secret passwords are normally stored in Cyrus SASL's own {{sasldb}}
+database, but if OpenLDAP has been compiled with Cyrus SASL 2.1 it is
+possible to store the secrets in the LDAP database itself. With Cyrus
+SASL 1.5, secrets may only be stored in the {{sasldb}}. In either
+case it is very important to apply file access controls and LDAP access
+controls to prevent exposure of the passwords.
+
+The configuration and commands discussed in this section assume the use
+of Cyrus SASL 2.1. If you are using version 1.5 then certain features
+will not be available, and the command names will not have the trailing
+digit "2".
+
+To use secrets stored in {{sasldb,}} simply add users with the
+{{saslpasswd2}} command:
+
+> saslpasswd2 -c <username>
+
+The passwords for such users must be managed with the {{saslpasswd2}}
+command.
+
+To use secrets stored in the LDAP directory, place plaintext passwords
+in the {{EX:userPassword}} attribute. It will be necessary to add an
+option to {{EX:slapd.conf}} to make sure that passwords changed through
+LDAP are stored in plaintext:
+
+> password-hash {CLEARTEXT}
+
+Passwords stored in this way can be managed either with {{EX:ldappasswd}}
+or by simply modifying the {{EX:userPassword}} attribute.
+
+Wherever the passwords are stored, a mapping will be needed from SASL
+authentication IDs to regular DNs. The DIGEST-MD5 mechanism produces
+authentication IDs of the form:
+
+> uid=<username>,cn=<realm>,cn=digest-md5,cn=auth
+
+NOTE that if the default realm is used, the realm name is omitted from
+the ID, giving:
+
+> uid=<username>,cn=digest-md5,cn=auth
+
+See {{SECT: Mapping Authentication identities to LDAP entries}} below
+for information on mapping such IDs to DNs.
+
+With suitable mappings in place, users can specify SASL IDs when
+performing LDAP operations, and the password stored in {{sasldb}} or in
+the directory itself will be used to verify the authentication.
+For example, the user identified by the directory entry:
+
+> dn: cn=Andrew Findlay+uid=u000997,dc=example,dc=com
+> objectclass: inetOrgPerson
+> objectclass: person
+> sn: Findlay
+> uid: u000997
+> userPassword: secret
+
+can issue commands of the form:
+
+> ldapsearch -U u000997 -b dc=example,dc=com 'cn=andrew*'
+
+or can specify the realm explicitly:
+
+> ldapsearch -U u000997@myrealm -b dc=example,dc=com 'cn=andrew*'
+
+If several SASL mechanisms are supported at your site, it may be
+necessary to specify which one to use, e.g.:
+
+> ldapsearch -Y DIGEST-MD5 -U u000997 -b dc=example,dc=com 'cn=andrew*'
+
+
+
H3: Mapping Authentication identities to LDAP entries
The authentication mechanism in the slapd server will use SASL
library calls to obtain the authenticated user's "username", based
on whatever underlying authentication mechanism was used. This
username is in the namespace of the authentication mechanism, and
-not in the LDAP namespace. As stated in the section above, that
+not in the LDAP namespace. As stated in the sections above, that
username is reformatted into an authentication request DN of the
form
> uid=<username>,cn=<mechanism>,cn=auth
depending on whether or not <mechanism> employs the concept of
-"realms".
+"realms". Note also that the realm part will be omitted if the default
+realm was used in the authentication.
It is not intended that you should add LDAP entries of the above
form to your LDAP database. Chances are you have an LDAP entry for
The LDAP administrator will need to tell the slapd server how to
map an authentication request DN to a user's authentication DN.
-This is done by adding one or more {{EX:saslRegexp}} directives to
+This is done by adding one or more {{EX:sasl-regexp}} directives to
the {{slapd.conf}}(5) file. This directive takes two arguments:
-> saslRegexp <search pattern> <replacement pattern>
+> sasl-regexp <search pattern> <replacement pattern>
The authentication request DN is compared to the search pattern
using the regular expression functions {{regcomp}}() and {{regexec}}(),
and if it matches, it is rewritten as the replacement pattern. If
-there are multiple {{EX:saslRegexp}} directives, only the first
+there are multiple {{EX:sasl-regexp}} directives, only the first
whose search pattern matches the authentication identity is used.
The string that is output from the replacement pattern should be
the authentication DN of the user, in a legitimate LDAP DN format.
characters listed in {{regexec}}(3C). The main characters of note
are dot ".", asterisk "*", and the open and close parenthesis "("
and ")". Essentially, the dot matches any character, the asterisk
-matches one or more characters, and terms in parenthesis are
+allows zero or more repeats of the immediately preceding character or
+pattern, and terms in parenthesis are
remembered for the replacement pattern.
The replacement pattern will produce the final authentication DN
matched a string in parenthesis in the search pattern is stored in
the variable "$1". That variable "$1" can appear in the replacement
pattern, and will be replaced by the string from the authentication
-request DN. If there were multiple sets of parenthesis in the search
+request DN. If there were multiple sets of parentheses in the search
pattern, the variables $2, $3, etc are used.
For example, suppose the user's authentication identity is written
as the DN string
-> uid=ADAMSON,cn=EXAMPLE.COM,cn=KERBEROS_V4,cn=AUTH
+> uid=adamson,cn=example.com,cn=kerberos_v4,cn=auth
and the user's actual LDAP entry is
-> uid=ADAMSON,ou=PERSON,dc=EXAMPLE,dc=COM
+> uid=adamson,ou=person,dc=example,dc=com
-The {{EX:saslRegexp}} directive in {{slapd.conf}}(5) could be
+The {{EX:sasl-regexp}} directive in {{slapd.conf}}(5) could be
written
-> saslRegexp
+> sasl-regexp
> uid=(.*),cn=example.com,cn=kerberos_v4,cn=auth
> uid=$1,ou=person,dc=example,dc=com
An even more lenient rule could be written as
-> saslRegexp
-> uid=(.*),.*cn=auth
+> sasl-regexp
+> uid=(.*),cn=.*,cn=auth
> uid=$1,ou=person,dc=example,dc=com
Be careful about setting the search pattern too leniently, however,
security holes. If there is only one authentication mechanism in
place at your site, and zero or one realms in use, you might be
able to map between authentication identities and LDAP DN's with
-a single {{EX:saslRegexp}} directive.
+a single {{EX:sasl-regexp}} directive.
+
+Don't forget to allow for the case where the realm is omitted as well
+as the case with an explicitly specified realm. This may well
+require a separate {{EX:sasl-regexp}} directive for each case, with the
+explicit-realm entry being listed first.
Some sites may have people's DN's spread to multiple areas of the
LDAP tree, such as if there were an ou=accounting tree and an
In this case, the information in the authentication identity can
only be used to search for the user's DN, not derive it directly.
For both of these situations, and others, the replacement pattern
-in the {{EX:saslRegexp}} directives will need to produce an LDAP
+in the {{EX:sasl-regexp}} directives will need to produce an LDAP
URL, described in the next section.
H3: Performing searches for a person's DN
When there is not enough information in the authentication identity
-to derive a person's authentication DN directly, the {{EX:saslRegexp}}
+to derive a person's authentication DN directly, the {{EX:sasl-regexp}}
directives in the {{slapd.conf}}(5) file will need to produce an
LDAP URL. This URL will then be used to perform an internal search
of the LDAP database to find the person's authentication DN.
<base>, the LDAP attributes to retrieve <attrs>, the search scope
<scope> which is one of the three options "base", "one", or "sub",
and lastly an LDAP search filter <filter>. Since the search is for
-an LDAP DN on the local machine, the <host> portion is ignored. By
-the same token the <attrs> field is also ignored since only the DN
-is of concern. These two elements are left in the format of the
-URL to maintain the clarity of what information goes where in the
-string.
+an LDAP DN on the local machine, the <host> portion should be empty.
+The <attrs> field is also ignored since only the DN is of concern.
+These two elements are left in the format of the URL to maintain
+the clarity of what information goes where in the string.
Suppose that the person in the example from above did in fact have
an authentication username of "adamson" and that information was
-kept in the attribute "uid" in their LDAP entry. The {{EX:saslRegexp}}
+kept in the attribute "uid" in their LDAP entry. The {{EX:sasl-regexp}}
directive might be written as
-> saslRegexp
+> sasl-regexp
> uid=(.*),cn=example.com,cn=kerberos_v4,cn=auth
-> ldap://localhost/ou=person,dc=example,dc=com??sub?uid=$1
+> ldap:///ou=person,dc=example,dc=com??sub?(uid=$1)
This will initiate an internal search of the LDAP database inside
the slapd server. If the search returns exactly one entry, it is
the authentication step alone can take uncomfortably long periods,
and users may assume the server is down.
+A more complex site might have several realms in use, each mapping to
+a different sub-tree in the directory. These can be handled with
+statements of the form:
+
+> # Match Engineering realm
+> sasl-regexp
+> uid=(.*),cn=engineering.example.com,cn=digest-md5,cn=auth
+> ldap:///dc=eng,dc=example,dc=com??sub?(&(uid=$1)(objectClass=person))
+>
+> # Match Accounting realm
+> sasl-regexp
+> uid=(.*),cn=accounting.example.com,cn=digest-md5,cn=auth
+> ldap:///dc=accounting,dc=example,dc=com??sub?(&(uid=$1)(objectClass=person))
+>
+> # Default realm is customers.example.com
+> sasl-regexp
+> uid=(.*),cn=digest-md5,cn=auth
+> ldap:///dc=customers,dc=example,dc=com??sub?(&(uid=$1)(objectClass=person))
+
+Note that the explicitly-named realms are handled first, to avoid the
+realm name becoming part of the UID. Note also the limitation of
+matches to those entries with objectClass=person to avoid matching
+other entries that happen to refer to the UID.
+
+See {{slapd.conf}}(5) for more detailed information.
+
H2: SASL Authorization
cannot be made by SASL alone. The SASL library leaves it up to the
server to make the decision. The LDAP administrator sets the
guidelines of who can authorize to what identity by adding information
-into the LDAP database entries.
-
+into the LDAP database entries. By default, the authorization
+features are disabled, and must be explicitly configured by the
+LDAP administrator before use.
H3: Uses of Authorization
by the same function that the authentication process used, producing
an {{authorization request DN}} of the form
-> uid=<username>,cn=<realm>,cn=auth
+> uid=<username>,cn=<realm>,cn=<mechanism>,cn=auth
That authorization request DN is then run through the same
-{{EX:saslRegexp}} process to convert it into a legitimate authorization
+{{EX:sasl-regexp}} process to convert it into a legitimate authorization
DN from the database. If it cannot be converted due to a failed
search from an LDAP URL, the authorization request fails with
"inappropriate access". Otherwise, the DN string is now a legitimate
authorization DN ready to undergo approval.
If the authorization identity was provided in the second form, with
-a {EX:"dn:"}} prefix, the string after the prefix is already in
+a {{EX:"dn:"}} prefix, the string after the prefix is already in
authorization DN form, ready to undergo approval.
> saslAuthzTo
> saslAuthzFrom
-Both can be multivalued. The first is called a source rule, and it
-is placed into a person's authentication DN entry to tell what
-other authorization DN's the person is allowed to change to. The
-second form is called a destination rule, and it is placed into an
-authorization DN's entry to tell what authenticated DN a person
-must be coming from in order to switch to that authorization DN.
-The choice of which form to use is up to the administrator. Source
-rules are checked first in the person's authentication DN entry,
-and if none of the {{EX:saslAuthzTo}} rules specify the authorization
-is permitted, the {{EX:saslAuthzFrom}} rules in the authorization
-DN entry are then checked. If neither case specifies that the
-request be honored, the request is denied with an "inappropriate
-access" message. Since the default behaviour is to deny authorization
-requests, rules only specify that a request be allowed; there are
-no negative rules telling what authorizations to deny.
+Both can be multivalued. The {{EX:saslAuthzTo}} attribute is a
+source rule, and it is placed into the entry associated with the
+authentication DN to tell what authorization DNs the authenticated
+DN is allowed to assume. The second attribute is a destination
+rule, and it is placed into the entry associated with the requested
+authorization DN to tell which authenticated DNs may assume it.
+
+The choice of which authorization policy attribute to use is up to
+the administrator. Source rules are checked first in the person's
+authentication DN entry, and if none of the {{EX:saslAuthzTo}} rules
+specify the authorization is permitted, the {{EX:saslAuthzFrom}}
+rules in the authorization DN entry are then checked. If neither
+case specifies that the request be honored, the request is denied.
+Since the default behaviour is to deny authorization requests, rules
+only specify that a request be allowed; there are no negative rules
+telling what authorizations to deny.
The value(s) in the two attributes are of the same form as the
-output of the replacement pattern of a {{EX:saslRegexp}} directive:
-either a DN or an LDAP URL. For example, if a saslAuthzTo value is
-a DN, that DN is one the authenticated user can authorize to. On
-the other hand, if the {{EX:saslAuthzTo}} value is an LDAP URL,
-the URL is used as an internal search of the LDAP database, and
-the authenticated user can become ANY DN returned by the search.
+output of the replacement pattern of a {{EX:sasl-regexp}} directive:
+either a DN or an LDAP URL. For example, if a {{EX:saslAuthzTo}}
+value is a DN, that DN is one the authenticated user can authorize
+to. On the other hand, if the {{EX:saslAuthzTo}} value is an LDAP
+URL, the URL is used as an internal search of the LDAP database,
+and the authenticated user can become ANY DN returned by the search.
If an LDAP entry looked like:
> dn: cn=WebUpdate,dc=example,dc=com
-> saslAuthzTo: ldap://host/dc=example,dc=com??sub?objectclass=Person
+> saslAuthzTo: ldap:///dc=example,dc=com??sub?(objectclass=Person)
then any user who authenticated as cn=WebUpdate,dc=example,dc=com
could authorize to any other LDAP entry under the search base
as a DN. It is not permissable to enter another authorization
identity of the form "u:<username>" as an authorization rule.
-The decision of which type of rules to use, saslAuthzFrom or
-saslAuthzTo, will depend on the site's situation. For example, if
+H4: Policy Configuration
+
+The decision of which type of rules to use, {{EX:saslAuthzFrom}} or
+{{EX:saslAuthzTo}}, will depend on the site's situation. For example, if
the set of people who may become a given identity can easily be
written as a search filter, then a single destination rule could
be written. If the set of people is not easily defined by a search
a source rule in the entries of each of those people who should be
allowed to perform the authorization.
+By default, processing of authorization rules is disabled. The
+{{EX:sasl-authz-policy}} directive must be set in the {{slapd.conf}}(5) file
+to enable authorization. This directive can be set to {{EX:none}}
+for no rules (the default), {{EX:from}} for source rules, {{EX:to}}
+for destination rules, or {{EX:both}} for both source and destination
+rules.
+
+Destination rules are extremely powerful. If ordinary users have
+access to write the {{EX:saslAuthzTo}} attribute in their own entries, then
+they can write rules that would allow them to authorize as anyone else.
+As such, when using destination rules, the {{EX:saslAuthzTo}} attribute
+should be protected with an ACL that only allows privileged users
+to set its values.
projects / openldap / blobdiff