Documentação Cyrus-sasl

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.12 or higher,
ftp://ftp.andrew.cmu.edu/pub/cyrus-mail/.

Unpack cyrus-sasl:
gzip -dc cyrus-sasl-2.1.12.tar.gz | tar xf -
or
tar zxf cyrus-sasl-2.1.12.tar.gz (if your tar supportz gzip)

cd cyrus-sasl-2.1.12
./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: <ldap://localhost/>
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: <none>

Specify DN (distinguished name) to bind to the LDAP directory.  Do not
specify this parameter for the anonymous bind.

ldap_bind_pw: <none>
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: <none> <search|find|always|never>
Specify how aliases dereferencing is handled during a search.

ldap_referrals: <no>
Specify whether or not the client should follow referrals.

ldap_restart: <yes>
Specify whether or not LDAP I/O operations are automatically restarted
if they abort prematurely.

ldap_scope:

Search scope.

ldap_search_base: <none>
Specify a starting point for the search: e.g. dc=foo,dc=com.  Tokens
described in 'ldap_filter' (see below) can be used for substitution.

ldap_auth_method: <bind> <bind|custom|fastbind>
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.
Suppored hashes: crypt, md5, smd5, sha and ssha.  Cleartext is supported
as well.

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: <uid=%u>
Specify a filter.  The following tokens can be used in the filter string:

%%   = %
%u   = user
%U   = user portion of %u (%U = test when %u = test@domain.tld)
%d   = domain portion of %u (%d = domain.tld when %u = test@domain.tld)
%1-9 = domain tokens (%1 = tld, %2 = domain when %d = domain.tld)
%s   = service
%r   = realm

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 'ldap_password_attr' (see below) attribute.

ldap_group_dn: <none>

Specify a group DN. If specified, the user DN has to be part of the
group in order to authenticate successfully.  Tokens described in
'ldap_filter' (see above) can be used for substitution.  The user DN is
compared against the 'ldap_group_attr' (see below) attribute of the
group.

ldap_group_attr: <uniqueMember>
Specify what attribute to compare the user DN against in the group. If
ldap_group_dn is not specified, this parameter is ignored.

ldap_password_attr: <userPassword>
   Specify what password attribute to use for password verification.

ldap_tls_check_peer: <no> <yes|no>
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: <none>

File containing CA (Certificate Authority) certificate(s).

ldap_tls_cacert_dir: <none>
Path to directory with CA (Certificate Authority) certificates.

ldap_tls_ciphers: <DEFAULT>
List of SSL/TLS ciphers to allow.  The format of the string is
described in ciphers(1).

ldap_tls_cert: <none>
File containing the client certificate.

ldap_tls_key: <none>
File containing the private client key.


5. NOTES
--------

For better performance ensure that the attributes specified in ldap_filter are
indexed.

My testing shows that 'custom' is 2-3 times faster than 'bind'
ldap_auth_method.  The 'fastbind' auth_method is just as fast or faster.  The
slower performace of the 'bind' auth_method is caused by two extra calls to
ldap_bind() per each authentication.

6. TODO
-------

- Port to other ldap libraries
- There may be bind problems when following referrals.  Normally this is not an
issue.
- Allow to specify an attribute other than userPassword for use in the custom
authentication method. (Done)
- Add more password hashes such as md5, sha etc (Done)
- Make a suggestion (possibly another authentication method?) (added fastbind)
thanks to Simon Brady <simon.brady@otago.ac.nz>


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 <igor@ipass.net>.

Retirada daqui.