/ 
Apache2-AuthCookieDBI-2.19
River stage zero No dependents
/ Apache2::AuthCookieDBI

NAME

Apache2::AuthCookieDBI - An AuthCookie module backed by a DBI database.

COMPATIBILITY

Starting with version 2.03, this module is in the Apache2::* namespace, Apache2::AuthCookieDBI. For mod_perl 1.x versions, there is still Apache::AuthCookieDBI.

SYNOPSIS

 # In httpd.conf or .htaccess
 
 # Optional: Initiate a persistent database connection using Apache::DBI.
 # See: http://search.cpan.org/dist/Apache-DBI/
 # If you choose to use Apache::DBI then the following directive must come
 # before all other modules using DBI - just uncomment the next line:
 #PerlModule Apache::DBI  

 PerlModule Apache2::AuthCookieDBI
 PerlSetVar WhatEverPath /
 PerlSetVar WhatEverLoginScript /login.pl

 # Optional, to share tickets between servers.
 PerlSetVar WhatEverDomain .domain.com
 
 # These must be set
 PerlSetVar WhatEverDBI_DSN "DBI:mysql:database=test"
 PerlSetVar WhatEverDBI_SecretKey "489e5eaad8b3208f9ad8792ef4afca73598ae666b0206a9c92ac877e73ce835c"

 # These are optional, the module sets sensible defaults.
 PerlSetVar WhatEverDBI_User "nobody"
 PerlSetVar WhatEverDBI_Password "password"
 PerlSetVar WhatEverDBI_UsersTable "users"
 PerlSetVar WhatEverDBI_UserField "user"
 PerlSetVar WhatEverDBI_PasswordField "password"
 PerlSetVar WhatEverDBI_UserActiveField "" # Default is skip this feature
 PerlSetVar WhatEverDBI_CryptType "none"
 PerlSetVar WhatEverDBI_GroupsTable "groups"
 PerlSetVar WhatEverDBI_GroupField "grp"
 PerlSetVar WhatEverDBI_GroupUserField "user"
 PerlSetVar WhatEverDBI_EncryptionType "none"
 PerlSetVar WhatEverDBI_SessionLifetime 00-24-00-00

 # Protected by AuthCookieDBI.
 <Directory /www/domain.com/authcookiedbi>
     AuthType Apache2::AuthCookieDBI
     AuthName WhatEver
     PerlAuthenHandler Apache2::AuthCookieDBI->authenticate
     PerlAuthzHandler Apache2::AuthCookieDBI->authorize
     require valid-user
     # or you can require users:
     require user jacob
     # You can optionally require groups.
     require group system
 </Directory>

 # Login location.
 <Files LOGIN>
     AuthType Apache2::AuthCookieDBI
     AuthName WhatEver
     SetHandler perl-script
     PerlHandler Apache2::AuthCookieDBI->login

     # If the directopry you are protecting is the DocumentRoot directory
     # then uncomment the following directive:
     #Satisfy any
 </Files>

DESCRIPTION

This module is an authentication handler that uses the basic mechanism provided by Apache2::AuthCookie with a DBI database for ticket-based protection. It is based on two tokens being provided, a username and password, which can be any strings (there are no illegal characters for either). The username is used to set the remote user as if Basic Authentication was used.

On an attempt to access a protected location without a valid cookie being provided, the module prints an HTML login form (produced by a CGI or any other handler; this can be a static file if you want to always send people to the same entry page when they log in). This login form has fields for username and password. On submitting it, the username and password are looked up in the DBI database. The supplied password is checked against the password in the database; the password in the database can be plaintext, or a crypt() or md5_hex() checksum of the password. If this succeeds, the user is issued a ticket. This ticket contains the username, an issue time, an expire time, and an MD5 checksum of those and a secret key for the server. It can optionally be encrypted before returning it to the client in the cookie; encryption is only useful for preventing the client from seeing the expire time. If you wish to protect passwords in transport, use an SSL-encrypted connection. The ticket is given in a cookie that the browser stores.

After a login the user is redirected to the location they originally wished to view (or to a fixed page if the login "script" was really a static file).

On this access and any subsequent attempt to access a protected document, the browser returns the ticket to the server. The server unencrypts it if encrypted tickets are enabled, then extracts the username, issue time, expire time and checksum. A new checksum is calculated of the username, issue time, expire time and the secret key again; if it agrees with the checksum that the client supplied, we know that the data has not been tampered with. We next check that the expire time has not passed. If not, the ticket is still good, so we set the username.

Authorization checks then check that any "require valid-user" or "require user jacob" settings are passed. Finally, if a "require group foo" directive was given, the module will look up the username in a groups database and check that the user is a member of one of the groups listed. If all these checks pass, the document requested is displayed.

If a ticket has expired or is otherwise invalid it is cleared in the browser and the login form is shown again.

APACHE CONFIGURATION DIRECTIVES

All configuration directives for this module are passed in PerlSetVars. These PerlSetVars must begin with the AuthName that you are describing, so if your AuthName is PrivateBankingSystem they will look like:

PerlSetVar PrivateBankingSystemDBI_DSN "DBI:mysql:database=banking"

See also Apache2::Authcookie for the directives required for any kind of Apache2::AuthCookie-based authentication system.

In the following descriptions, replace "WhatEver" with your particular AuthName. The available configuration directives are as follows:

WhatEverDBI_DSN

Specifies the DSN for DBI for the database you wish to connect to retrieve user information. This is required and has no default value.

WhateverDBI_SecretKey

Specifies the secret key for this auth scheme. This should be a long random string. This should be secret; either make the httpd.conf file only readable by root, or put the PerlSetVar in a file only readable by root and include it.

This is required and has no default value. (NOTE: In AuthCookieDBI versions 1.22 and earlier the secret key either could be set in the configuration file itself or it could be placed in a separate file with the path configured with PerlSetVar WhateverDBI_SecretKeyFile.

As of version 2.0, you must use WhateverDBI_SecretKey and not PerlSetVar WhateverDBI_SecretKeyFile.

If you want to put the secret key in a separate file then you can create a separate file that uses PerlSetVar WhateverDBI_SecretKey and include that file in your main Apache configuration using Apaches' Include directive. You might wish to make the file not world-readable. Also, make sure that the Perl environment variables are not publically available, for example via the /perl-status handler.) See also "COMPATIBILITY" in this man page.

WhatEverDBI_User

The user to log into the database as. This is not required and defaults to undef.

WhatEverDBI_Password

The password to use to access the database. This is not required and defaults to undef.

Make sure that the Perl environment variables are not publically available, for example via the /perl-status handler since the password could be exposed.

WhatEverDBI_UsersTable

The table that user names and passwords are stored in. This is not required and defaults to 'users'.

WhatEverDBI_UserField

The field in the above table that has the user name. This is not required and defaults to 'user'.

WhatEverDBI_PasswordField

The field in the above table that has the password. This is not required and defaults to 'password'.

WhatEverDBI_UserActiveField

The field in the users' table that has a value indicating if the users' account is "active". This is optional and the default is to not use this field. If used then users will fail authentication if the value in this field is not a Perlish true value, so NULL, 0, and the empty string are all false values. The user_is_active class method exposes this setting (and may be overidden in a subclass.)

WhatEverDBI_CryptType

What kind of hashing is used on the password field in the database. This can be 'none', 'crypt', 'md5', 'sha256', 'sha384', or 'sha512'.

md5 will use Digest::MD5::md5hex() and sha... will use Digest::SHA::sha{n}_hex().

This is not required and defaults to 'none'.

WhatEverDBI_GroupsTable

The table that has the user / group information. This is not required and defaults to 'groups'.

WhatEverDBI_GroupField

The field in the above table that has the group name. This is not required and defaults to 'grp' (to prevent conflicts with the SQL reserved word 'group').

WhatEverDBI_GroupUserField

The field in the above table that has the user name. This is not required and defaults to 'user'.

WhatEverDBI_EncryptionType

What kind of encryption to use to prevent the user from looking at the fields in the ticket we give them. This is almost completely useless, so don't switch it on unless you really know you need it. It does not provide any protection of the password in transport; use SSL for that. It can be 'none', 'des', 'idea', 'blowfish', or 'blowfish_pp'.

This is not required and defaults to 'none'.

WhatEverDBI_SessionLifetime

How long tickets are good for after being issued. Note that presently Apache2::AuthCookie does not set a client-side expire time, which means that most clients will only keep the cookie until the user quits the browser. However, if you wish to force people to log in again sooner than that, set this value. This can be 'forever' or a life time specified as:

DD-hh-mm-ss -- Days, hours, minute and seconds to live.

This is not required and defaults to '00-24-00-00' or 24 hours.

WhatEverDBI_SessionModule

Which Apache2::Session module to use for persistent sessions. For example, a value could be "Apache2::Session::MySQL". The DSN will be the same as used for authentication. The session created will be stored in $r->pnotes( WhatEver ).

If you use this, you should put:

PerlModule Apache2::Session::MySQL

(or whatever the name of your session module is) in your httpd.conf file, so it is loaded.

If you are using this directive, you can timeout a session on the server side by deleting the user's session. Authentication will then fail for them.

This is not required and defaults to none, meaning no session objects will be created.

SUBCLASSING

You can subclass this module to override public functions and change their behaviour.

CLASS METHODS

authen_cred($r, $user, $password, @extra_data)

Take the credentials for a user and check that they match; if so, return a new session key for this user that can be stored in the cookie. If there is a problem, return a bogus session key.

authen_ses_key($r, $encrypted_session_key)

Take a session key and check that it is still valid; if so, return the user.

decrypt_session_key($r, $encryptiontype, $encrypted_session_key, $secret_key)

Returns the decrypted session key or false on failure.

extra_session_info($r, $user, $password, @extra_data)

A stub method that you may want to override in a subclass.

This method returns extra fields to add to the session key. It should return a string consisting of ":field1:field2:field3" (where each field is preceded by a colon).

The default implementation returns an empty string.

group($r, $groups_string)

Take a string containing a whitespace-delimited list of groups and make sur that the current remote user is a member of one of them.

Returns either Apache2::Const::HTTP_FORBIDDEN or Apache2::Const::OK.

logger($r, $log_level, $message, $user, $log_type, @extra_args)

Calls one of the Apache::Log methods with:

( $message, @extra_args )

for example, if the log_level is Apache2::Const::LOG_DEBUG then this method will call:

$r->log->debug( $message, @extra_args )

Sub-classes may wish to override this method to perform their own logging, for example to log to a database.

$log_level is one of the constants:

Apache2::Const::LOG_DEBUG
Apache2::Const::LOG_INFO
Apache2::Const::LOG_NOTICE
Apache2::Const::LOG_WARNING
Apache2::Const::LOG_ERR
Apache2::Const::LOG_CRIT
Apache2::Const::LOG_ALERT
Apache2::Const::LOG_EMERG

$message is a text string.

$user should be the username, could be undef in some cases.

$log_type is always undef when called in this module, but sub-classes may wish to use it when they override this method.

@extra_args are appended to the call to the appropriate Apache::Log method. Usually this is simply the value of $r->uri.

user_is_active($r, $user)

If the DBI_UserActiveField is not set then this method returns true without checking the database (this is the default behavior).

If DBI_UserActiveField is set then this method checks the database and returns the value in that field for this user.

DATABASE SCHEMAS

For this module to work, the database tables must be laid out at least somewhat according to the following rules: the user field must be a UNIQUE KEY so there is only one row per user; the password field must be NOT NULL. If you're using MD5 passwords the password field must be 32 characters long to allow enough space for the output of md5_hex(). If you're using crypt() passwords you need to allow 13 characters. If you're using sha256_hex() then you need to allow for 64 characters, for sha384_hex() allow 96 characters, and for sha512_hex() allow 128.

An minimal CREATE TABLE statement might look like:

CREATE TABLE users (
    user VARCHAR(16) PRIMARY KEY,
    password VARCHAR(32) NOT NULL
)

For the groups table, the access table is actually going to be a join table between the users table and a table in which there is one row per group if you have more per-group data to store; if all you care about is group membership though, you only need this one table. The only constraints on this table are that the user and group fields be NOT NULL.

A minimal CREATE TABLE statement might look like:

CREATE TABLE groups (
    grp VARCHAR(16) NOT NULL,
    user VARCHAR(16) NOT NULL
)

COPYRIGHT

Copyright (C) 2002 SF Interactive
Copyright (C) 2003-2004 Jacob Davies
Copyright (C) 2004-2019 Matisse Enzer

LICENSE

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

CREDITS

Original Author: Jacob Davies
Incomplete list of additional contributors (alphabetical by first name):
  Carl Gustafsson
  Chad Columbus
  Edward J Sabol
  Jay Strauss
  Joe Ingersoll
  Keith Lawson
  Lance P Cleveland
  Matisse Enzer
  Nick Phillips
  William McKee

MAINTAINER

Matisse Enzer

<matisse@cpan.org>

SEE ALSO

Latest version: http://search.cpan.org/dist/Apache2-AuthCookieDBI

Apache2::AuthCookie - http://search.cpan.org/dist/Apache2-AuthCookie
Apache2::Session    - http://search.cpan.org/dist/Apache2-Session
Apache::AuthDBI     - http://search.cpan.org/dist/Apache-DBI

TODO

Improve test coverage.
Refactor authen_cred() and authen_ses_key() into several smaller private methods.
Refactor documentation.