Checkpassword LDAP

Chkpassldap is a Perl checkpassword implementation suitable for qmail-ldap and Dovecot proxying clusters and beyond.

Download chkpassldap

NAME

chkpassldap.pl

SYNOPSIS

Qmail run script:

/var/qmail/bin/qmail-smtpd /var/qmail/bin/chkpassldap.pl /bin/true 2>&1

Dovecot passdb checkpassword configuration:

args = /opt/bin/chkpassldap.pl

DESCRIPTION

Chkpassldap is a Perl implementation of D. J. Bernstein's checkpassword interface that authenticates and authorizes against LDAP. It is suited for SMTP-Auth via qmail, and any other applications that supports the standard checkpassword interface. Beyond simple auth, it is also capable of setting environment variables if required. This flexibility allows the interface to scale to other applications as well, such as the Dovecot POP/IMAP server.

INSTALLATION

Script requirements are as follows:

 IO::Handle
 Net::LDAP (from perl-ldap)
 Net::DNS (optional for enabling nslookups)

Installation consists of copying the script to the filesystem, for example in /opt/bin. The script then must be configured, and applications setup to make use of it.

CONFIGURATION

Configuration is done in-script, changing variables at the top of the script. Most are self-explanatory, but all are described here.

logging

Eenable or disable (1|0) logging to STDERR. Default: '1'

debug

Increase the amount of debugging information to the log. Default: '0'

ldap_server

LDAP server IP address or name. TCP port can optionally be specified with trailing colon such as ldap.example.com:389. This must be set to suit your environment. Default: nothing useful

ldap_base people_base group_base

LDAP root search base and the people and group search bases. The search base must be set to suit your environment. The people and group bases are pretty typical but may need to be adjusted to suit your environment. Default: nothing useful

search_scope

LDAP search scope. This determines how searches are conducted, with possible values sub, one, and base. The value sub will suffice for most sites. Default: 'sub'

group

LDAP group authorization. This is the cn of a group of which the user must be a memberuid. If not specified, no group restriction. Default: ''

attribute

LDAP attribute authorization. This is an attribute/value pairing which the user must possess, for example accountStatus=active. If not specified, no attribute restriction. Default: ''

envset

Enable or disable (1|0) environment variable setting. Default: '0'

envmap

Configure how the environment is set. No effect if envset=0. See section ENVIRONMENT MODIFICATION.

INTEGRATION

Configurations for common applications which have been heavily tested with this script.

Qmail

Qmail is almost always run out of daemontools run scripts. Assuming roughly a life with qmail install running on port 25 (hopefully with STARTTLS required):

 exec /usr/local/bin/softlimit -m 24000000
        /usr/local/bin/tcpserver -v -R -l "$LOCAL" -x /etc/tcp.smtp.cdb
                -c "$MAXSMTPD" -u "$QMAILDUID" -g "$NOFILESGID" 0 smtp
                /var/qmail/bin/qmail-smtpd
                /opt/bin/chkpassldap.pl /bin/true 2>&1

Note: This should be all one line or lines ending with ' \'

Qmail and Stunnel

The following daemontools run script sets up qmail using stunnel to provide SSL on the official dedicated SSL port 465:

 exec /usr/local/bin/softlimit -m 24000000
        /usr/local/bin/tcpserver -v -R -l "$LOCAL" -x /etc/tcp.smtps.cdb
                -c "$MAXSMTPD" -u "$QMAILDUID" -g "$NOFILESGID" 0 smtps
                /usr/sbin/stunnel /etc/stunnel/smtp.conf 2>&1

Note: This should be all one line or lines ending with ' \'

And the following stunnel smtp.conf configuration:

 cert = /etc/stunnel/smtp.pem
 exec = /var/qmail/bin/qmail-smtpd
 execargs = qmail-smtpd smtp.example.com /opt/bin/chkpassldap.pl /bin/true
 foreground = yes

Dovecot

Dovecot can make us of the checkpassword interface for both passdb and prefetch userdb lookups. In dovecont.conf:

 userdb prefetch {
 }
 
 passdb checkpassword {
        args = /opt/bin/chkpassldap.pl
 }

The prefetch userdb avoids unnecessary LDAP lookups, but will only work with extensive use of chkpassldap's environment modification capabilities. See section ENVIRONMENT MODIFICATION.

ENVIRONMENT MODIFICATION

Some applications have needs beyond simple authentication and authorization, such as modifying the environment. The envmap hash at the top of the script controls this behavior. Each key is an environment variable name that points to a hash of options that controls how it is set. Options are described here.

ldap

Names the LDAP attribute whose value will be looked up to fill the environment variable.

extra

Flags the variable for inclusion in a special environment variable named EXTRA. This is higly specific to Dovecot.

optional

Flags the variable as optional so the environment variable will not be set at all if no value can be found.

nslookup

Flags the variable for address resolution. This is included for the strange reason that in qmail-ldap it is typical to store the mailHost ldap attribute as a hostname, but Dovecot proxying can only make use of ip addresses. Therefore, we resolve it on behalf of Dovecot.

depends

Names a dependency for the variable, so it will only be set if the dependency is set. This is included because Dovecot does not like to see proxying enabled when there is no host set.

value

When lookups are actually done, values are stored in this hash element. If a value is set ahead of time, it is effectively hardcoded and no lookup is done. This is a handy shortcut to specify a global setting for all users.

It may be obvious that much of the capability for environment modification grew up around tailoring the environment for Dovecot using qmail-ldap ldap attributes. It may be beneficial to describe the default hash in full to better show what is happening.

 my %envmap = (
        'HOME' =>               { ldap=>'homeDirectory' },
        'USER' =>               { ldap=>'uid' },
        'userdb_uid' =>         { ldap=>'uidNumber', extra=>1 },
        'userdb_gid' =>         { ldap=>'gidNumber', extra=>1 },
        'host' =>               { ldap=>'mailHost', extra=>1, optional=>1, nslookup=>1 },
        'proxy_maybe' =>        { value=>1, extra=>1, depends=>'host' },
 );

When envset is enabled, the environment variables HOME, USER, userdb_uid, userdb_gid, and host are all set to the corresponding ldap attribute values returned for the user. The host variable is flagged for nslookup. It is also flagged as optional, so that if mailHost cannot be looked up or does not exist, the host environment variable is not set at all. If such is the case, proxy_maybe will not be set since it is flagged as depends on host, otherwise it is hardcoded to value 1. Finally, all those flagged with extra are stored by name, space-separated, in a special EXTRA environment variable.

A full reading of the Dovecot authentication documentation is required to understand the ramifications of the above. This specific setup is geared towards setting the environment for a qmail-ldap and Dovecot proxying cluster, but should scale well to other needs. Enable logging and debug and watch the logs. Suffice it to say, it does actually work.

CHANGES

chkpassldap 1.00 (20120526)

- Initial release.

RESOURCES

http://cr.yp.to/checkpwd.html

http://wiki.dovecot.org

http://www.apecity.com/qmail/ldap_auth.html