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
24
25NOTE: latest documentation can be found at:
26https://redmine.lighttpd.net/projects/lighttpd/wiki/Docs_ModAuth
27
28
29Supported Methods
30-----------------
31
32lighttpd supports both authentication method described by
33RFC 2617:
34
35basic
36`````
37
38The Basic method transfers the username and the password in
39cleartext over the network (base64 encoded) and might result
40in security problems if not used in conjunction with an encrypted
41channel between client and server.
42
43digest
44``````
45
46The Digest method only transfers a hashed value over the
47network which performs a lot of work to harden the
48authentication process in insecure networks.
49
50Backends
51--------
52
53Depending on the method lighttpd provides various way to store
54the credentials used for the authentication.
55
56for basic auth:
57
58- plain_
59- htpasswd_
60- htdigest_
61- ldap_
62
63for digest auth:
64
65- plain_
66- htdigest_
67
68
69plain
70`````
71
72A file which contains username and the cleartext password
73separated by a colon. Each entry is terminated by a single
74newline.::
75
76  e.g.:
77  agent007:secret
78
79
80htpasswd
81````````
82
83A file which contains username and the crypt()'ed password
84separated by a colon. Each entry is terminated by a single
85newline. ::
86
87  e.g.:
88  agent007:XWY5JwrAVBXsQ
89
90You can use htpasswd from the apache distribution to manage
91those files. ::
92
93  $ htpasswd lighttpd.user.htpasswd agent007
94
95
96htdigest
97````````
98
99A file which contains username, realm and the md5()'ed
100password separated by a colon. Each entry is terminated
101by a single newline. ::
102
103  e.g.:
104  agent007:download area:8364d0044ef57b3defcfa141e8f77b65
105
106You can use htdigest from the apache distribution to manage
107those files. ::
108
109  $ htdigest lighttpd.user.htdigest 'download area' agent007
110
111Using md5sum can also generate the password-hash: ::
112
113  #!/bin/sh
114  user=$1
115  realm=$2
116  pass=$3
117
118  hash=`echo -n "$user:$realm:$pass" | md5sum | cut -b -32`
119
120  echo "$user:$realm:$hash"
121
122To use it:
123
124  $ htdigest.sh 'agent007' 'download area' 'secret'
125  agent007:download area:8364d0044ef57b3defcfa141e8f77b65
126
127
128
129ldap
130````
131
132the ldap backend is basically performing the following steps
133to authenticate a user
134
1351. connect anonymously  (at plugin init)
1362. get DN for filter = username
1373. auth against ldap server
1384. disconnect
139
140if all 4 steps are performed without any error the user is
141authenticated
142
143Configuration
144=============
145
146::
147
148  ## type of backend
149  # plain, htpasswd, ldap or htdigest
150  auth.backend               = "htpasswd"
151
152  # filename of the password storage for
153  # plain
154  auth.backend.plain.userfile = "lighttpd-plain.user"
155
156  ## for htpasswd
157  auth.backend.htpasswd.userfile = "lighttpd-htpasswd.user"
158
159  ## for htdigest
160  auth.backend.htdigest.userfile = "lighttpd-htdigest.user"
161
162  ## for ldap
163  # the $ in auth.backend.ldap.filter is replaced by the
164  # 'username' from the login dialog
165  auth.backend.ldap.hostname = "localhost"
166  auth.backend.ldap.base-dn  = "dc=my-domain,dc=com"
167  auth.backend.ldap.filter   = "(uid=$)"
168  # if enabled, startTLS needs a valid (base64-encoded) CA
169  # certificate
170  auth.backend.ldap.starttls   = "enable"
171  auth.backend.ldap.ca-file   = "/etc/CAcertificate.pem"
172
173  ## restrictions
174  # set restrictions:
175  #
176  # ( <left-part-of-the-url> =>
177  #   ( "method" => "digest"/"basic",
178  #     "realm" => <realm>,
179  #     "require" => "user=<username>" )
180  # )
181  #
182  # <realm> is a string to display in the dialog
183  #         presented to the user and is also used for the
184  #         digest-algorithm and has to match the realm in the
185  #         htdigest file (if used)
186  #
187
188  auth.require = ( "/download/" =>
189                   (
190		     "method"  => "digest",
191		     "realm"   => "download archive",
192		     "require" => "user=agent007|user=agent008"
193		   ),
194		   "/server-info" =>
195                   (
196		     "method"  => "digest",
197		     "realm"   => "download archive",
198		     "require" => "valid-user"
199		   )
200                 )
201