Perl Documentation
NAME
authenticate - provide HTTP authentication according to RFC 2617
SYNOPSIS
Plugin authenticate AuthType Digest AuthRealm "Protected Area" AuthFile etc/passwd
DESCRIPTION
This plugin allows you to add standard HTTP authentication to AxKit2. It supports Basic and Digest authentication, but you are strongly encouraged to use digest authentication only, because it provides the best level of security available without resorting to SSL (with it's performance impact and certificate costs).
This plugin does not handle any kind of authorization through groups
or other mechanisms. Any user in AuthFile
is granted access.
If you use Digest authentication, you also gain a free session ID for all
authenticated users without needing cookies or URL parameters. It is generated
at login and can be retrieved through $plugin->send('session-id')
.
If you use that mechanism, you can even log out users using the logout function.
If you want to retrieve the authenticated username, see AxKit2::HTTPHeaders,
i.e. $client->headers_in->user
.
Troubleshooting
Digest authentication is rather strict. A common mistake is to protect a single subdirectory, but to leave the AuthDomain parameter at it's default value. This will cause the user agent to send authentication headers for all requested files (including external CSS stylesheets, public images part of your website design, and so on).
The trouble with this is that Digest auth keeps a count of requested files, and if this plugin isn't called for some of those requests, the count will differ between user-agent and authenticate. Sooner or later, the user will get a erroneous re-authentication request.
So always configure AuthDomain
correctly!
Managing password files
This plugin can be called standalone using this syntax:
perl plugins/authenticate <file> [ -d ] <username> [ <realm> [ <password> ] ]
It will use the most secure encryption method available on the machine it is running on. It can read Apache password files and will upgrade them to AxKit2 format.
Note that you MUST provide the realm
parameter if you have configured
AuthRealm
instead of using the default value.
CONFIG
AuthType
{ Basic
| Digest
}
Choose authentication method.
Digest is recommended, since it is the best you can get short of going the SSL route, i.e. it protects you from everything but eavesdropping on transferred data, which only SSL can defend against, at a price. Not only does it protect your password (an attacker can never read or guess your password just by sniffing on the line), it also effectively prevents more advanced attacks like man-in-the-middle or replay attacks.
Basic provides practically no security, since anyone snooping on your connection can read the password in (superficially obfuscated) plain text. It is widely supported. This is relevant if you expect media players and other embedded HTTP clients to read your data that may not yet know Digest. All regular web browsers know how to speak Digest, so this is probably not an issue anymore.
Digest authentication needs a little bit of server-side state to be really secure. Each session uses about 70 bytes. This may sound a bit non-HTTPish, but in return the possibilities of Digest authentication are used for maximum security. Sessions that are not explicitly logged out are purged after one to two days.
AuthRealm
realm
The realm is an arbitrary string value that separates different authentication realms within a single domain. It is typically shown in the browser's authentication dialog, but it also serves to separate distinct login areas.
Note that choosing a unique realm increases the resilience against cryptographic attacks. There is a default value, but it is highly recommended to set your own.
AuthOptional
true
| false
If set to true, authentication is not enforced. Nevertheless, if authentication credentials
are sent, they are processed and checked as usual, including 401 Unauthenticated
responses
on failure.
This can be used to provide a common home age for your password-protected area where logged-in users get a kind of main menu, while guests get the choice to log in or sign up for your service. In order to make browser send credentials, use the AuthDomain setting and make sure the AuthOptional area is included. Login can be done through a no-op page that is password-protected and just redirects back to the AuthOptional area.
Default is false
. This setting only works with Digest authentication.
AuthFile
filename [ ... ]
A file containing username/password information. It contains a colon-separated list of username, realm, Digest credentials, Basic credentials. You can manage password files by calling this plugin as standalone perl script. One password file can contain multiple passwords for each user, one per realm. So take care to specify the correct realm value when you add/change passwords.
If multiple files are specified, all files are searched in sequence and the first matching
username/realm entry is used. This allows you to implement role-based authentication by
using different password files for different areas. When adding new users (see AuthAllowAdmin
),
the first file is used.
If you have Digest::SHA or Digest::SHA::PurePerl installed, Basic credentials are stored in a more secure fashion.
For compatibility, Apache-style htpasswd and htdigest files are also accepted.
AuthHighSecurity
true
| false
In some situations, a convenience/security tradeoff must be made. In high security mode, values are chosen which are as secure as is appropriate for an unencrypted connection. If this is disabled, settings for more convenient every-day usage are chosen, but a determined attacker with access to raw network data may influence a session.
Currently, only one setting is adjusted: The time window for possible replay attacks if a client doesn't support the modern variant of Digest authentication (Secure: 60 seconds, Default: 3600 seconds). This is only relevant for old/weird browsers, and the convenience issue is that the user must relogin after the given period.
Default is off. Note that except where noted above, both modes provide maximum possible security.
AuthDomain
domain(s)
A string value to send as domain
option in HTTP Digest authorization. It consists of a
quoted string with one or more absolute URIs or absolute paths, separated by space and
specifies where this authentication session is valid. It is perfectly legal to have URIs
for different hosts in that list. Default value is "/", i.e., the whole server.
AuthAllowAdmin
user | @add
| @self
| @none
Allow administration of credentials using the add_password
and del_password
messages, if the specified user is currently authenticated.
If set to @self
(the default), the currently logged in user is allowed to change
her own password or delete his own account (only).
If set to @add
, user credentials can only be added. Deletion is also allowed for
convenience (useful in a "lost password" form), but no outright changes.
Otherwise, no modifications are allowed.
CLIENT NOTES
These are retrievable through $self->client->notes($name)
.
session-id
Digest authentication automatically creates a session ID as a side effect.
reauthenticated
This value is defined if the user just entered her password. It is true if this is not a fresh login, but a real re-authentication, and defined, but false on a fresh login.
This is useful in conjunction with "relogin" to protect extra-sensitive requests like password changes: Force a relogin on undefined values. Ignore change requests and display the corresponding web form again on a defined, but false value. That way, you can make reasonably sure that the user has seen the actual web form so that she knows what she is doing.
If you are using plugins::xsrf_protect, this still works as advertised during XSRF attacks.
MESSAGES HANDLED
logout
Inhvalidates (logs out) the current session. Any further attempt to access protected pages will result in a new login prompt and a new session ID.
relogin
Forces the user to enter her password again, but keeps the current session ID. Useful for very sensitive pages, like password change requests. See "reauthenticated" above. Return this message's return value.
get_secret [ session ]
Returns a unique secret value which is associated with the given session, or the current request session, if not specified. You may hash this secret, but do not even think about sending it over the net.
set_password user, pass
Change the given user's password. The account will be created if it doesn't yet exist.
See also AuthAllowAdmin
.
del_password user
Remove given user's credentials. See also AuthAllowAdmin
.
has_password user
Returns true if the given user account exists.
list_users
Returns a list of known users in the current realm.
MESSAGES SENT
login username, session-id
This message is sent when a user successfully starts a new login session.