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
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
|
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
<head>
<title>mod_authn_sasl - Apache HTTP Server Authentication Module</title>
<link href="css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
<link href="css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
<link href="css/manual-print.css" rel="stylesheet" media="print" type="text/css" />
<link href="images/favicon.ico" rel="shortcut icon" />
</head>
<body>
<div id="page-header">
<p class="menu">
<a href="http://sourceforge.net/projects/mod-authn-sasl/">Project Page</a> |
<a href="http://sourceforge.net/project/showfiles.php?group_id=185449">Downloads</a> |
<a href="http://httpd.apache.org/docs/2.2/">Apache HTTPD</a> |
<a href="http://asg.web.cmu.edu/sasl/sasl-library.html">Cyrus SASL</a> |
<a href="http://sourceforge.net">Sourceforge.net</a>
</p>
<p class="apache">Apache HTTP Server Version 2.2</p>
<img alt="Apache HTTPD logo feather" src="images/feather.png" />
</div>
<div id="path">
<a href="http://www.apache.org/">Apache</a> >
<a href="http://httpd.apache.org/">HTTP Server</a> >
<a href="http://httpd.apache.org/docs/">Documentation</a> >
<a href="http://httpd.apache.org/docs/2.2/">Version 2.2</a> >
<a href="http://httpd.apache.org/docs/2.2/mod/">Modules</a>
</div>
<div id="page-content">
<div id="preamble">
<h1>Apache Module mod_authn_sasl Version 1.2</h1>
<div class="toplang">
<p>
<span>Available Languages: </span>
<a href="index.html" title="English"> en </a>
</p>
</div>
<table class="module"><tr>
<th><a href="http://httpd.apache.org/docs/2.2/mod/module-dict.html#Description">Description:</a></th>
<td>User authentication using Cyrus libsasl2 password verification service</td>
</tr><tr>
<th><a href="http://httpd.apache.org/docs/2.2/mod/module-dict.html#Status">Status:</a></th>
<td>External</td>
</tr><tr>
<th><a href="http://httpd.apache.org/docs/2.2/mod/module-dict.html#ModuleIdentifier">Module Identifier:</a></th>
<td>authn_sasl_module</td>
</tr><tr>
<th><a href="http://httpd.apache.org/docs/2.2/mod/module-dict.html#SourceFile">Source File:</a></th>
<td>mod_authn_sasl.c</td>
</tr><tr>
<th><a href="http://httpd.apache.org/docs/2.2/mod/module-dict.html#Compatibility">Compatibility:</a></th>
<td>Available in Apache 2.2 and later</td>
</tr></table>
<h3>Summary</h3>
<p>
This module provides the <code class="module"><a href="http://httpd.apache.org/docs/2.2/mod/mod_auth_basic.html">mod_auth_basic</a></code> authentication front-end a way to authenticate users by checking credentials via the <a href="http://asg.web.cmu.edu/sasl/sasl-library.html">Cyrus SASL library</a>. This may be interesting for setups where other daemons (e.g. for SMTP, IMAP or LDAP) already running at a machine use SASL to authenticate users. The module is also useful to authenticate users against databases that use shadow passwords. You do not need to elevate Apache HTTPD's access rights to superuser privileges. See <code class="directive"><a href="#authsaslpwcheckmethod">AuthSaslPwcheckMethod</a></code> for more information about this topic.
</p>
<div class="note">
Note that on many systems access to the SASL database and <code>saslauthd</code> communication socket is restricted. You might have to add Apache HTTPD to the a certain system group (like <var>sasl</var> or similar) in order to be able to use the password verification services provided by the Cyrus SASL library.
</div>
<p>
When using <code class="module"><a href="http://httpd.apache.org/docs/2.2/mod/mod_auth_basic.html">mod_auth_basic</a></code> this module is invoked with the directive <code class="directive"><a href="http://httpd.apache.org/docs/2.2/mod/mod_auth_basic.html#authbasicprovider">AuthBasicProvider</a></code> and a value of <code>sasl</code>. Using it with <code class="module"><a href="http://httpd.apache.org/docs/2.2/mod/mod_auth_basic.html">mod_auth_digest</a></code> is unfortunately not possible for conceptual technical reasons.
</p>
</div>
<div id="quickview">
<h3 class="directives">Directives</h3>
<ul id="toc">
<li><img alt="arrow down" src="images/down.png" /> <a href="#authsaslpwcheckmethod">AuthSaslPwcheckMethod</a></li>
<li><img alt="arrow down" src="images/down.png" /> <a href="#authsaslservicename">AuthSaslServiceName</a></li>
<li><img alt="arrow down" src="images/down.png" /> <a href="#authsasldbpath">AuthSaslDbPath</a></li>
<li><img alt="arrow down" src="images/down.png" /> <a href="#authsaslrealm">AuthSaslRealm</a></li>
</ul>
<h3>Example Configurations</h3>
<ul id="toc">
<li><img alt="arrow down" src="images/down.png" /> <a href="#example_htaccess">.htaccess</a></li>
</ul>
<h3>See also</h3>
<ul class="seealso">
<li>
<code class="directive"><a href="http://httpd.apache.org/docs/2.2/mod/mod_auth_basic.html#authbasicprovider">AuthBasicProvider</a></code>
</li>
<li><a href="http://mod-authn-sasl.sourceforge.net/sasl/index.html">libsasl2 documentation</a></li>
</ul>
<p class="centered"><a href="http://sourceforge.net/projects/mod-authn-sasl/">
<img src="http://sflogo.sourceforge.net/sflogo.php?group_id=185449&type=2" width="125" height="37" border="0" alt="sf.net Logo" />
</a></p>
</div>
<div class="top">
<a href="#page-header"><img alt="top" src="images/up.png" /></a>
</div>
<div class="directive-section">
<h2>
<a name="AuthSaslPwcheckMethod" id="AuthSaslPwcheckMethod">AuthSaslPwcheckMethod</a>
<a name="authsaslpwcheckmethod" id="authsaslpwcheckmethod">Directive</a>
</h2>
<table class="directive"><tr>
<th><a href="http://httpd.apache.org/docs/2.2/mod/directive-dict.html#Description">Description:</a></th>
<td>Sets the pwcheck_method used by libsasl2 for authentication.</td>
</tr><tr>
<th><a href="http://httpd.apache.org/docs/2.2/mod/directive-dict.html#Syntax">Syntax:</a></th>
<td><code>AuthSaslPwcheckMethod <var>method [method2]</var></code></td>
</tr><tr>
<th><a href="http://httpd.apache.org/docs/2.2/mod/directive-dict.html#Context">Context:</a></th>
<td>directory, .htaccess</td>
</tr><tr>
<th><a href="http://httpd.apache.org/docs/2.2/mod/directive-dict.html#Override">Override:</a></th>
<td>AuthConfig</td>
</tr><tr>
<th><a href="http://httpd.apache.org/docs/2.2/mod/directive-dict.html#Status">Status:</a></th>
<td>Extension</td>
</tr><tr>
<th><a href="http://httpd.apache.org/docs/2.2/mod/directive-dict.html#Module">Module:</a></th>
<td>mod_authn_sasl</td>
</tr></table>
<p>
The <code class="directive">AuthSaslPwcheckMethod</code> directive sets the password check method used by libsasl2 for authentication.
The module supports the two methods <var>saslauthd</var> and <var>sasldb</var>. If both of them are given as parameters
the second one is used if the user could not be authenticated by the first one. The <var>saslauthd</var> can be configured to
check the password with a variety of mechanisms. Please see the documentation that comes with it for more information.
</p>
<p>For example:</p>
<div class="example"><p><code>
AuthSaslPwcheckMethod sasldb saslauthd
</code></p></div>
<p>
will first try to authenticate using the <var>sasldb</var> method and will try <var>saslauthd</var> if the user could
not be authenticated using <var>sasldb</var>. Generally using <var>sasldb</var> boils down to users being authenticated
using the SASL database whereas <var>saslauthd</var> defers authentication to the SASL authentication daemon,
which also ships with the libsasl2 distribution. The saslauth daemon supports a number of mechanisms of its own, which
allow it to do verification of passwords in a variety of ways, including PAM, LDAP, Kerberos, to name a few. One of the
mechanisms actually is <var>sasldb</var>, it's also offered here directly (really through the <var>auxprop</var> method,
which is an alias for <var>sasldb</var> here) because it's relatively popular and can be used without running another daemon.
Since saslauthd runs with superuser privileges, this is how you would, for example, want to authenticate users against
the data contained in /etc/shadow or any mechanism the requires elevated privileges. See the documentation that comes
with libsasl2 for more information about the methods (<a href="sasl/index.html">local copy</a>).
</p>
<p>
If no <code class="directive">AuthSaslPwcheckMethod</code> directive is given, the authentication defaults to the
<var>saslauthd</var> method.
</p>
</div>
<div class="top">
<a href="#page-header"><img alt="top" src="images/up.png" /></a>
</div>
<div class="directive-section">
<h2>
<a name="AuthSaslServiceName" id="AuthSaslServiceName">AuthSaslServiceName</a>
<a name="authsaslservicename" id="authsaslservicename">Directive</a>
</h2>
<table class="directive"><tr>
<th><a href="http://httpd.apache.org/docs/2.2/mod/directive-dict.html#Description">Description:</a></th>
<td>Sets the service name used by libsasl2 during authentication.</td>
</tr><tr>
<th><a href="http://httpd.apache.org/docs/2.2/mod/directive-dict.html#Syntax">Syntax:</a></th>
<td><code>AuthSaslServiceName <var>name</var></code></td>
</tr><tr>
<th><a href="http://httpd.apache.org/docs/2.2/mod/directive-dict.html#Context">Context:</a></th>
<td>directory, .htaccess</td>
</tr><tr>
<th><a href="http://httpd.apache.org/docs/2.2/mod/directive-dict.html#Override">Override:</a></th>
<td>AuthConfig</td>
</tr><tr>
<th><a href="http://httpd.apache.org/docs/2.2/mod/directive-dict.html#Status">Status:</a></th>
<td>Extension</td>
</tr><tr>
<th><a href="http://httpd.apache.org/docs/2.2/mod/directive-dict.html#Module">Module:</a></th>
<td>mod_authn_sasl</td>
</tr></table>
<p>
The <code class="directive">AuthSaslServiceName</code> directive sets the service name to be used by libsasl2 during user authentication.
Depending on the <code class="directive">AuthSaslPwcheckMethod</code> used this name affects the way how authentication takes place.
For example, if <code>saslauthd</code> is used and it is doing password verification via the <code>pam</code> mechanism, the service name
is passed on to the PAM library. Thus PAM configuration is loaded from <code>/etc/pam.d/<var>name</var></code>. The value of this directive
is unused if you use <code>sasldb</code> on the other hand. Consult the documentation for the mechanism of you choice to see if the SASL
service name is used for plaintext username/password authentication.
</p>
<p>For example:</p>
<div class="example"><p><code>
AuthSaslServiceName webmail
</code></p></div>
<p>
will use <var>webmail</var> as a service name, doing PAM authentication as specified in the file <code>/etc/pam.d/webmail</code> if you
use <code>saslauthd</code> with the <code>pam</code> mechanism.
</p>
<p>If no <code class="directive">AuthSaslServiceName</code> directive is given, the default service name <var>http</var> is used.</p>
<p>
This directive was know as <code class="directive">AuthSaslAppname</code> up to version 1.0.2 of this module, but that name is now
deprecated in favor of this one. Support for the old name may be removed from future version without further notice, so please update
your configuration.
</p>
</div>
<div class="top">
<a href="#page-header"><img alt="top" src="images/up.png" /></a>
</div>
<div class="directive-section">
<h2>
<a name="AuthSaslDbPath" id="AuthSaslDbPath">AuthSaslDbPath</a>
<a name="authsasldbpath" id="authsasldbpath">Directive</a>
</h2>
<table class="directive"><tr>
<th><a href="http://httpd.apache.org/docs/2.2/mod/directive-dict.html#Description">Description:</a></th>
<td>Sets the path to the sasldb file used by libsasl2 for user authentication.</td>
</tr><tr>
<th><a href="http://httpd.apache.org/docs/2.2/mod/directive-dict.html#Syntax">Syntax:</a></th>
<td><code>AuthSaslDbPath <var>path</var></code></td>
</tr><tr>
<th><a href="http://httpd.apache.org/docs/2.2/mod/directive-dict.html#Context">Context:</a></th>
<td>directory, .htaccess</td>
</tr><tr>
<th><a href="http://httpd.apache.org/docs/2.2/mod/directive-dict.html#Override">Override:</a></th>
<td>AuthConfig</td>
</tr><tr>
<th><a href="http://httpd.apache.org/docs/2.2/mod/directive-dict.html#Status">Status:</a></th>
<td>Extension</td>
</tr><tr>
<th><a href="http://httpd.apache.org/docs/2.2/mod/directive-dict.html#Module">Module:</a></th>
<td>mod_authn_sasl</td>
</tr></table>
<p>
The <code class="directive">AuthSaslDbPath</code> directive sets the path to the sasldb file used by libsasl2 during user authentication.
It is only needed if <code class="directive">AuthSaslPwcheckMethod</code> is set to <var>sasldb</var> and you don't want to or can't
use the systemwide database in <var>/etc/sasldb2</var>. It's also good if you want to have separate databases for different web services.
Keep in mind that the webserver needs to be able to access the file, so you need to give the httpd process read rights on the file. This
potentially allows any script run by the webserver to read the file contents as well. So, it's a rather unsafe place to keep your most
secret passwords. Using <code class="directive">AuthSaslPwcheckMethod</code> with <var>saslauthd</var> and the sasldb method there can
effectively prevent this direct access.
</p>
<p>For example:</p>
<div class="example"><p><code>
AuthSaslDbPath /var/www/sites/cms/userdb
</code></p></div>
<p>will use the file <var>/var/www/sites/cms/userdb</var> as a sasl database to look up users and passwords during authenticaton.</p>
<p>If no <code class="directive">AuthSaslDbPath</code> directive is given, the default path <var>/etc/sasldb2</var> is used.</p>
</div>
<div class="top">
<a href="#page-header"><img alt="top" src="images/up.png" /></a>
</div>
<div class="directive-section">
<h2>
<a name="AuthSaslRealm" id="AuthSaslRealm">AuthSaslRealm</a>
<a name="authsaslrealm" id="authsaslrealm">Directive</a>
</h2>
<table class="directive"><tr>
<th><a href="http://httpd.apache.org/docs/2.2/mod/directive-dict.html#Description">Description:</a></th>
<td>Sets the user realm(s) that may be used by libsasl2 during authentication.</td>
</tr><tr>
<th><a href="http://httpd.apache.org/docs/2.2/mod/directive-dict.html#Syntax">Syntax:</a></th>
<td><code>AuthSaslRealm <var>realm</var> [ <var>realm</var> ] ...</code></td>
</tr><tr>
<th><a href="http://httpd.apache.org/docs/2.2/mod/directive-dict.html#Context">Context:</a></th>
<td>directory, .htaccess</td>
</tr><tr>
<th><a href="http://httpd.apache.org/docs/2.2/mod/directive-dict.html#Override">Override:</a></th>
<td>AuthConfig</td>
</tr><tr>
<th><a href="http://httpd.apache.org/docs/2.2/mod/directive-dict.html#Status">Status:</a></th>
<td>Extension</td>
</tr><tr>
<th><a href="http://httpd.apache.org/docs/2.2/mod/directive-dict.html#Module">Module:</a></th>
<td>mod_authn_sasl</td>
</tr></table>
<p>
The <code class="directive">AuthSaslRealm</code> directive sets the user realm(s) that may be used by libsasl2 during authentication.
The Cyrus SASL library supports the concept of realms. A realm is an abstract set of users and certain mechanisms authenticate
users in a certain realm. Users can log in with a username in the format <code>user@realm</code> to specify what realm they are in.
Use this directive if you need to limit the set of allowed realms users can specify. The first realm in the list is the default realm
that will be used for all users that log in without specifying a realm part in the user name.
</p>
<p>For example:</p>
<div class="example"><p><code>
AuthSaslRealm acme.edu cs.acme.edu
</code></p></div>
<p>
will require users to be member in the realm <var>acme.edu</var> or <var>cs.acme.edu</var> to be able to authenticate successfully.
It will use the realm <var>acme.edu</var> for users who do not explicitly specify a realm in the login user name.
</p>
</div>
<div class="top">
<a href="#page-header"><img alt="top" src="images/up.png" /></a>
</div>
<div class="directive-section">
<h2>
<a name="ExampleConfiguration" id="ExampleConfiguration">Example Configuration</a>
<a name="example_htaccess" id="example_htaccess">.htaccess</a>
</h2>
<p>
This .htaccess file will let Apache HTTPD grant access only to users wo can be authenticated against saslauthd:
</p>
<div class="example"><p><code>
AuthType Basic<br/>
AuthName "private area"<br/>
AuthBasicProvider sasl<br/>
AuthBasicAuthoritative On<br/>
AuthSaslPwcheckMethod saslauthd<br/>
Require valid-user<br/>
</code></p></div>
</div>
</div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="index.html" title="English"> en </a></p>
</div>
<div id="footer">
<p class="apache">
Copyright 2011 Heiko Hund.<br />
Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.
</p>
<p class="menu">
<a href="http://sourceforge.net/projects/mod-authn-sasl/">Project Page</a> |
<a href="http://sourceforge.net/project/showfiles.php?group_id=185449">Downloads</a> |
<a href="http://httpd.apache.org/docs/2.2/">Apache HTTPD</a> |
<a href="http://asg.web.cmu.edu/sasl/sasl-library.html">Cyrus SASL</a> |
<a href="http://sourceforge.net">Sourceforge.net</a>
</p>
</div>
</body>
</html>
|
