====================
Using Authentication
====================

----------------
Module: mod_auth
----------------

:Author: Jan Kneschke
:Date: $Date$
:Revision: $Revision$

:abstract:
  The auth module provides ...

.. meta::
  :keywords: lighttpd, authentication

.. contents:: Table of Contents

Description
===========


NOTE: latest documentation can be found at:
https://redmine.lighttpd.net/projects/lighttpd/wiki/Docs_ModAuth


Supported Methods
-----------------

lighttpd supportes both authentication method described by
RFC 2617:

basic
`````

The Basic method transfers the username and the password in
cleartext over the network (base64 encoded) and might result
in security problems if not used in conjunction with an encrypted
channel between client and server.

digest
``````

The Digest method only transfers a hashed value over the
network which performs a lot of work to harden the
authentication process in insecure networks.

Backends
--------

Depending on the method lighttpd provides various way to store
the credentials used for the authentication.

for basic auth:

- plain_
- htpasswd_
- htdigest_
- ldap_

for digest auth:

- plain_
- htdigest_


plain
`````

A file which contains username and the cleartext password
separated by a colon. Each entry is terminated by a single
newline.::

  e.g.:
  agent007:secret


htpasswd
````````

A file which contains username and the crypt()'ed password
separated by a colon. Each entry is terminated by a single
newline. ::

  e.g.:
  agent007:XWY5JwrAVBXsQ

You can use htpasswd from the apache distribution to manage
those files. ::

  $ htpasswd lighttpd.user.htpasswd agent007


htdigest
````````

A file which contains username, realm and the md5()'ed
password separated by a colon. Each entry is terminated
by a single newline. ::

  e.g.:
  agent007:download area:8364d0044ef57b3defcfa141e8f77b65

You can use htdigest from the apache distribution to manage
those files. ::

  $ htdigest lighttpd.user.htdigest 'download area' agent007

Using md5sum can also generate the password-hash: ::

  #!/bin/sh
  user=$1
  realm=$2
  pass=$3

  hash=`echo -n "$user:$realm:$pass" | md5sum | cut -b -32`

  echo "$user:$realm:$hash"

To use it:

  $ htdigest.sh 'agent007' 'download area' 'secret'
  agent007:download area:8364d0044ef57b3defcfa141e8f77b65



ldap
````

the ldap backend is basically performing the following steps
to authenticate a user

1. connect anonymously  (at plugin init)
2. get DN for filter = username
3. auth against ldap server
4. disconnect

if all 4 steps are performed without any error the user is
authenticated

Configuration
=============

::

  ## type of backend
  # plain, htpasswd, ldap or htdigest
  auth.backend               = "htpasswd"

  # filename of the password storage for
  # plain
  auth.backend.plain.userfile = "lighttpd-plain.user"

  ## for htpasswd
  auth.backend.htpasswd.userfile = "lighttpd-htpasswd.user"

  ## for htdigest
  auth.backend.htdigest.userfile = "lighttpd-htdigest.user"

  ## for ldap
  # the $ in auth.backend.ldap.filter is replaced by the
  # 'username' from the login dialog
  auth.backend.ldap.hostname = "localhost"
  auth.backend.ldap.base-dn  = "dc=my-domain,dc=com"
  auth.backend.ldap.filter   = "(uid=$)"
  # if enabled, startTLS needs a valid (base64-encoded) CA
  # certificate
  auth.backend.ldap.starttls   = "enable"
  auth.backend.ldap.ca-file   = "/etc/CAcertificate.pem"

  ## restrictions
  # set restrictions:
  #
  # ( <left-part-of-the-url> =>
  #   ( "method" => "digest"/"basic",
  #     "realm" => <realm>,
  #     "require" => "user=<username>" )
  # )
  #
  # <realm> is a string to display in the dialog
  #         presented to the user and is also used for the
  #         digest-algorithm and has to match the realm in the
  #         htdigest file (if used)
  #

  auth.require = ( "/download/" =>
                   (
		     "method"  => "digest",
		     "realm"   => "download archive",
		     "require" => "user=agent007|user=agent008"
		   ),
		   "/server-info" =>
                   (
		     "method"  => "digest",
		     "realm"   => "download archive",
		     "require" => "valid-user"
		   )
                 )