1====================
2Using Authentication
3====================
4
5----------------
6Module: mod_auth
7----------------
8
9:Author: Jan Kneschke
10:Date: $Date$
11:Revision: $Revision$
12
13:abstract:
14  The auth module provides ...
15
16.. meta::
17  :keywords: lighttpd, authentication
18
19.. contents:: Table of Contents
20
21Description
22===========
23
24Supported Methods
25-----------------
26
27lighttpd supportes both authentication method described by
28RFC 2617:
29
30basic
31`````
32
33The Basic method transfers the username and the password in
34cleartext over the network (base64 encoded) and might result
35in security problems if not used in conjunction with a crypted
36channel between client and server.
37
38digest
39``````
40
41The Digest method only transfers a hashed value over the
42network which performs a lot of work to harden the
43authentication process in insecure networks.
44
45Backends
46--------
47
48Depending on the method lighttpd provides various way to store
49the credentials used for the authentication.
50
51for basic auth:
52
53- plain_
54- htpasswd_
55- htdigest_
56- ldap_
57
58for digest auth:
59
60- plain_
61- htdigest_
62
63
64plain
65`````
66
67A file which contains username and the cleartext password
68seperated by a colon. Each entry is terminated by a single
69newline.::
70
71  e.g.:
72  agent007:secret
73
74
75htpasswd
76````````
77
78A file which contains username and the crypt()'ed password
79seperated by a colon. Each entry is terminated by a single
80newline. ::
81
82  e.g.:
83  agent007:XWY5JwrAVBXsQ
84
85You can use htpasswd from the apache distribution to manage
86those files. ::
87
88  $ htpasswd lighttpd.user.htpasswd agent007
89
90
91htdigest
92````````
93
94A file which contains username, realm and the md5()'ed
95password seperated by a colon. Each entry is terminated
96by a single newline. ::
97
98  e.g.:
99  agent007:download area:8364d0044ef57b3defcfa141e8f77b65
100
101You can use htdigest from the apache distribution to manage
102those files. ::
103
104  $ htdigest lighttpd.user.htdigest 'download area' agent007
105
106Using md5sum can also generate the password-hash: ::
107
108  #!/bin/sh
109  user=$1
110  realm=$2
111  pass=$3
112
113  hash=`echo -n "$user:$realm:$pass" | md5sum | cut -b -32`
114
115  echo "$user:$realm:$hash"
116
117To use it:
118
119  $ htdigest.sh 'agent007' 'download area' 'secret'
120  agent007:download area:8364d0044ef57b3defcfa141e8f77b65
121
122
123
124ldap
125````
126
127the ldap backend is basically performing the following steps
128to authenticate a user
129
1301. connect anonymously  (at plugin init)
1312. get DN for filter = username
1323. auth against ldap server
1334. disconnect
134
135if all 4 steps are performed without any error the user is
136authenticated
137
138Configuration
139=============
140
141::
142
143  ## debugging
144  # 0 for off, 1 for 'auth-ok' messages, 2 for verbose debugging
145  auth.debug                 = 0
146
147  ## type of backend
148  # plain, htpasswd, ldap or htdigest
149  auth.backend               = "htpasswd"
150
151  # filename of the password storage for
152  # plain
153  auth.backend.plain.userfile = "lighttpd-plain.user"
154
155  ## for htpasswd
156  auth.backend.htpasswd.userfile = "lighttpd-htpasswd.user"
157
158  ## for htdigest
159  auth.backend.htdigest.userfile = "lighttpd-htdigest.user"
160
161  ## for ldap
162  # the $ in auth.backend.ldap.filter is replaced by the
163  # 'username' from the login dialog
164  auth.backend.ldap.hostname = "localhost"
165  auth.backend.ldap.base-dn  = "dc=my-domain,dc=com"
166  auth.backend.ldap.filter   = "(uid=$)"
167  # if enabled, startTLS needs a valid (base64-encoded) CA
168  # certificate
169  auth.backend.ldap.starttls   = "enable"
170  auth.backend.ldap.ca-file   = "/etc/CAcertificate.pem"
171
172  ## restrictions
173  # set restrictions:
174  #
175  # ( <left-part-of-the-url> =>
176  #   ( "method" => "digest"/"basic",
177  #     "realm" => <realm>,
178  #     "require" => "user=<username>" )
179  # )
180  #
181  # <realm> is a string to display in the dialog
182  #         presented to the user and is also used for the
183  #         digest-algorithm and has to match the realm in the
184  #         htdigest file (if used)
185  #
186
187  auth.require = ( "/download/" =>
188                   (
189		     "method"  => "digest",
190		     "realm"   => "download archiv",
191		     "require" => "user=agent007|user=agent008"
192		   ),
193		   "/server-info" =>
194                   (
195		     "method"  => "digest",
196		     "realm"   => "download archiv",
197		     "require" => "valid-user"
198		   )
199                 )
200
201Limitations
202============
203
204- The implementation of digest method is currently not
205  completely compliant with the standard as it still allows
206  a replay attack.
207
208