Apache Configuration - httpd.conf

 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:

 <Location /foo>
     AuthType Apache::AuthTicket
     AuthName Foo
     PerlAuthenHandler Apache::AuthTicket->authenticate
     PerlAuthzHandler Apache::AuthTicket->authorize
     require valid-user
 </Location>

The remaining blocks control how to display the login form, and the login and logout urls. These blocks should look similar to this:

 <Location /foologinform>
     AuthType Apache::AuthTicket
     AuthName Foo
     SetHandler perl-script
     Perlhandler Apache::AuthTicket->login_screen
 </Location>
 
 <Location /foologin>
     AuthType    Apache::AuthTicket
     AuthName    Foo
     SetHandler  perl-script
     PerlHandler Apache::AuthTicket->login
 </Location>
 
 <Location /foo/logout>
     AuthType Apache::AuthTicket
     AuthName Foo
     SetHandler perl-script
     PerlHandler Apache::AuthTicket->logout
 </Location>

Apache Configuration - startup.pl

 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', TicketUserTable => '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:

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.

This should not be confused with the inherited AuthCookie setting "Expire", which is the cookie expiration time. "TicketExpires" controls the expiration of the ticket, not the cookie.

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

TicketCheckIP (default: on)

This controlls whether or not the client IP address is included in the ticket hash. The default is 'on'. If you turn this off, then the client ip address will not be checked. It is sometimes not desirable to check the client ip if the clients are behind load balancers and subsequent requests might come in from a different IP.

TicketCheckBrowser (default: off)

This controlls whether or not the "USER_AGENT" string is included in the ticket hash. This can be used in conjunction with, or instead of "TicketCheckIP" to prevent tampering with the ticket.

Database Configuration

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
 );