Know-How für Ihr Projekt

Perl Documentation


authenticate - provide HTTP authentication according to RFC 2617


Plugin authenticate
AuthType Digest
AuthRealm "Protected Area"
AuthFile etc/passwd


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.


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.


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.


These are retrievable through $self->client->notes($name).


Digest authentication automatically creates a session ID as a side effect.


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.



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.


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.


Returns a list of known users in the current realm.


login username, session-id

This message is sent when a user successfully starts a new login session.