summaryrefslogtreecommitdiffabout
path: root/saslauthd/LDAP_SASLAUTHD
blob: 86f24e5e35d059cdc293625c1a4d3eed2c8dbfdf (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
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>.