auth_ldap module for saslauthd ------------------------------ Saslauthd can use an LDAP directory for authentication/authorization. Sections: 1. Build saslauthd with ldap support 2. Start saslauthd with ldap 3. Testing 4. Parameters 5. Examples 6. Notes 7. Todo 8. Feedback 8. Author 1. BUILD SASLAUTHD WITH LDAP SUPPORT ------------------------------------ Ensure that you have the OpenLDAP (http://www.openldap.org) libraries 2.0 or higher. Fetch the latest cyrus-sasl package, 2.1.6 or higher, ftp://ftp.andrew.cmu.edu/pub/cyrus-mail/. Unpack cyrus-sasl: gzip -dc cyrus-sasl-2.1.6.tar.gz | tar xf - or tar zxf cyrus-sasl-2.1.6.tar.gz (if your tar supportz gzip) cd cyrus-sasl-2.1.6 ./configure --with-ldap (you may need to add other options, check doc/index.html for more) make make install 2. START SASLAUTHD WITH LDAP ---------------------------- Create /usr/local/etc/saslauthd.conf and add the following (modify to fit your environment): ldap_servers: ldap://10.1.1.15/ ldap://10.1.1.25/ ldap_bind_dn: cn=operator,ou=Profile,o=foo.com ldap_bind_pw: secret Do not specify ldap_bind_* if you want to bind anonymously to your ldap server(s). Run saslauthd: saslauthd -a ldap If you want to specify a different configuration file, you can do something like: saslauthd -a ldap -O /etc/saslauthd.conf For more, check 'man saslauthd' 3. TESTING ---------- First build testsaslauthd: cd $sasl_src/saslauthd make testsaslauthd Run test utility: ./testsaslauthd -u igor -p secret 0: OK "Success." If you get output other then Success, check the auth.* syslog facility. Hopefully this will give you enough information to make adjustements in the startup and/or configuration files. 4. PARAMETERS ------------- The following are available ldap parameters. There are quite a few of those, but only ldap_servers may need to be specified. The defaults for all other parameters are adequate for most installations. Do not use quotes (\"\') in the parameter values. The defaults are specified within the first set of <>. There may be a second set of <> which provide available values. ldap_servers: Specify URI(s) refering to LDAP server(s), e.g. ldaps://10.1.1.2:999/. You can specify multiple servers separated by a space. ldap_bind_dn: Specify DN (distinguished name) to bind to the LDAP directory. Do not specify this parameter for the anonymous bind. ldap_bind_pw: Specify the password for ldap_bind_dn. Do not specify this parameter for the anonymous bind. ldap_version: <3> <2|3> Specify the LDAP protocol version to use. ldap_timeout: <5> Specify a number of seconds a search can take before timing out. ldap_time_limit: <5> Specify a number of seconds for a search request to complete. ldap_deref: Specify how aliases dereferencing is handled during a search. ldap_referrals: Specify whether or not the client should follow referrals. ldap_restart: Specify whether or not LDAP I/O operations are automatically restarted if they abort prematurely. ldap_cache_ttl: <0> Non zero enables client side caching. Cached results will expire after specified number seconds, e.g. 30. Use this option with care. OpenLDAP folks consider this feature experimental. ldap_cache_mem: <0> If client side caching is enabled, the value specifies the cache size in bytes, e.g. 32768. ldap_scope: Search scope. ldap_search_base: Specify a starting point for the search. e.g. dc=foo,dc=com ldap_auth_method: Specify an authentication method. The bind method uses the LDAP simple bind facility to verify the password. This is the default. The custom method uses userPassword attribute to verify the password. Currently, {CRYPT} hash is supported. The fastbind method does away with the search and extra anonymous bind in auth_bind, but makes two assumptions: 1. Expanding the ldap_filter expression gives the fully-qualified DN 2. There is no cost to staying bound as a named user ldap_filter: Specify a filter. Use the %u and %r tokens for the username and realm substitution. The %u token has to be used at minimum for the filter to be useful. If ldap_auth_method is 'bind', the filter will search for the DN (distinguished name) attribute. Otherwise, the search will look for the userPassword attribute. ldap_debug: <0> Specify a debugging level in the OpenLDAP libraries. See ldap_set_option(3) for more (LDAP_OPT_DEBUG_LEVEL). ldap_tls_check_peer: Require and verify server certificate. If this option is yes, you must specify ldap_tls_cacert_file or ldap_tls_cacert_dir. ldap_tls_cacert_file: File containing CA (Certificate Authority) certificate(s). ldap_tls_cacert_dir: Path to directory with CA (Certificate Authority) certificates. ldap_tls_ciphers: List of SSL/TLS ciphers to allow. The format of the string is described in ciphers(1). ldap_tls_cert: File containing the client certificate. ldap_tls_key: File containing the private client key. 5. NOTES -------- For better performance ensure that the attributes specified in ldap_filter are indexed. You can also experiment with client side caching. This can be a significant performance gain. Use client side caching with caution because it is still an experimental OpenLDAP call. The following configuration setting enables client side caching and it sets the cache size to 32k: ldap_cache_ttl: 30 ldap_cache_mem: 32768 My testing shows that 'custom' is 2-3 times faster than 'bind' ldap_auth_method. This is caused because of two extra binds performed during the 'bind' authentication method. On the other hand, the 'bind' authentication method is more secure because ldap_bind_pw is not exposed. 6. TODO ------- - Port to other ldap libraries - There may be bind problems when following referrals. Normally this is not an issue. Fix. - Allow to specify an attribute other than userPassword for use in the custom authentication method. - Add more password hashes such as md5, sha etc - Make a suggestion (possibly another authentication method?) 7. FEEDBACK ----------- Feedback is much appreciated! Please drop me a note if you are successfully using ldap-enabled saslauthd. Any code improvements and/or suggestion are welcome. If you have questions, send email to cyrus-sasl@lists.andrew.cmu.edu. Please include relevant information about your saslauthd setup: at minimum provide your saslauth.conf, output from syslog and which directory server you're using. 8. AUTHOR --------- Igor Brezac .