Options for Cyrus SASL

This document contains information on what options are used by the Cyrus SASL library and bundled mechanisms. The most commonly used options (and those that are therefore most commonly misunderstood are pwcheck_method and auxprop_plugin. Please ensure that you have configured these correctly if things don't seem to be working right. Additionally, mech_list can be an easy way to limit what mechanisms a given application will use.

Notes on SQL auxprop options

The sql_insert and sql_update options are optional and are only needed if you wish to allow the SASL library (e.g., saslpasswd2) and plugins (e.g., OTP) to write properties to the SQL server. If used, both statements MUST be provided so that properties can be added, changed and deleted. NOTE: The columns for writable properites MUST accept NULL values.

The SQL statements provided in the sql_select, sql_insert and sql_update options can contain arguments which will be substituted with the appropriate values. The valid arguments are:

%u

Username whose properties are being fetched/stored.

%p

Name of the property being fetched/stored. This could technically be anything, but SASL authentication will try userPassword and cmusaslsecretMECHNAME (where MECHNAME is the name of a SASL mechanism).

%r

Realm to which the user belongs. This could be the kerberos realm, the FQDN of the computer the SASL application is running on or whatever is after the @ on a username. (read the realm documentation).

%v

Value of the property being stored (INSERT or UPDATE only!). This could technically be anything depending on the property itself, but is generally a userPassword.

Examples:

     sql_select: SELECT %p FROM user_table WHERE username = '%u' and realm = '%r'

     SELECT userPassword FROM user_table WHERE username = 'bovik' and
     realm = 'madoka.surf.org.uk';

     sql_insert: INSERT INTO user_table (username, realm, %p) VALUES ('%u', '%r', '%v')

     INSERT INTO user_table (username, realm, userPassword) VALUES
     ('bovik', 'madoka.surf.org.uk', 'wert');

Note that all substitutions do not have to be used. For instance,

     SELECT password FROM auth WHERE username = '%u'

Notes on LDAPDB plugin options

Unlike other LDAP-enabled plugins for other services that are common on the web, this plugin does not require you to configure DN search patterns to map usernames to LDAP DNs. This plugin requires SASL name mapping to be configured on the target slapd. This approach keeps the LDAP-specific configuration details in one place, the slapd.conf, and makes the configuration of remote services much simpler.

This plugin is not for use with slapd itself. When OpenLDAP is built with SASL support, slapd uses its own internal auxprop and canonuser module. By default, without configuring anything else, slapd will fail to load the ldapdb module when it's present. This is as it should be. If you don't like the "auxpropfunc: error -7" message that is sent to syslog by slapd, you can stop it by creating /usr/lib/sasl2/slapd.conf with:

auxprop_plugin: slapd

Examples:

ldapdb_uri: ldap://ldap.example.com
ldapdb_id: root
ldapdb_pw: secret
ldapdb_mech: DIGEST-MD5
ldapdb_canon_attr: uid

The LDAP server must be configured to map the SASL authcId "root" into a DN that has proxy authorization privileges to every account that is allowed to login to this server. (See the OpenLDAP Admin Guide section 10 for details.)

ldapdb_uri: ldapi://
ldapdb_mech: EXTERNAL

This configuration assumes an LDAP server is on the same server that is using SASL and the underlying OS is *NIX based (ldapi:// requires UNIX domain sockets). This is fast and secure, and needs no username or password to be stored. The slapd.conf will need to map these usernames to LDAP DNs:

sasl-regexp uidNumber=(.*)\\+gidNumber=(.*),cn=peercred,cn=external,cn=auth
    ldap:///dc=example,dc=com??sub?(&(uidNumber=$1)(gidNumber=$2))

sasl-regexp uid=(.*),cn=external,cn=auth
    ldap:///dc=example,dc=com??sub?(uid=$1)

Notes on sasldb with LMDB

The OpenLDAP LMDB library is an extremely compact, extremely high performance B+tree database. The code for it is available in the regular OpenLDAP source distributions and it is distributed under the terms of the OpenLDAP Public License.

Full documentation, plus papers and presentations are available on the LMDB page.