15. Using SASL
OpenLDAP clients and servers are capable of authenticating via the
There are several industry standard authentication mechanisms that can be used with SASL, including
The standard client tools provided with OpenLDAP Software, such as ldapsearch(1) and ldapmodify(1), will by default attempt to authenticate the user to the
This chapter assumes you have read Cyrus SASL for System Administrators, provided with the Cyrus SASL package (in doc/sysadmin.html) and have a working Cyrus SASL installation. You should use the Cyrus SASL sample_client and sample_server to test your SASL installation before attempting to make use of it with OpenLDAP Software.
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 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 is an application entity.
15.1. SASL Security Considerations
SASL offers many different authentication mechanisms. This section briefly outlines security considerations.
Some mechanisms, such as PLAIN and LOGIN, offer no greater security over LDAP simple authentication. Like LDAP simple authentication, such mechanisms should not be used unless you have adequate security protections in place. It is recommended that these mechanisms be used only in conjunction with
The DIGEST-MD5 mechanism is the mandatory-to-implement authentication mechanism for LDAPv3. Though DIGEST-MD5 is not a strong authentication mechanism in comparison with trusted third party authentication systems (such as
The GSSAPI mechanism utilizes
The EXTERNAL mechanism utilizes authentication services provided by lower level network services such as
EXTERNAL can also be used with the ldapi:/// transport, as Unix-domain sockets can report the UID and GID of the client process.
There are other strong authentication mechanisms to choose from, including
15.2. SASL Authentication
Getting basic SASL authentication running involves a few steps. The first step configures your slapd server environment so that it can communicate with client programs using the security system in place at your site. This usually involves setting up a service key, a public key, or other form of secret. The second step concerns mapping authentication identities to LDAP
15.2.1. 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 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 doc/gssapi file) and successfully experimented with the Cyrus provided sample_server and sample_client applications. General information about Kerberos is available at 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 directory.example.com and your realm is 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 file, /etc/krb5.keytab. See your Kerberos and Cyrus SASL documentation for information regarding keytab location settings.
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 -Y GSSAPI as a command option.
For the purposes of authentication and authorization, slapd(8) associates an authentication request DN of the form:
uid=<primary[/instance]>,cn=<realm>,cn=gssapi,cn=auth
Continuing our example, a user with the Kerberos principal kurt@EXAMPLE.COM would have the associated DN:
uid=kurt,cn=example.com,cn=gssapi,cn=auth
and the principal ursula/admin@FOREIGN.REALM would have the associated DN:
uid=ursula/admin,cn=foreign.realm,cn=gssapi,cn=auth
The authentication request DN can be used directly ACLs and groupOfNames "member" attributes, since it is of legitimate LDAP DN format. Or alternatively, the authentication DN could be mapped before use. See the section Mapping Authentication Identities for details.
15.2.2. 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 the Kerberos IV security system, and that your site has Kerberos IV deployed. Your users should be familiar with authentication policy, how to receive credentials in a Kerberos ticket cache, and how to refresh expired credentials.
Note: KERBEROS_V4 and Kerberos IV are deprecated in favor of GSSAPI and Kerberos V.
Client programs will need to be able to obtain a session key for use when connecting to your LDAP server. This allows the LDAP server to know the identity of the user, and allows the client to know it is connecting to a legitimate server. If encryption layers are to be used, the session key can also be used to help negotiate that option.
The slapd server runs the service called "ldap", and the server will require a srvtab file with a service key. SASL aware client programs will be obtaining an "ldap" service ticket with the user's ticket granting ticket (TGT), with the instance of the ticket matching the hostname of the OpenLDAP server. For example, if your realm is named EXAMPLE.COM and the slapd server is running on the host named directory.example.com, the /etc/srvtab file on the server will have a service key
ldap.directory@EXAMPLE.COM
When an LDAP client is authenticating a user to the directory using the KERBEROS_IV mechanism, it will request a session key for that same principal, either from the ticket cache or by obtaining a new one from the Kerberos server. This will require the TGT to be available and valid in the cache as well. If it is not present or has expired, the client may print out the message:
ldap_sasl_interactive_bind_s: Local error
When the service ticket is obtained, it will be passed to the LDAP server as proof of the user's identity. The server will extract the identity and realm out of the service ticket using SASL library calls, and convert them into an authentication request DN of the form
uid=<username>,cn=<realm>,cn=<mechanism>,cn=auth
So in our above example, if the user's name were "adamson", the authentication request DN would be:
uid=adamsom,cn=example.com,cn=kerberos_v4,cn=auth
This authentication request DN can be used directly ACLs or, alternatively, mapped prior to use. See the section Mapping Authentication Identities for details.
15.2.3. 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).
The server's copy of the shared-secret may be stored in Cyrus SASL's own sasldb database, in an external system accessed via saslauthd, or in LDAP database itself. 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.
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 userPassword attribute. It will be necessary to add an option to slapd.conf to make sure that passwords set using the LDAP Password Modify Operation are stored in plaintext:
password-hash {CLEARTEXT}
Passwords stored in this way can be managed either with ldappasswd(1) or by simply modifying the userPassword attribute. Regardless of where the passwords are stored, a mapping will be needed from authentication request DN to user's DN.
The DIGEST-MD5 mechanism produces authentication IDs of the form:
uid=<username>,cn=<realm>,cn=digest-md5,cn=auth
If the default realm is used, the realm name is omitted from the ID, giving:
uid=<username>,cn=digest-md5,cn=auth
See Mapping Authentication Identities below for information on optional mapping of identities.
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 -Y DIGEST-MD5 -U u000997 ...
Note: in each of the above cases, no authorization identity (e.g. -X) was provided. Unless you are attempting SASL Proxy Authorization, no authorization identity should be specified. The server will infer an authorization identity from authentication identity (as described below).
15.2.4. EXTERNAL
The SASL EXTERNAL mechanism makes use of an authentication performed by a lower-level protocol: usually
Each transport protocol returns Authentication Identities in its own format:
15.2.4.1. TLS Authentication Identity Format
This is the Subject DN from the client-side certificate. Note that DNs are displayed differently by LDAP and by X.509, so a certificate issued to
C=gb, O=The Example Organisation, CN=A Person
will produce an authentication identity of:
cn=A Person,o=The Example Organisation,c=gb
Note that you must set a suitable value for TLSVerifyClient to make the server request the use of a client-side certificate. Without this, the SASL EXTERNAL mechanism will not be offered. Refer to the Using TLS chapter for details.
15.2.4.2. IPC (ldapi:///) Identity Format
This is formed from the Unix UID and GID of the client process:
gidNumber=<number>+uidNumber=<number>,cn=peercred,cn=external,cn=auth
Thus, a client process running as root will be:
gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth
15.2.5. Mapping Authentication Identities
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 normal LDAP namespace. As stated in the sections above, that username is reformatted into an authentication request DN of the form
uid=<username>,cn=<realm>,cn=<mechanism>,cn=auth
or
uid=<username>,cn=<mechanism>,cn=auth
depending on whether or not <mechanism> employs the concept of "realms". Note also that the realm part will be omitted if the default realm was used in the authentication.
The ldapwhoami(1) command may be used to determine the identity associated with the user. It is very useful for determining proper function of mappings.
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 each of the persons that will be authenticating to LDAP, laid out 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 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. This is done by adding one or more authz-regexp directives to the slapd.conf(5) file. This directive takes two arguments:
authz-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 authz-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 or an LDAP URL. If replacement string produces a DN, the entry named by this DN need not be held by this server. If the replace string produces an LDAP URL, that LDAP URL must evaluate to one and only one entry held by this server.
The search pattern can contain any of the regular expression 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 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 either a DN or URL referring to the user. Anything from the authentication request DN that 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 parentheses in the search pattern, the variables $2, $3, etc are used.
15.2.6. Direct Mapping
Where possible, direct mapping of the authentication request DN to the user's DN is generally recommended. Aside from avoiding the expense of searching for the user's DN, it allows mapping to DNs which refer to entries not held by this server.
Suppose the authentication request DN is written as:
uid=adamson,cn=example.com,cn=gssapi,cn=auth
and the user's actual LDAP entry is:
uid=adamson,ou=people,dc=example,dc=com
then the following authz-regexp directive in slapd.conf(5) would provide for direct mapping.
authz-regexp
uid=([^,]*),cn=example.com,cn=gssapi,cn=auth
uid=$1,ou=people,dc=example,dc=com
An even more lenient rule could be written as
authz-regexp
uid=([^,]*),cn=[^,]*,cn=auth
uid=$1,ou=people,dc=example,dc=com
Be careful about setting the search pattern too leniently, however, since it may mistakenly allow persons to become authenticated as a DN to which they should not have access. It is better to write several strict directives than one lenient directive which has 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 authz-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 authz-regexp directive for each case, with the explicit-realm entry being listed first.
15.2.7. Search-based mappings
There are a number of cases where mapping to a LDAP URL may be appropriate. For instance, some sites may have person objects located in multiple areas of the LDAP tree, such as if there were an ou=accounting tree and an ou=engineering tree, with persons interspersed between them. Or, maybe the desired mapping must be based upon information in the user's information. Consider the need to map the above authentication request DN to user whose entry is as follows:
dn: cn=Mark Adamson,ou=People,dc=Example,dc=COM
objectclass: person
cn: Mark Adamson
uid: adamson
The information in the authentication request DN is insufficient to allow the user's DN to be directly derived, instead the user's DN must be searched for. For these situations, a replacement pattern which produces a LDAP URL can be used in the authz-regexp directives. This URL will then be used to perform an internal search of the LDAP database to find the person's authentication DN.
An LDAP URL, similar to other URL's, is of the form
ldap://<host>/<base>?<attrs>?<scope>?<filter>
This contains all of the elements necessary to perform an LDAP 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 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 kept in the attribute "uid" in their LDAP entry. The authz-regexp directive might be written as
authz-regexp
uid=([^,]*),cn=example.com,cn=gssapi,cn=auth
ldap:///ou=people,dc=example,dc=com??one?(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 accepted as being the DN of the user. If there are more than one entries returned, or if there are zero entries returned, the authentication fails and the user's connection is left bound as the authentication request DN.
The attributes that are used in the search filter <filter> in the URL should be indexed to allow faster searching. If they are not, 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 subtree in the directory. These can be handled with statements of the form:
# Match Engineering realm
authz-regexp
uid=([^,]*),cn=engineering.example.com,cn=digest-md5,cn=auth
ldap:///dc=eng,dc=example,dc=com??one?(&(uid=$1)(objectClass=person))
# Match Accounting realm
authz-regexp
uid=([^,].*),cn=accounting.example.com,cn=digest-md5,cn=auth
ldap:///dc=accounting,dc=example,dc=com??one?(&(uid=$1)(objectClass=person))
# Default realm is customers.example.com
authz-regexp
uid=([^,]*),cn=digest-md5,cn=auth
ldap:///dc=customers,dc=example,dc=com??one?(&(uid=$1)(objectClass=person))
Note that the explicitly-named realms are handled first, to avoid the realm name becoming part of the UID. Also note the use of scope and filters to limit matching to desirable entries.
Note as well that authz-regexp internal search are subject to access controls. Specifically, the authentication identity must have auth access.
See slapd.conf(5) for more detailed information.
15.3. 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 user's LDAP connection is switched to have a binding DN derived from the authorization identity, and the LDAP session proceeds with the access of the new authorization DN.
The decision to allow an authorization to proceed depends on the rules and policies of the site where LDAP is running, and thus 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. By default, the authorization features are disabled, and must be explicitly configured by the LDAP administrator before use.
15.3.1. 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 a web page to make changes to their personal information in their LDAP entry. The users authenticate to the web server to establish their identity, but the web server CGI cannot authenticate to the LDAP server as that user to make changes for them. Instead, the web server authenticates itself to the LDAP server as a service identity, say,
cn=WebUpdate,dc=example,dc=com
and then it will SASL authorize to the DN of the user. Once so authorized, the CGI makes changes to the LDAP entry of the user, and as far as the slapd server can tell for its ACLs, it is the user themself on the other end of the connection. The user could have connected to the LDAP server directly and authenticated as themself, but that would require the user to have more knowledge of LDAP clients, knowledge which the web page provides in an easier format.
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 privileged account, possibly through the rootpw slapd.conf(5) directive or through a userPassword attribute, then auditing becomes more difficult.
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.
15.3.2. SASL Authorization Identities
The SASL authorization identity is sent to the LDAP 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
u:<username>
or
dn:<dn>
In the first form, the <username> is from the same namespace as the authentication identities above. It is the user's username as it is referred to by the underlying authentication mechanism. Authorization identities of this form are converted into a DN format by the same function that the authentication process used, producing an authorization request DN of the form
uid=<username>,cn=<realm>,cn=<mechanism>,cn=auth
That authorization request DN is then run through the same authz-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 "dn:" prefix, the string after the prefix is already in authorization DN form, ready to undergo approval.
15.3.3. Proxy Authorization Rules
Once slapd has the authorization DN, the actual approval process begins. There are two attributes that the LDAP administrator can put into LDAP entries to allow authorization:
authzTo
authzFrom
Both can be multivalued. The authzTo 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 authzTo rules specify the authorization is permitted, the authzFrom 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 behavior 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 authz-regexp directive: either a DN or an LDAP URL. For example, if a authzTo value is a DN, that DN is one the authenticated user can authorize to. On the other hand, if the authzTo 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
authzTo: 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 dc=example,dc=com which has an objectClass of Person.
15.3.3.1. Notes on Proxy Authorization Rules
An LDAP URL in a authzTo or authzFrom attribute will return a set of DNs. Each DN returned will be checked. Searches which return a large set can cause the authorization process to take an uncomfortably long time. Also, searches should be performed on attributes that have been indexed by slapd.
To help produce more sweeping rules for authzFrom and authzTo, the values of these attributes are allowed to be DNs with regular expression characters in them. This means a source rule like
authzTo: dn.regex:^uid=[^,]*,dc=example,dc=com$
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=*).
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 permissible to enter another authorization identity of the form "u:<username>" as an authorization rule.
15.3.3.2. Policy Configuration
The decision of which type of rules to use, authzFrom or authzTo, 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 authz-policy directive must be set in the slapd.conf(5) file to enable authorization. This directive can be set to none for no rules (the default), to for source rules, from for destination rules, or both for both source and destination rules.
Source rules are extremely powerful. If ordinary users have access to write the authzTo attribute in their own entries, then they can write rules that would allow them to authorize as anyone else. As such, when using source rules, the authzTo attribute should be protected with an ACL that only allows privileged users to set its values.