This is Info file pm.info, produced by Makeinfo version 1.68 from the input file bigpm.texi.  File: pm.info, Node: Apache/AuthDBI, Next: Apache/AuthLDAP, Prev: Apache/AuthCookieURL, Up: Module List Authentication and Authorization via Perl's DBI *********************************************** NAME ==== Apache::AuthDBI - Authentication and Authorization via Perl's DBI SYNOPSIS ======== # Configuration in httpd.conf or startup.pl: PerlModule Apache::AuthDBI # Authentication and Authorization in .htaccess: AuthName DBI AuthType Basic PerlAuthenHandler Apache::AuthDBI::authen PerlAuthzHandler Apache::AuthDBI::authz PerlSetVar Auth_DBI_data_source dbi:driver:dsn PerlSetVar Auth_DBI_username db_username PerlSetVar Auth_DBI_password db_password #DBI->connect($data_source, $username, $password) PerlSetVar Auth_DBI_pwd_table users PerlSetVar Auth_DBI_uid_field username PerlSetVar Auth_DBI_pwd_field password # authentication: SELECT pwd_field FROM pwd_table WHERE uid_field=$user PerlSetVar Auth_DBI_grp_field groupname # authorization: SELECT grp_field FROM pwd_table WHERE uid_field=$user require valid-user require user user_1 user_2 ... require group group_1 group_2 ... The AuthType is limited to Basic. You may use one or more valid require lines. For a single require line with the requirement 'valid-user' or with the requirements 'user user_1 user_2 ...' it is sufficient to use only the authentication handler. DESCRIPTION =========== This module allows authentication and authorization against a database using Perl's DBI. For supported DBI drivers see: http://www.symbolstone.org/technology/perl/DBI/ Authentication: For the given username the password is looked up in the cache. If the cache is not configured or if the user is not found in the cache, or if the given password does not match the cached password, it is requested from the database. If the username does not exist and the authoritative directive is set to 'on', the request is rejected. If the authoritative directive is set to 'off', the control is passed on to next module in line. If the password from the database for the given username is empty and the nopasswd directive is set to 'off', the request is rejected. If the nopasswd directive is set to 'on', any password is accepted. Finally the passwords (multiple passwords per userid are allowed) are retrieved from the database. The result is put into the environment variable REMOTE_PASSWORDS. Then it is compared to the password given. If the encrypted directive is set to 'on', the given password is encrypted using perl's crypt() function before comparison. If the encrypted directive is set to 'off' the plain-text passwords are compared. If this comparison fails the request is rejected, otherwise the request is accepted and the password is put into the environment variable REMOTE_PASSWORD. The SQL-select used for retrieving the passwords is as follows: SELECT pwd_field FROM pwd_table WHERE uid_field = user If a pwd_whereclause exists, it is appended to the SQL-select. This module supports in addition a simple kind of logging mechanism. Whenever the handler is called and a log_string is configured, the log_field will be updated with the log_string. As log_string - depending upon the database - macros like TODAY can be used. The SQL-select used for the logging mechanism is as follows: UPDATE pwd_table SET log_field = log_string WHERE uid_field = user Authorization: When the authorization handler is called, the authentication has already been done. This means, that the given username/password has been validated. The handler analyzes and processes the requirements line by line. The request is accepted if the first requirement is fulfilled. In case of 'valid-user' the request is accepted. In case of one or more user-names, they are compared with the given user-name until the first match. In case of one or more group-names, all groups of the given username are looked up in the cache. If the cache is not configured or if the user is not found in the cache, or if the requested group does not match the cached group, the groups are requested from the database. A comma separated list of all these groups is put into the environment variable REMOTE_GROUPS. Then these groups are compared with the required groups until the first match. If there is no match and the authoritative directive is set to 'on' the request is rejected. In case the authorization succeeds, the environment variable REMOTE_GROUP is set to the group name, which can be used by user scripts without accessing the database again. The SQL-select used for retrieving the groups is as follows (depending upon the existence of a grp_table): SELECT grp_field FROM pwd_table WHERE uid_field = user SELECT grp_field FROM grp_table WHERE uid_field = user This way the group-information can either be held in the main users table, or in an extra table, if there is an m:n relationship between users and groups. From all selected groups a comma-separated list is build, which is compared with the required groups. If you don't like normalized group records you can put such a comma-separated list of groups (no spaces) into the grp_field instead of single groups. If a grp_whereclause exists, it is appended to the SQL-select. Cache: The module maintains an optional cash for all passwords/groups. See the method setCacheTime(n) on how to enable the cache. Every server has it's own cache. Optionally the cache can be put into a shared memory segment, so that it can be shared among all servers. See the CONFIGURATION section on how to enable the usage of shared memory. In order to prevent the cache from growing indefinitely a CleanupHandler can be initialized, which skips through the cache and deletes all outdated entries. This can be done once per request after sending the response, hence without slowing down response time to the client. The minimum time between two successive runs of the CleanupHandler is configurable (see the CONFIGURATION section). The default is 0, which runs the CleanupHandler after every request. =head1 LIST OF TOKENS * Auth_DBI_data_source (Authentication and Authorization) The data_source value has the syntax 'dbi:driver:dsn'. This parameter is passed to the database driver for processing during connect. The data_source parameter (as well as the username and the password parameters) may be a tilde ('~') separated list of several data_sources. All of these triples will be used until a successful connect is made. This way several backup-servers can be configured. if you want to use the environment variable DBI_DSN instead of a data_source, do not specify this parameter at all. * Auth_DBI_username (Authentication and Authorization) The username argument is passed to the database driver for processing during connect. This parameter may be a tilde ('~') separated list. See the data_source parameter above for the usage of a list. * Auth_DBI_password (Authentication and Authorization) The password argument is passed to the database driver for processing during connect. This parameter may be a tilde ('~') separated list. See the data_source parameter above for the usage of a list. * Auth_DBI_pwd_table (Authentication and Authorization) Contains at least the fields with the username and the (possibly encrypted) password. The username should be unique. * Auth_DBI_uid_field (Authentication and Authorization) Field name containing the username in the Auth_DBI_pwd_table. * Auth_DBI_pwd_field (Authentication only) Field name containing the password in the Auth_DBI_pwd_table. * Auth_DBI_pwd_whereclause (Authentication only) Use this option for specifying more constraints to the SQL-select. * Auth_DBI_grp_table (Authorization only) Contains at least the fields with the username and the groupname. * Auth_DBI_grp_field (Authorization only) Field-name containing the groupname in the Auth_DBI_grp_table. * Auth_DBI_grp_whereclause (Authorization only) Use this option for specifying more constraints to the SQL-select. * Auth_DBI_log_field (Authentication only) Field name containing the log string in the Auth_DBI_pwd_table. * Auth_DBI_log_string (Authentication only) String to update the Auth_DBI_log_field in the Auth_DBI_pwd_table. Depending upon the database this can be a macro like 'TODAY'. * Auth_DBI_authoritative < on / off> (Authentication and Authorization) Default is 'on'. When set 'on', there is no fall-through to other authentication methods if the authentication check fails. When this directive is set to 'off', control is passed on to any other authentication modules. Be sure you know what you are doing when you decide to switch it off. * Auth_DBI_nopasswd < on / off > (Authentication only) Default is 'off'. When set 'on' the password comparison is skipped if the password retrieved from the database is empty, i.e. allow any password. This is 'off' by default to ensure that an empty Auth_DBI_pwd_field does not allow people to log in with a random password. Be sure you know what you are doing when you decide to switch it on. * Auth_DBI_encrypted < on / off > (Authentication only) Default is 'on'. When set to 'on', the password retrieved from the database is assumed to be crypted. Hence the incoming password will be crypted before comparison. When this directive is set to 'off', the comparison is done directly with the plain-text entered password. * Auth_DBI_encryption_salt < password / userid > (Authentication only) When crypting the given password AuthDBI uses per default the password selected from the database as salt. Setting this parameter to 'userid', the module uses the userid as salt. * Auth_DBI_uidcasesensitive < on / off > (Authentication and Authorization) Default is 'on'. When set 'off', the entered userid is converted to lower case. Also the userid in the password select-statement is converted to lower case. * Auth_DBI_pwdcasesensitive < on / off > (Authentication only) Default is 'on'. When set 'off', the entered password is converted to lower case. * Auth_DBI_placeholder < on / off > (Authentication and Authorization) Default is 'off'. When set 'on', the select statement is prepared using a placeholder for the username. This may result in improved performance for databases supporting this method. CONFIGURATION ============= The module should be loaded upon startup of the Apache daemon. Add the following line to your httpd.conf: PerlModule Apache::AuthDBI A common usage is to load the module in a startup file via the PerlRequire directive. See eg/startup.pl for an example. There are three configurations which are server-specific and which can be done in a startup file: Apache::AuthDBI->setCacheTime(0); This configures the lifetime in seconds for the entries in the cache. Default is 0, which turns off the cache. When set to any value n > 0, the passwords/groups of all users will be cached for at least n seconds. After finishing the request, a special handler skips through the cache and deletes all outdated entries (entries, which are older than the CacheTime). Apache::AuthDBI->setCleanupTime(-1); This configures the minimum time in seconds between two successive runs of the CleanupHandler, which deletes all outdated entries from the cache. The default is -1, which disables the CleanupHandler. Setting the interval to 0 runs the CleanupHandler after every request. For a heavily loaded server this should be set to a value, which reflects a compromise between scanning a large cache possibly containing many outdated entries and between running many times the CleanupHandler on a cache containing only few entries. Apache::AuthDBI->initIPC(50000); This enables the usage of shared memory for the cache. Instead of every server maintaining it's own cache, all servers have access to a common cache. This should minimize the database load considerably for sites running many servers. The number indicates the size of the shared memory segment in bytes. This size is fixed, there is no dynamic allocation of more segments. As a rule of thumb multiply the estimated maximum number of simultaneously cached users by 100 to get a rough estimate of the needed size. Values below 500 will be overwritten with the default 50000. To enable debugging the variable $Apache::AuthDBI::DEBUG must be set. This can either be done in startup.pl or in the user script. Setting the variable to 1, just reports about a cache miss. Setting the variable to 2 enables full debug output. PREREQUISITES ============= Note that this module needs mod_perl-1.08 or higher, apache_1.3.0 or higher and that mod_perl needs to be configured with the appropriate call-back hooks: PERL_AUTHEN=1 PERL_AUTHZ=1 PERL_CLEANUP=1 PERL_STACKED_HANDLERS=1 SECURITY ======== In some cases it is more secure not to put the username and the password in the .htaccess file. The following example shows a solution to this problem: httpd.conf: my($uid,$pwd) = My::dbi_pwd_fetch(); $Location{'/foo/bar'}->{PerlSetVar} = [ [ Auth_DBI_username => $uid ], [ Auth_DBI_password => $pwd ], ]; SEE ALSO ======== *Note Apache: Apache,, `mod_perl' in this node, `DBI' in this node AUTHORS ======= * mod_perl by Doug MacEachern * DBI by Tim Bunce * Apache::AuthDBI by Edmund Mergl COPYRIGHT ========= The Apache::AuthDBI module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: Apache/AuthLDAP, Next: Apache/AuthNetLDAP, Prev: Apache/AuthDBI, Up: Module List mod_perl LDAP Access Control and Authentication Module ****************************************************** NAME ==== Apache::AuthLDAP - mod_perl LDAP Access Control and Authentication Module SYNOPSIS ======== # Authentication Realm and Type (only Basic supported) AuthName "Foo Bar Authentication" AuthType Basic # Any of the following variables can be set. Defaults are listed # to the right. PerlSetVar BaseDN o=Foo,c=Bar # Default: Empty String ("") PerlSetVar LDAPServer ldap.foo.com # Default: localhost PerlSetVar LDAPPort 389 # Default: 389 (standard LDAP port) PerlSetVar UIDAttr uid # Default: uid PerlAuthenHandler Apache::AuthLDAP # Require lines can be any of the following: # require valid-user # Any Valid LDAP User require user uid1 uid2 uid2 # Allow Any User in List require ldapattrib val1 val2 # Allow Any User w/ Entry Containing # Matching Attribute and Value These directives can also be used in a .htaccess file. DESCRIPTION =========== This perl module is designed to work with mod_perl and my Net::LDAPapi module (http://www.wwa.com/~donley/). This version of the module does not support access control based on LDAP groups, but the next release will. It does support a handy access control based on attribute and value pairs. This can be used to restrict access to people whose LDAP entries contain a given department number, etc... I welcome feedback on this module and the Net::LDAPapi module. AUTHOR ====== Clayton Donley COPYRIGHT ========= Copyright (c) 1998 Clayton Donley This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: Apache/AuthNetLDAP, Next: Apache/AuthPerLDAP, Prev: Apache/AuthLDAP, Up: Module List mod_perl module that uses the Net::LDAP module for user authentication for Apache ********************************************************************************* NAME ==== Apache::AuthNetLDAP - mod_perl module that uses the Net::LDAP module for user authentication for Apache SYNOPSIS ======== AuthName "LDAP Test Auth" AuthType Basic #only set the next two if you need to bind as a user for searching #PerlSetVar BindDN "uid=user1,ou=people,o=acme.com" #optional #PerlSetVar BindPWD "password" #optional PerlSetVar BaseDN "ou=people,o=acme.com" PerlSetVar LDAPServer ldap.acme.com PerlSetVar LDAPPort 389 #PerlSetVar UIDAttr uid PerlSetVar UIDAttr mail require valid-user PerlAuthenHandler Apache::AuthNetLDAP DESCRIPTION =========== This module authenticates users via LDAP using the Net::LDAP module. This module is Graham Barr's "pure" Perl LDAP API. It also uses all of the same parameters as the Apache::AuthPerLDAP, but I have added two extra parameters. The parameters are: PerlSetVar BindDN Used to set initial LDAP user. PerlSetVar BindPWD Used to set initial LDAP password. PerlSetVar BaseDN This sets the search base used when looking up a user in an LDAP server. PerlSetVar LDAPServer This is the hostname of the LDAP server you wish to use. PerlSetVar LDAPPort This is the port the LDAP server is listening on. PerlSetVar UIDAttr The attribute used to lookup the user. Uses for UIDAttr ---------------- For example if you set the UIDAttr to uid, then the LDAP search filter will lookup a user using the search filter: Normally you will use the uid attribute, but you may want (need) to use a different attribute depending on your LDAP server or to synchronize with different applications. For example some versions of Novell's LDAP servers that I've encountered stored the user's login name in the cn attribute (a really bad idea). And the Netscape Address Book uses a user's email address as the login id. INSTALLATION ============ It's a pretty straightforward install if you already have mod_perl and Net::LDAP already installed. After you have unpacked the distribution type: perl Makefile.PL make make install Then in your httpd.conf file or .htaccess file, in either a or section put: AuthName "LDAP Test Auth" AuthType Basic #only set the next two if you need to bind as a user for searching #PerlSetVar BindDN "uid=user1,ou=people,o=acme.com" #optional #PerlSetVar BindPWD "password" #optional PerlSetVar BaseDN "ou=people,o=acme.com" PerlSetVar LDAPServer ldap.acme.com PerlSetVar LDAPPort 389 PerlSetVar UIDAttr uid require valid-user PerlAuthenHandler Apache::AuthNetLDAP HOMEPAGE ======== Module Home:http://courses.unt.edu/mewilcox/ AUTHOR Mark Wilcox mewilcox@unt.edu ======================================= SEE ALSO *Note Net/LDAP: Net/LDAP, ===================================== ACKNOWLEDGMENTS =============== Graham Barr for writing Net::LDAP module. Henrik Strom for writing the Apache::AuthPerLDAP module which I derived this from. The O'Reilly "Programming Modules for Apache with Perl and C" (http://www.modperl.com). WARRANTY AND LICENSE You can distribute and modify in accordance to the same license as Perl. Though I would like to know how you are using the module or if you are using the module at all. ============================================================================================================================================================================================= Like most of the stuff on the 'net, I got this copy to work for me without destroying mankind, you're mileage may vary.  File: pm.info, Node: Apache/AuthPerLDAP, Next: Apache/AuthTicket, Prev: Apache/AuthNetLDAP, Up: Module List mod_perl PerLDAP Authentication Module ************************************** NAME ==== Apache::AuthPerLDAP - mod_perl PerLDAP Authentication Module SYNOPSIS ======== # Authentication Realm and Type (only Basic supported) AuthName "Foo Bar Authentication" AuthType Basic # Any of the following variables can be set. # Defaults are listed to the right. PerlSetVar BaseDN o=Foo,c=Bar # Default: "" (empty String) PerlSetVar LDAPServer ldap.foo.com # Default: localhost PerlSetVar LDAPPort 389 # Default: 389 (standard LDAP port) PerlSetVar UIDAttr uid # Default: uid require valid-user PerlAuthenHandler Apache::AuthPerLDAP These directives can also be used in a .htaccess file. DESCRIPTION =========== AuthPerLDAP provides Basic Authentication, with username/password lookups against an LDAP server, using Netscape's PerLDAP kit. It is heavily based on Clayton Donley's Apache::AuthLDAP module, but uses the newer Netscape PerLDAP (Mozilla::LDAP), which in turn uses the Netscape Directory SDK for C. Thus Donley's original Net::LDAPapi module and library is no longer required. It requires mod_perl and PerLDAP (v1.2 or later). Building mod_perl with: perl Makefile.PL PERL_AUTHEN=1 PERL_STACKED_HANDLERS=1 PERL_GET_SET_HANDLERS works for me. If this module is the only Apache/Perl module you are going to use, you probably don't need anything but the PERL_AUTHEN hook enabled. Unlike Donley's Apache::AuthLDAP module, AuthPerLDAP is only used for authentication, and thus only supports the require-user directive. If a user enters the correct username and password, the authentication is considered to be OK. TODO ==== * Find out more about these messages in the error_log: "child pid 5244 exit signal Segmentation Fault (11)" * Further testing. * More detailed documentation. * Some examples of how to setup and use this module. CREDITS ======= Apache::AuthPerLDAP is greatly inspired by the original Apache::AuthLDAP written by Clayton Donley. Adoption to PerLDAP was done by reading the PerLDAP source and documentation provided by Netscape Corp. and Leif Hedstrom, found at www.perldap.org. The new book published by O'Reilly & Associates, and authored by Lincoln Stein and Doug MacEachern helped clarify many mod_perl issues I previously had problems with: "Writing Apache Modules with Perl and C" (www.modperl.com). Andreas K. Sorensen provided usefull Perl wisdom during debugging. AUTHOR ====== Henrik Strom COPYRIGHT ========= Copyright (c) 1999 Henrik Strom This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. SEE ALSO ======== mod_perl(1), *Mozilla::LDAP::Conn*, *Apache::AuthenCache*.  File: pm.info, Node: Apache/AuthTicket, Next: Apache/AuthenCache, Prev: Apache/AuthPerLDAP, Up: Module List Cookie based access module. *************************** NAME ==== Apache::AuthTicket - Cookie based access module. SYNOPSIS ======== # in httpd.conf PerlModule Apache::AuthTicket PerlSetVar FooTicketDB DBI:mysql:database=mschout;host=testbed PerlSetVar FooTicketDBUser test PerlSetVar FooTicketDBPassword secret PerlSetVar FooTicketTable tickets:ticket_hash:ts PerlSetVar FooTicketUserTable myusers:usename:passwd PerlSetVar FooTicketPasswordStyle cleartext PerlSetVar FooTicketSecretTable ticket_secrets:sec_data:sec_version PerlSetVar FooTicketExpires 15 PerlSetVar FooTicketLogoutURI /foo/index.html PerlSetVar FooTicketLoginHandler /foologin PerlSetVar FooTicketIdleTimeout 1 PerlSetVar FooPath / PerlSetVar FooDomain .foo.com PerlSetVar FooSecure 1 PerlSetVar FooLoginScript /foologinform AuthType Apache::AuthTicket AuthName Foo PerlAuthenHandler Apache::AuthTicket->authenticate PerlAuthzHandler Apache::AuthTicket->authorize require valid-user AuthType Apache::AuthTicket AuthName Foo SetHandler perl-script Perlhandler Apache::AuthTicket->login_screen AuthType Apache::AuthTicket AuthName Foo SetHandler perl-script PerlHandler Apache::AuthTicket->login AuthType Apache::AuthTicket AuthName Foo SetHandler perl-script PerlHandler Apache::AuthTicket->logout DESCRIPTION =========== This module provides ticket based access control. The theory behind this is similar to the system described in the eagle book. This module works using HTTP cookies to check if a user is authorized to view a page. *Apache::AuthCookie* is used as the underlying mechanism for managing cookies. This module was designed to be as extensible as possible. Its quite likely that you will want to create your own subclass of *Apache::AuthTicket* in order to customize various aspects of this module (show your own versions of the forms, override database methods etc). This system uses cookies to authenticate users. When a user is authenticated through this system, they are issued a cookie consisting of the time, the username of the user, the expriation time of the cookie, a "secret" version (described later), and a cryptographic signature. The cryptographic signature is generated using the MD5 algorithm on the cookie data and a "secret" key that is read from a database. Each secret key also has a version number associated with it. This allows the site administrator to issue a new secret periodically without invalidating the current valid tickets. For example, the site administrator might periodically insert a new secret key into the databse periodically, and flush secrets that are more than 2 days old. Since the ticket issued to the user contains the secret version, the authentication process will still allow tickets to be authorized as long as the corresponding secrets exist in the ticket secrets table. The actual contents and length of secret data is left to the site administrator. A good choice might be to read data from /dev/random, unpack it into a hex string and save that. This system should be reasonably secure becuase the IP address of the end user is incorporated into the cryptographic signature. If the ticket were intercepted, then an attacker would have to steal the user's IP address in order to be able to use the ticket. Plus, since the tickets can expire automatically, we can be sure that the ticket is not valid for a long period of time. Finally, by using the *Secure* mode of *Apache::AuthCookie*, the ticket is not passed over unencrypted connections. In order to attack this system, an attacker would have to exploit both the MD5 algorightm as well as SSL. Chances are, by the time the user could break both of these, the ticket would no longer be valid. CONFIGURATION ============= There are two things you must do in order to configure this module: 1) configure your mod_perl apache server 2) create the necessary database tables. Apache Configuration - httpd.conf --------------------------------- There are two ways that this module could be configured. Either by using a function call in startup.pl, or by configuring each handler explicitly in httpd.conf. If you decide to mix and match using calls to Apache::AuthTicket->configure() with directives in httpd.conf, then remember that the following precedence applies: o If a directive is specified in httpd.conf, it will be used. o else if a directive is specified by configure(), then the configure() value will be used. o else a default value will be used. Default values are subject to change in later versions, so you are better of explicitly configuring all values and not relying on any defaults. There are four blocks that need to be entered into httpd.conf. The first of these is the block specifying your access restrictions. This block should look somrthing like this: AuthType Apache::AuthTicket AuthName Foo PerlAuthenHandler Apache::AuthTicket->authenticate PerlAuthzHandler Apache::AuthTicket->authorize require valid-user The remaining blocks control how to display the login form, and the login and logout urls. These blocks should look similar to this: AuthType Apache::AuthTicket AuthName Foo SetHandler perl-script Perlhandler Apache::AuthTicket->login_screen AuthType Apache::AuthTicket AuthName Foo SetHandler perl-script PerlHandler Apache::AuthTicket->login AuthType Apache::AuthTicket AuthName Foo SetHandler perl-script PerlHandler Apache::AuthTicket->logout Apache Configuration - startup.pl --------------------------------- Any *Apache::AuthTicket* configuration items can be set in startup.pl. You can configure an AuthName like this: Apache::AuthTicket->configure(String auth_name, *Hash config) Note that when configuring this way you dont prefix the configuration items with the AuthName value like you do when using PerlSetVar directives. Note: You must still include *Apache::AuthCookie* configuration directives in httpd.conf when configuring the server this way. These items include: PerlSetVar FooPath / PerlSetVar FooDomain .foo.com PerlSetVar FooSecure 1 PerlSetVar FooLoginScript /foologinform example: Apache::AuthTicket->configure('Foo', { TicketDB => 'DBI:mysql:database=test;host=foo', TicketDBUser => 'mschout', TicketDBPassword => 'secret', TicketTable => 'tickets:ticket_hash:ts', TicketUserTablei => 'myusers:usename:passwd', TicketPasswordStyle => 'cleartext', TicketSecretTable => 'ticket_secrets:sec_data:sec_version', TicketExpires => '15', TicketLogoutURI => '/foo/index.html', TicketLoginHandler => '/foologin', TicketIdleTimeout => 5 }); Valid configuration items are: TicketDB This directive specifys the DBI URL string to use when connecting to the database. Also, you might consider overloading the *dbi_connect* method to handle setting up your db connection if you are creating a subclass of this module. example: dbi:Pg:dbname=test TicketDBUser This directive specifys the username to use when connecting to the databse. TicketDBPassword This directive specifys the password to use when connecting to the databse. TicketTable This directive specifys the ticket hash table as well as the column name for the hash. Format: table_name:ticket_column_name:timestamp_column Example: tickets:ticket_hash:ts TicketUserTable This directive specifys the users table and the username and password column names. Format: table_name:username_column:password_column Example: users:usrname:passwd TicketPasswordStyle This directive specifys what type of passwords are stored in the database. The default is to use cleartext passwords. Currently supported password styles are: cleartext This password style is just plain text passwords. When using this password style, the supplied user password is simply compared with the password stored in the database. md5 This password style generates an MD5 hex hash of the supplied password before comparing it against the password stored in the database. Passwords should be stored in the database by passing them through Digest::MD5->md5_hex(). crypt This password style uses traditional crypt() to encrypt the supplied password before comparing it to the password saved in the database. TicketSecretTable This directive specifys the server secret table as well as the names of the secret data column and the version column. Format: table_name:data_column:version_column Example: ticketsecrets:sec_data:sec_version TicketExpires This directive specifys the number of minutes that tickets should remain valid for. If a user exceeds this limit, they will be forced to log in again. TicketIdleTimeout This directive specifys the number of minutes of inactivity before a ticket is considered invalid. Setting this value to 5 for example would force a re-login if no requests are recieved from the user in a 5 minute period. The default for this value is 0, which disables this feature. If this number is larger than TicketExpires, then this setting will have no effect. TicketLogoutURI This directive specifys the URL that the user should be sent to after they are successfully logged out (this is done via a redirect). Example: /logged_out_message.html Database Configuration ---------------------- Three database tables are needed for this module: *users table* This table stores the actual usernames and passwords of the users. This table needs to contain at least a username and password column. This table is confgured by the TicketUserTable directive. example: CREATE TABLE users ( usename VARCHAR(32) NOT NULL, passwd VARCHAR(32) NOT NULL ); *tickets table* This table stores the ticket hash for each ticket. This information must be stored locally so that users can be forcefully logged out without worrying if the HTTP cookie doesn't get deleted. example: CREATE TABLE tickets ( ticket_hash CHAR(32) NOT NULL, ts INT NOT NULL, PRIMARY KEY (ticket_hash) ); *secrets table* This table contains the server secret and a numeric version for the secret. This table is configured by the TicketSecretTable directive. example: CREATE TABLE ticketsecrets ( sec_version SERIAL, sec_data TEXT NOT NULL ); METHODS ======= This is not a complete listing of methods contained in *Apache::AuthTicket*. Rather, it is a listing of methods that you might want to overload if you were subclassing this module. Other methods that exist in the module are probably not useful to you. Feel free to examine the source code for other methods that you might choose to overload. void make_login_screen($r, String action, String destination) This method creats the "login" screen that is shown to the user. You can overload this method to create your own login screen. The log in screen only needs to contain a hidden field called "destination" with the contents of *destination* in it, a text field named *credential_0* and a password field named *credential_1*. You are responsible for sending the http header as well as the content. See *Apache::AuthCookie* for the description of what each of these fields are for. action contains the action URL for the form. You must set the action of your form to this value for it to function correctly. *Apache::AuthTicket* also provides a mechanism to determine why the login for is being displayed. This can be used in conjunction with *Apache::AuthCookie*'s "AuthCookieReason" setting to determine why the user is being asked to log in. *Apache::AuthCookie* sets $r->prev->subprocess_env("AuthCookieReason") to either "no_cookie" or "bad_cookie" when this page is loaded. If the value is "no_cookie" then the user is being asked to log in for the first time, or they are logging in after they previously logged out. If this value is "bad_cookie" then *Apache::AuthTicket* is asking them to re-login for some reason. To determine what this reason is, you must examine $r->prev->subprocess_env("AuthTicketReason"). *AuthTicketReason* can take the following values: malformed_ticket This value means that the ticket is malformed. In other words, the ticket does not contain all of the required information that should be present. invalid_hash This value means that the hash contained in the ticket does not match any values in the tickets database table. This might happen if you are periodically clearing out old tickets from the database and the user presents a ticket that has been deleted. expired_ticket This value means that the ticket has expired and the user must re-login to be issued a new ticket. missing_secret This value means that the server secret could not be loaded. idle_timeout This value means that the user has exceeded the TicketIdleTimeout minutes of inactivity, and the user must re-login. tampered_hash This value indicates that the ticket data does not match its cryptographic signature, and the ticket has most likely been tampered with. The user is forced to re-login at this point. You can use these values in your *make_login_screen()* method to display a message stating why the user must login (e.g.: "you have exceeded 5 minutes of inactivity and you must re-login"). DBI::db dbi_connect() This method connects to the TicketDB data source. You might overload this method if you have a common DBI connection function. For example: sub dbi_connect { my ($this) = @_; return Foo::dbi_connect(); } Note that you can also adjust the DBI connection settings by setting TicketDB, TicketDBUser, and TicketDBPassword in httpd.conf. BUGS ==== None known, but that doesn't mean there aren't any. If you find a bug in this software, please let me know. CREDITS ======= The idea for this module came from the Ticket Access system in the eagle book, along with several ideas discussed on the mod_perl mailing list. Thanks to Ken Williams for his wonderful *Apache::AuthCookie* module, and for putting in the necessary changes to *Apache::AuthCookie* to make this module work! AUTHOR ====== Michael Schout SEE ALSO ======== *Note Perl: (perl.info)perl,, `mod_perl' in this node, *Note Apache: Apache,, *Note Apache/AuthCookie: Apache/AuthCookie,  File: pm.info, Node: Apache/AuthenCache, Next: Apache/AuthenDBI, Prev: Apache/AuthTicket, Up: Module List Authentication caching used in conjuction with a primary authentication module (Apache::AuthenDBI, Apache::AuthenLDAP, etc.) **************************************************************************************************************************** NAME ==== Apache::AuthenCache - Authentication caching used in conjuction with a primary authentication module (Apache::AuthenDBI, Apache::AuthenLDAP, etc.) SYNOPSIS ======== # In your httpd.conf PerlModule Apache::AuthenCache # In httpd.conf or .htaccess: AuthName Name AuthType Basic PerlAuthenHandler Apache::AuthenCache Apache::AuthenCache::manage_cache require valid-user # Limited to valid-user # Optional parameters # Defaults are listed to the right. PerlSetVar AuthenCache_CacheTime 900 # Default: indefinite PerlSetVar AuthenCache_CaseSensitive Off # Default: On PerlSetVar AuthenCache_Encrypted Off # Default: On PerlSetVar AuthenCache_NoPasswd On # Default: Off DESCRIPTION =========== *Apache::AuthenCache* implements a caching mechanism in order to speed up authentication and to reduce the usage of system resources. It must be used in conjunction with a regular mod_perl authentication module (it was designed with AuthenDBI and AuthenLDAP in mind). For a list of mod_perl authentication modules see: http://www.cpan.org/modules/by-module/Apache/apache-modlist.html When a request that requires authorization is received, AuthenCache::handler looks up the REMOTE_USER in a shared-memory cache (using IPC::Cache) and compares the cached password to the sent password. A new cache is created for the first request or if the cache has expired. If the passwords match, the handler returns OK and clears the downstream Authen handlers from the stack. Otherwise, it returns DECLINED and allows the next PerlAuthenHandler in the chain to be called. After the primary authentication handler completes with an OK, AuthenCache::manage_cache adds the new user to the cache. CONFIGURATION OPTIONS ===================== The following variables can be defined within the configuration of Directory, Location, or Files blocks or within .htaccess files. This directive contains the number of seconds before the cache is expired. Default is an indefinite time limit. PREREQUISITES ============= mod_perl 1.11_01 is required. IPC::Cache is also required. SEE ALSO ======== crypt(3c), httpd(8), mod_perl(1) AUTHORS ======= Jason Bodnar Christian Gilmore COPYRIGHT ========= Copyright (C) 1998-2001, Jason Bodnar This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: Apache/AuthenDBI, Next: Apache/AuthenLDAP, Prev: Apache/AuthenCache, Up: Module List Authentication via Perl's DBI ***************************** NAME ==== Apache::AuthenDBI - Authentication via Perl's DBI SYNOPSIS ======== # Configuration in httpd.conf or srm.conf: PerlModule Apache::AuthenDBI # Authentication in .htaccess: AuthName DBI AuthType Basic #authenticate via DBI PerlAuthenHandler Apache::AuthenDBI PerlSetVar Auth_DBI_data_source dbi:driver:dsn PerlSetVar Auth_DBI_username db_username PerlSetVar Auth_DBI_password db_password #DBI->connect($data_source, $username, $password) PerlSetVar Auth_DBI_pwd_table users PerlSetVar Auth_DBI_uid_field username PerlSetVar Auth_DBI_pwd_field password #SELECT pwd_field FROM pwd_table WHERE uid_field=$user require valid-user The AuthType is limited to Basic. The require directive is limited to 'valid-user' and 'user user_1 user_2 ...'. For group support see AuthzDBI.pm. DESCRIPTION =========== This module allows authentication against a database using Perl's DBI. For supported DBI drivers see: http://www.symbolstone.org/technology/perl/DBI/ For the given username the password is looked up in the cache. If it is not found in the cache, it is requested from the database. If the username does not exist and the authoritative directive is set to 'on', the request is rejected. If the authoritative directive is set to 'off', the control is passed on to next module in line. If the password for the given username is empty and the nopasswd directive is set to 'off', the request is rejected. If the nopasswd directive is set to 'on', any password is accepted. Finally the passwords (multiple passwords per userid are allowed) retrieved from the database are compared to the password given. If the encrypted directive is set to 'on', the given password is encrypted using perl's crypt() function before comparison. If the encrypted directive is set to 'off' the plain-text passwords are compared. If this comparison fails the request is rejected, otherwise the request is accepted. The SQL-select used for retrieving the passwords is as follows: SELECT pwd_field FROM pwd_table WHERE uid_field = user If a pwd_whereclause exists, it is appended to the SQL-select. At the end a CleanupHandler is initialized, which skips through the password cache and deletes all outdated entries. This is done after sending the response, hence without slowing down response time to the client. The default cache_time is set to 0, which disables the cache, because any user would be deleted immediately from the cache. This module supports in addition a simple kind of logging mechanism. Whenever the handler is called and a log_string is configured, the log_field will be updated with the log_string. As log_string - depending upon the database - macros like TODAY can be used. The SQL-select used for the logging mechanism is as follows: UPDATE pwd_table SET log_field = log_string WHERE uid_field = user =head1 LIST OF TOKENS * Auth_DBI_data_source The data_source value should begin with 'dbi:driver_name:'. This value (with the 'dbi:...:' prefix removed) is passed to the database driver for processing during connect. * Auth_DBI_username The username argument is passed to the database driver for processing during connect. * Auth_DBI_password The password argument is passed to the database driver for processing during connect. * Auth_DBI_pwd_table Contains at least the fields with the username and the (encrypted) password. The username should be unique. * Auth_DBI_uid_field Field name containing the username in the Auth_DBI_pwd_table. * Auth_DBI_pwd_field Field name containing the password in the Auth_DBI_pwd_table. * Auth_DBI_pwd_whereclause Use this option for specifying more constraints to the SQL-select. * Auth_DBI_log_field Field name containing the log string in the Auth_DBI_pwd_table. * Auth_DBI_log_string String to update the Auth_DBI_log_field in the Auth_DBI_pwd_table. Depending upon the database this can be a macro like 'TODAY'. * Auth_DBI_authoritative < on / off> Default is 'on'. When set 'on', there is no fall-through to other authentication methods if the authentication check fails. When this directive is set to 'off', control is passed on to any other authentication modules. Be sure you know what you are doing when you decide to switch it off. * Auth_DBI_nopasswd < on / off > Default is 'off'. When set 'on' the password comparison is skipped if the Auth_DBI_pwd_field is empty, i.e. allow any password. This is 'off' by default to ensure that an empty Auth_DBI_pwd_field does not allow people to log in with a random password. Be sure you know what you are doing when you decide to switch it on. * Auth_DBI_encrypted < on / off > Default is 'on'. When set 'on', the value in the Auth_DBI_pwd_field is assumed to be crypted using perl's crypt() function and the incoming password is crypted before comparison. When this directive is set to 'off', the comparison is done directly with the plain-text entered password. * Auth_DBI_uidcasesensitive < on / off > Default is 'on'. When set 'off', the entered userid is converted to lower case. Also the userid in the password select-statement is converted to lower case. * Auth_DBI_pwdcasesensitive < on / off > Default is 'on'. When set 'off', the entered password is converted to lower case. * Auth_DBI_cache_time Default is 0 = off. When set to any value n > 0, the passwords of all users will be cached for n seconds. After finishing the request, a special handler skips through the cache and deletes all outdated entries (entries, which are older than the cache_time). * Auth_DBI_placeholder < on / off > Default is 'off'. When set 'on', the select statement is prepared using a placeholder for the username. This may result in improved performance for databases supporting this method. CONFIGURATION ============= The module should be loaded upon startup of the Apache daemon. Note that this needs mod_perl-1.08 or higher, apache_1.3.0 or higher and that mod_perl needs to be configured with PERL_AUTHEN=1 PERL_CLEANUP=1 PERL_STACKED_HANDLERS=1. Add the following line to your httpd.conf or srm.conf: PerlModule Apache::AuthenDBI PREREQUISITES ============= For Apache::AuthenDBI you need to enable the appropriate call-back hooks when making mod_perl: perl Makefile.PL PERL_AUTHEN=1 PERL_CLEANUP=1 PERL_STACKED_HANDLERS=1. SECURITY ======== In some cases it is more secure not to put the username and the password in the .htaccess file. The following example shows a solution to this problem: httpd.conf: my($uid,$pwd) = My::dbi_pwd_fetch(); $Location{'/foo/bar'}->{PerlSetVar} = [ [ Auth_DBI_username => $uid ], [ Auth_DBI_password => $pwd ], ]; SEE ALSO ======== *Note Apache: Apache,, `mod_perl' in this node, `DBI' in this node AUTHORS ======= * mod_perl by Doug MacEachern * DBI by Tim Bunce * Apache::AuthenDBI by Edmund Mergl COPYRIGHT ========= The Apache::AuthenDBI module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: Apache/AuthenLDAP, Next: Apache/AuthenNIS, Prev: Apache/AuthenDBI, Up: Module List mod_perl LDAP Authentication Module *********************************** NAME ==== Apache::AuthenLDAP - mod_perl LDAP Authentication Module SYNOPSIS ======== # Authentication Realm and Type (only Basic supported) AuthName "Foo Bar Authentication" AuthType Basic # Any of the following variables can be set. # Defaults are listed to the right. PerlSetVar AuthenBaseDN o=Foo,c=Bar # Default: Empty String ("") PerlSetVar LDAPServer ldap.foo.com # Default: localhost PerlSetVar LDAPPort 389 # Default: 389 (standard LDAP port) PerlSetVar UidattrType userid # Default: uid PerlAuthenHandler Apache::AuthenLDAP require valid-user # Any Valid LDAP User # Matching Attribute and Value DESCRIPTION =========== *Apache::AuthenLDAP* is designed to work with mod_perl and Net::LDAP. This module authenticates a user against an LDAP backend. It can be combined with Apache::AuthzLDAP to provide LDAP authorization as well. CONFIGURATION OPTIONS ===================== The following variables can be defined within the configuration of Directory, Location, or Files blocks or within .htaccess files. AuthenBaseDN The base distinguished name with which to query LDAP. By default, the AuthenBaseDN is empty. LDAPServer The hostname for the LDAP server to query. By default, LDAPServer is set to localhost. LDAPPort The port on which the LDAP server is listening. By default, LDAPPort is set to 389. UidAttrType The attribute type name that contains the user's identification. By default, UidAttrType is set to uid. NOTES ===== This module has hooks built into it to handle Apache::AuthenCache version 0.04 and higher passing notes to avoid bugs in the set_handlers() method in mod_perl versions prior to 1.26. AUTHORS ======= Jason Bodnar, Christian Gilmore See ALSO ======== httpd(8), ldap(3), mod_perl(1), slapd(8C) COPYRIGHT Copyright (C) 2001, International Business Machines Corporation and others. All Rights Reserved. This module is free software; you can redistribute it and/or modify it under the terms of the IBM Public License. ================================================================================================================================================================================================================================