1 auth_ldap module for saslauthd
2 ------------------------------
4 Saslauthd can use an LDAP directory for authentication/authorization.
7 1. Build saslauthd with ldap support
8 2. Start saslauthd with ldap
18 1. BUILD SASLAUTHD WITH LDAP SUPPORT
19 ------------------------------------
21 Ensure that you have the OpenLDAP (http://www.openldap.org) libraries 2.1 or
22 higher. Fetch the latest cyrus-sasl package, 2.1.17 or higher,
23 ftp://ftp.andrew.cmu.edu/pub/cyrus-mail/.
26 gzip -dc cyrus-sasl-2.1.17.tar.gz | tar xf -
28 tar zxf cyrus-sasl-2.1.17.tar.gz (if your tar supportz gzip)
31 ./configure --with-ldap (you may need to add other options, check doc/index.html for more)
36 2. START SASLAUTHD WITH LDAP
37 ----------------------------
39 Create /usr/local/etc/saslauthd.conf and add the following (modify to fit your
41 ldap_servers: ldap://10.1.1.15/ ldap://10.1.1.25/
42 ldap_bind_dn: cn=operator,ou=Profile,o=foo.com
45 Do not specify ldap_bind_*/ldap_password if you want to bind anonymously to
51 If you want to specify a different configuration file, you can do something
53 saslauthd -a ldap -O /etc/saslauthd.conf
55 For more command line options, check 'man saslauthd'
61 First build testsaslauthd:
62 cd $sasl_src/saslauthd
66 ./testsaslauthd -u igor -p secret
69 If you get output other then Success, turn debug level for the auth syslog
70 facility and check the syslog file. Hopefully this will give you enough
71 information to make adjustements in the startup and/or configuration files.
77 The following are available ldap parameters. There are quite a few of those,
78 but only ldap_servers may need to be specified. The defaults for all other
79 parameters are adequate for most installations.
81 Do not use quotes (\"\') in the parameter values. The defaults are specified
82 within the first set of <>. There may be a second set of <> which provide
85 ldap_auth_method: <bind|fastbind> <bind|custom|fastbind>
86 Specify an authentication method.
88 The bind method uses the LDAP bind facility to verify the password. The
89 bind method is not available when ldap_use_sasl is turned on. In that case
90 saslauthd will use fastbind.
92 'bind' is the default auth method. When ldap_use_sasl is enabled,
93 'fastbind' is the default.
95 The custom method uses userPassword attribute to verify the password.
96 Suppored hashes: crypt, md5, smd5, sha and ssha. Cleartext is supported as
99 The fastbind method (when 'ldap_use_sasl: no') does away with the search
100 and an extra anonymous bind in auth_bind, but makes two assumptions:
101 1. Expanding the ldap_filter expression gives the user's fully-qualified DN
102 2. There is no cost to staying bound as a named user
105 Specify DN (distinguished name) to bind to the LDAP directory. Do not
106 specify this parameter for the anonymous bind.
109 Alias for ldap_password.
111 ldap_default_domain: <none>
112 Alias for ldap_default_realm.
114 ldap_default_realm: <none>
115 The default realm is assigned to the %r token when realm is not
116 available. See ldap_filter for more.
118 ldap_deref: <none> <search|find|always|never>
119 Specify how aliases dereferencing is handled during search.
121 ldap_filter: <uid=%u>
122 Specify a filter. The following tokens can be used in the filter string:
126 %U = user portion of %u (%U = test when %u = test@domain.tld)
127 %d = domain portion of %u if available (%d = domain.tld when %u =
128 %test@domain.tld), otherwise same as %r
129 %1-9 = domain tokens (%1 = tld, %2 = domain when %d = domain.tld)
132 %D = user DN (available for group checks)
134 The %u token has to be used at minimum for the filter to be useful. If
135 ldap_auth_method is 'bind', the filter will search for the DN
136 (distinguished name) attribute. Otherwise, the search will look for
137 the 'ldap_password_attr' (see below) attribute.
139 ldap_group_attr: <uniqueMember>
140 Specify what attribute to compare the user DN against in the group. If
141 ldap_group_dn is not specified, this parameter is ignored. If
142 ldap_group_match_method is not attr, this parameter is ignored.
144 ldap_group_dn: <none>
145 If specified, the user has to be part of the group in order to authenticate
146 successfully. Tokens described in 'ldap_filter' (see above) can be used
149 ldap_group_filter: <none>
150 Specify a filter. If a filter match is found then the user is in the group.
151 Tokens described in 'ldap_filter' (see above) can be used for for
152 substitution. If ldap_group_dn is not specified, this parameter is ignored.
153 If ldap_group_match_method is not filter, this parameter is ignored.
155 ldap_group_match_method: <attr> <attr|filter>
156 Specify whether the group match method uses ldap_group_attr or
157 ldap_group_search. If ldap_group_dn is not specified, this parameter is
160 ldap_group_search_base: <if not specified, it defaults to ldap_search_base>
161 Specify a starting point for the group search: e.g. dc=foo,dc=com. Tokens
162 described in 'ldap_filter' (see below) can be used for substitution.
164 ldap_group_scope: <sub> <sub|one|base>
167 ldap_password: <none>
168 Specify the password for ldap_bind_dn or ldap_id if
169 ldap_use_sasl is turned on. Do not specify this parameter for the
172 ldap_password_attr: <userPassword>
173 Specify what password attribute to use for password verification.
176 Specify whether or not the client should follow referrals.
179 Specify whether or not LDAP I/O operations are automatically restarted
180 if they abort prematurely.
183 Specify the authentication ID for SASL bind.
185 ldap_authz_id: <none>
186 Specify the proxy authorization ID for SASL bind.
189 Specify the authentication mechanism for SASL bind.
192 Specify the realm of authentication ID for SASL bind.
194 ldap_scope: <sub> <sub|one|base>
197 ldap_search_base: <none>
198 Specify a starting point for the search: e.g. dc=foo,dc=com. Tokens
199 described in 'ldap_filter' (see below) can be used for substitution.
201 ldap_servers: <ldap://localhost/>
202 Specify URI(s) refering to LDAP server(s), e.g. ldaps://10.1.1.2:999/.
203 You can specify multiple servers separated by a space.
206 Use StartTLS extended operation. Do not use ldaps: ldap_servers when
207 this option is turned on.
210 Specify a number of seconds for a search request to complete.
213 Specify a number of seconds a search can take before timing out.
215 ldap_tls_check_peer: <no> <yes|no>
216 Require and verify server certificate. If this option is yes,
217 you must specify ldap_tls_cacert_file or ldap_tls_cacert_dir.
219 ldap_tls_cacert_file: <none>
220 File containing CA (Certificate Authority) certificate(s).
222 ldap_tls_cacert_dir: <none>
223 Path to directory with CA (Certificate Authority) certificates.
225 ldap_tls_ciphers: <DEFAULT>
226 List of SSL/TLS ciphers to allow. The format of the string is
227 described in ciphers(1).
229 ldap_tls_cert: <none>
230 File containing the client certificate.
233 File containing the private client key.
236 Use SASL bind rather than simple bind when connecting to the ldap
239 ldap_version: <3> <2|3>
240 Specify the LDAP protocol version. If ldap_start_tls and/or
241 ldap_use_sasl are enabled, ldap_version will be automatiacally set to
247 For better performance ensure that the attributes specified in ldap_filter are
250 My testing shows that 'custom' is 2-3 times faster than 'bind'
251 ldap_auth_method. The 'fastbind' auth_method is just as fast or faster. The
252 slower performace of the 'bind' auth_method is caused by two extra calls to
253 ldap_bind() per each authentication.
255 SASL bind should be used with the 'fastbind' auth_method:
257 ldap_servers: ldaps://10.1.1.2/
259 ldap_mech: DIGEST_MD5
260 ldap_auth_method: fastbind
262 At this time this is not the best performing solution because openldap (2.1.x)
263 cannot reuse existing connection for multiple ldap_sasl_bind()s. This will
264 hopefully change when openldap 2.2 comes out.
269 - Port to other ldap libraries
270 - There may be bind problems when following referrals. Normally this is not an
272 - Allow to specify an attribute other than userPassword for use in the custom
273 authentication method. (Done)
274 - Add more password hashes such as md5, sha etc (Done)
275 - Make a suggestion (possibly another authentication method?) (added fastbind)
276 thanks to Simon Brady <simon.brady@otago.ac.nz>
282 Feedback is much appreciated! Please drop me a note if you are successfully
283 using ldap-enabled saslauthd. Any code improvements and/or suggestion are welcome.
285 If you have questions, send email to cyrus-sasl@lists.andrew.cmu.edu. Please
286 include relevant information about your saslauthd setup: at minimum provide
287 your saslauth.conf, output from syslog and which directory server you're using.
293 Igor Brezac <igor@ipass.net>.