mod_auth

mod_auth requires authentication from clients using a username and password. It supports the basic (digest not yet) authentication method as well as plaintext, htpasswd and htdigest backends.

IMPORTANT NOTE: You need to put the auth actions before generating content! If a content handler is already active (like php or static or dirlist), auth will be ignored!

  • 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 communication channel between client and server.
    It is recommend to use https in conjunction with basic authentication.
  • Digest (not supported yet):
    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 (like the internet).
    The “digest” method doesn’t work with the htpasswd backend, only with plaintext and htdigest.

NOTE: The digest method is broken in Internet Explorer < 7. Use basic instead if this is a problem for you. (not supported for now anyway)

auth.plain (action)

requires authentication using a plaintext file

auth.plain options;
options
A key-value table with the following entries:
method
"basic" or "digest" - for now only "basic" is supported, but you still have to specify it.
realm
the realm name to send in the "Need authentication" response to the browser; used in the hash for htdigest too.
file
the filename of the backend data
ttl
(optional) after how many seconds lighty reloads the password file if it got changed and is needed again (defaults to 10 seconds)

requires authentication using a plaintext file containing user:password pairs separated by newlines (\n).

auth.htpasswd (action)

requires authentication using a htpasswd file

auth.htpasswd options;
options
A key-value table with the following entries:
method
only "basic" is supported
realm
the realm name to send in the "Need authentication" response to the browser; used in the hash for htdigest too.
file
the filename of the backend data
ttl
(optional) after how many seconds lighty reloads the password file if it got changed and is needed again (defaults to 10 seconds)
  • requires authentication using a htpasswd file containing user:encrypted_password pairs separated by newlines (\n)
  • passwords are encrypted using crypt(3), use the htpasswd binary from apache to manage the file
    • hashes starting with “$apr1$” ARE supported (htpasswd -m)
    • hashes starting with “{SHA}” ARE supported (followed by sha1_base64(password), htpasswd -s)

auth.htdigest (action)

requires authentication using a htdigest file

auth.htdigest options;
options
A key-value table with the following entries:
method
"basic" or "digest" - for now only "basic" is supported, but you still have to specify it.
realm
the realm name to send in the "Need authentication" response to the browser; used in the hash for htdigest too.
file
the filename of the backend data
ttl
(optional) after how many seconds lighty reloads the password file if it got changed and is needed again (defaults to 10 seconds)
  • requires authentication using a htdigest file containing user:realm:hashed_password tuples separated by newlines (\n)
  • the hashes are bound to the realm, so you can’t change the realm without resetting the passwords
  • passwords are saved as (modified) md5 hashes:
    md5hex(username + ":" + realm + ":" + password)

auth.deny (action)

handles request with "401 Unauthorized"

auth.deny;

auth.debug (option)

enable debug output

auth.debug value;
Default value: false

Example

setup {
	module_load "mod_auth";
}

#/members/ is for known users only
if request.path =^ "/members/" {
	auth.plain [ "method" => "basic", "realm" => "members only", "file" => "/etc/lighttpd/users.txt"];
	if req.env["REMOTE_USER"] !~ "^(admin1|user2|user3)$" { auth.deny; }
}

Example

You can use auth.require_user from the mod_lua plugin contrib/core.lua for the REMOTE_USER check too:

setup {
	module_load ("mod_auth", "mod_lua");
	lua.plugin "contrib/core.lua";
}

#/members/ is for known users only
if request.path =^ "/members/" {
	auth.plain [ "method" => "basic", "realm" => "members only", "file" => "/etc/lighttpd/users.txt"];
	auth.require_user ("admin1", "user2", "user3");
}