SASL in OpenLDAP.
There are several industry standard authentication mechanisms that
-can be used with SASL, including Kerberos V4, GSSAPI, and some of
-the Digest mechanisms. The standard client tools provided with
-OpenLDAP, such as {{ldapsearch}}(1) and {{ldapmodify}}(1), will by
-default attempt to authenticate the user to the {{slapd}}(8) server
-using SASL. Basic authentication service can be set up by the LDAP
+can be used with SASL, including {{TERM:Kerberos}} V4, {{TERM:GSSAPI}},
+and DIGEST-MD. The standard client tools provided with OpenLDAP,
+such as {{ldapsearch}}(1) and {{ldapmodify}}(1), will by default
+attempt to authenticate the user to the {{slapd}}(8) server using
+SASL. Basic authentication service can be set up by the LDAP
administrator with a few steps, allowing users to be authenticated
to the slapd server as their LDAP entry. With a few extra steps,
-some users and services can be allowed to exploit SASL's authorization
-feature, allowing them to authenticate themselves and then switch
-their identity to that of another user or service.
+some users and services can be allowed to exploit SASL's proxy
+authorization feature, allowing them to authenticate themselves and
+then switch their identity to that of another user or service.
This chapter assumes you have read {{Cyrus SASL for System
Administrators}}, provided with the {{PRD:Cyrus}} {{PRD:SASL}}
-package (in {{FILE:doc/sysadmin.html}}).
+package (in {{FILE:doc/sysadmin.html}}) and have a working Cyrus
+SASL installation. You should use the Cyrus SASL {{EX:sample_client}}
+and {{EX:sample_server}} to test your SASL installation before
+attempting to make use of it in OpenLDAP.
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
The EXTERNAL mechanism utilizes authentication services provided
by lower level network services such as {{TERM:TLS}} (TLS). When
-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.
+used in conjunction with {{TERM:TLS}} {{TERM:X.509}}-based public
+key technology, EXTERNAL offers strong authentication. Use of
+EXTERNAL is discussed in the {{SECT:Using TLS}} chapter.
There are other strong authentication mechanisms to choose from,
including OTP (one time passwords) and SRP (secure remote passwords).
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
+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
+{{EX:sample_server}} and {{EX: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
> 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*'
+
+
+Note: in each of the above cases, no authorization identity (e.g.
+{{EX:-X}}) was provided. Unless you are attempting
+{{SECT:SASL Proxy Authorization}}, no authorization identity should
+be specified. The server will infer an authorization identity from
+authentication identity (as described below).
+
+
H3: Mapping Authentication identities to LDAP entries
The authentication mechanism in the slapd server will use SASL
> 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
in your directory tree, and the tree does not start at cn=auth.
But if your site has a clear mapping between the "username" and an
LDAP entry for the person, you will be able to configure your LDAP
-server to automatically map a user's authentication username to
-their {{authentication DN}}.
+server to automatically map a authentication request DN to the
+user's {{authentication DN}}.
+
+Note: it is not required that the authentication request DN nor the
+user's authentication DN resulting from the mapping refer to an
+entry held in the directory. However, additional capabilities
+become available (see below).
The LDAP administrator will need to tell the slapd server how to
map an authentication request DN to a user's authentication DN.
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
An even more lenient rule could be written as
> sasl-regexp
-> uid=(.*),.*cn=auth
+> uid=(.*),cn=.*,cn=auth
> uid=$1,ou=person,dc=example,dc=com
Be careful about setting the search pattern too leniently, however,
able to map between authentication identities and LDAP DN's with
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
-ou=engineering tree, with people interspersed between them. Or
+LDAP tree, such as if there were an {{EX:ou=accounting}} tree and an
+{{EX:ou=engineering}} tree, with people interspersed between them. Or
there may not be enough information in the authentication identity
to isolate the DN, such as if the above person's LDAP entry looked
like
search: the name of the server <host>, the LDAP DN search base
<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 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.
+and lastly an LDAP search filter <filter>. Since the search is for
+an LDAP DN within the current server, 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
the authentication step alone can take uncomfortably long periods,
and users may assume the server is down.
-
-H2: SASL Authorization
-
-The SASL offers a feature known as {{authorization}}, which allows
-an authenticated user to request that they act on the behalf of
-another user. This step occurs after the user has obtained an
+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 {{EX:(objectClass=person)}} to
+avoid matching other entries that happen to refer to the UID.
+
+See {{slapd.conf}}(5) for more detailed information.
+
+
+H2: SASL Proxy Authorization
+
+The SASL offers a feature known as {{proxy authorization}}, which
+allows an authenticated user to request that they act on the behalf
+of another user. This step occurs after the user has obtained an
authentication DN, and involves sending an authorization identity
to the server. The server will then make a decision on whether or
not to allow the authorization to occur. If it is allowed, the
features are disabled, and must be explicitly configured by the
LDAP administrator before use.
-H3: Uses of Authorization
+
+H3: Uses of Proxy Authorization
This sort of service is useful when one entity needs to act on the
behalf of many other users. For example, users may be directed to
of LDAP clients, knowledge which the web page provides in an easier
format.
-Authorization can also be used to limit access to an account that
-has greater access to the database. Such an account, perhaps even
-the root DN specified in {{slapd.conf}}(5), can have a strict list
-of people who can authorize to that DN. Changes to the LDAP database
-could then be only allowed by that DN, and in order to become that
-DN, users must first authenticate as one of the persons on the
-list. This allows for better auditing of who made changes to the
-LDAP database. If people were allowed to authenticate directly to
-the priviliged account, possibly through the {{EX:rootpw}}
+Proxy authorization can also be used to limit access to an account
+that has greater access to the database. Such an account, perhaps
+even the root DN specified in {{slapd.conf}}(5), can have a strict
+list of people who can authorize to that DN. Changes to the LDAP
+database could then be only allowed by that DN, and in order to
+become that DN, users must first authenticate as one of the persons
+on the list. This allows for better auditing of who made changes
+to the LDAP database. If people were allowed to authenticate
+directly to the priviliged account, possibly through the {{EX:rootpw}}
{{slapd.conf}}(5) directive or through a {{EX:userPassword}}
attribute, then auditing becomes more difficult.
-Note that after a successful authorization, the original authentication
-DN in the LDAP connection is overwritten by the new DN from the
-authorization request. If a service program is able to authenticate
-itself as its own authentication DN and then authorize to other
-DN's, and it is planning on switching to several different identities
-during one LDAP session, it will need to authenticate itself each
-time before authorizing to another DN. The slapd server does not
-keep record of the service program's ability to switch to other
-DN's. On authentication mechanisms like Kerberos this will not
-require multiple connections being made to the Kerberos server,
-since the user's TGT and "ldap" session key are valid for multiple
-uses for the several hours of the ticket lifetime.
+Note that after a successful proxy authorization, the original
+authentication DN of the LDAP connection is overwritten by the new
+DN from the authorization request. If a service program is able to
+authenticate itself as its own authentication DN and then authorize
+to other DN's, and it is planning on switching to several different
+identities during one LDAP session, it will need to authenticate
+itself each time before authorizing to another DN (or use a different
+proxy authorization mechanism). The slapd server does not keep
+record of the service program's ability to switch to other DN's.
+On authentication mechanisms like Kerberos this will not require
+multiple connections being made to the Kerberos server, since the
+user's TGT and "ldap" session key are valid for multiple uses for
+the several hours of the ticket lifetime.
-H3: Authorization Identities
+H3: SASL Authorization Identities
-The authorization identity is sent to the slapd server via the -X
-switch for {{ldapsearch}}(1) and other tools, or in the *authzid
-parameter to the {{lutil_sasl_defaults}}() call. The identity can
-be in one of two forms, either
+The SASL authorization identity is sent to the LDAP server via the
+{{EX:-X}} switch for {{ldapsearch}}(1) and other tools, or in the
+{{EX:*authzid}} parameter to the {{lutil_sasl_defaults}}() call.
+The identity can be in one of two forms, either
> u:<username>
authorization DN form, ready to undergo approval.
-H3: Authorization rules
+H3: Proxy Authorization Rules
Once slapd has the authorization DN, the actual approval process
begins. There are two attributes that the LDAP administrator can
"dc=example,dc=com" which has an objectClass of "Person".
-H4: Notes on Authorization rules
+H4: Notes on Proxy Authorization Rules
An LDAP URL in a {{EX:saslAuthzTo}} or {{EX:saslAuthzFrom}} attribute
will return a set of DNs. Each DN returned will be checked.
would allow that authenticated user to authorize to any DN that
matches the regular expression pattern given. This regular expression
comparison can be evaluated much faster than an LDAP search for
-"uid=*".
+{{EX:(uid=*)}}.
Also note that the values in an authorization rule must be one of
the two forms: an LDAP URL or a DN (with or without regular expression
-characters). Anything that does not begin with "ldap://" is taken
-as a DN. It is not permissable to enter another authorization
-identity of the form "u:<username>" as an authorization rule.
+characters). Anything that does not begin with "{{EX:ldap://}}" is
+taken as a DN. It is not permissable to enter another authorization
+identity of the form "{{EX:u:<username>}}" as an authorization rule.
+
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
-filter, and the set of people is small, it may be better to write
-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.
+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 filter, and the set of people is small, it may be better
+to write a source rule in the entries of each of those people who
+should be allowed to perform the proxy authorization.
+
+By default, processing of proxy 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
projects / openldap / blobdiff