| Current Path : /usr/share/doc/cyrus-sasl-2.1.23/ |
| Current File : //usr/share/doc/cyrus-sasl-2.1.23/LDAP_SASLAUTHD |
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.1 or
higher. Fetch the latest cyrus-sasl package, 2.1.17 or higher,
ftp://ftp.andrew.cmu.edu/pub/cyrus-mail/.
Unpack cyrus-sasl:
gzip -dc cyrus-sasl-2.1.17.tar.gz | tar xf -
or
tar zxf cyrus-sasl-2.1.17.tar.gz (if your tar supportz gzip)
cd cyrus-sasl-2.1.17
./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_password: secret
Do not specify ldap_bind_*/ldap_password 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 command line options, 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, turn debug level for the auth syslog
facility and check the syslog file. 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_auth_method: <bind|fastbind> <bind|custom|fastbind>
Specify an authentication method.
The bind method uses the LDAP bind facility to verify the password. The
bind method is not available when ldap_use_sasl is turned on. In that case
saslauthd will use fastbind.
'bind' is the default auth method. When ldap_use_sasl is enabled,
'fastbind' 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 (when 'ldap_use_sasl: no') does away with the search
and an extra anonymous bind in auth_bind, but makes two assumptions:
1. Expanding the ldap_filter expression gives the user's fully-qualified DN
2. There is no cost to staying bound as a named user
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>
Alias for ldap_password.
ldap_default_domain: <none>
Alias for ldap_default_realm.
ldap_default_realm: <none>
The default realm is assigned to the %r token when realm is not
available. See ldap_filter for more.
ldap_deref: <none> <search|find|always|never>
Specify how aliases dereferencing is handled during search.
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 if available (%d = domain.tld when %u =
%test@domain.tld), otherwise same as %r
%1-9 = domain tokens (%1 = tld, %2 = domain when %d = domain.tld)
%s = service
%r = realm
%D = user DN (available for group checks)
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_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. If
ldap_group_match_method is not attr, this parameter is ignored.
ldap_group_dn: <none>
If specified, the user has to be part of the group in order to authenticate
successfully. Tokens described in 'ldap_filter' (see above) can be used
for substitution.
ldap_group_filter: <none>
Specify a filter. If a filter match is found then the user is in the group.
Tokens described in 'ldap_filter' (see above) can be used for for
substitution. If ldap_group_dn is not specified, this parameter is ignored.
If ldap_group_match_method is not filter, this parameter is ignored.
ldap_group_match_method: <attr> <attr|filter>
Specify whether the group match method uses ldap_group_attr or
ldap_group_search. If ldap_group_dn is not specified, this parameter is
ignored.
ldap_group_search_base: <if not specified, it defaults to ldap_search_base>
Specify a starting point for the group search: e.g. dc=foo,dc=com. Tokens
described in 'ldap_filter' (see below) can be used for substitution.
ldap_group_scope: <sub> <sub|one|base>
Group search scope.
ldap_password: <none>
Specify the password for ldap_bind_dn or ldap_id if
ldap_use_sasl is turned on. Do not specify this parameter for the
anonymous bind.
ldap_password_attr: <userPassword>
Specify what password attribute to use for password verification.
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_id: <none>
Specify the authentication ID for SASL bind.
ldap_authz_id: <none>
Specify the proxy authorization ID for SASL bind.
ldap_mech: <none>
Specify the authentication mechanism for SASL bind.
ldap_realm: <none>
Specify the realm of authentication ID for SASL bind.
ldap_scope: <sub> <sub|one|base>
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_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_start_tls: <no>
Use StartTLS extended operation. Do not use ldaps: ldap_servers when
this option is turned on.
ldap_time_limit: <5>
Specify a number of seconds for a search request to complete.
ldap_timeout: <5>
Specify a number of seconds a search can take before timing out.
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.
ldap_use_sasl: <no>
Use SASL bind rather than simple bind when connecting to the ldap
server.
ldap_version: <3> <2|3>
Specify the LDAP protocol version. If ldap_start_tls and/or
ldap_use_sasl are enabled, ldap_version will be automatiacally set to
3.
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.
SASL bind should be used with the 'fastbind' auth_method:
ldap_servers: ldaps://10.1.1.2/
ldap_use_sasl: yes
ldap_mech: DIGEST_MD5
ldap_auth_method: fastbind
At this time this is not the best performing solution because openldap (2.1.x)
cannot reuse existing connection for multiple ldap_sasl_bind()s. This will
hopefully change when openldap 2.2 comes out.
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>.
Copyright 2K16 - 2K18 Indonesian Hacker Rulez
;?>)