Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Apache2::AuthTicket(3)User Contributed Perl DocumentatioApache2::AuthTicket(3)

NAME
       Apache2::AuthTicket - Cookie Based Access and Authorization Module

VERSION
       version 0.93

SYNOPSIS
	# in httpd.conf
	PerlModule Apache2::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

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

	<Location /foologinform>
	    AuthType Apache2::AuthTicket
	    AuthName Foo
	    SetHandler perl-script
	    PerlResponseHandler	Apache2::AuthTicket->login_screen
	</Location>

	<Location /foologin>
	    AuthType Apache2::AuthTicket
	    AuthName Foo
	    SetHandler perl-script
	    PerlResponseHandler	Apache2::AuthTicket->login
	</Location>

	<Location /foo/logout>
	    AuthType Apache2::AuthTicket
	    AuthName Foo
	    SetHandler perl-script
	    PerlResponseHandler	Apache2::AuthTicket->logout
	</Location>

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.	Apache2::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
       Apache2::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 Apache2::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 Apache2::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:

	<Location /foo>
	    AuthType Apache2::AuthTicket
	    AuthName Foo
	    PerlAuthenHandler Apache2::AuthTicket->authenticate
	    PerlAuthzHandler Apache2::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 Apache2::AuthTicket
	    AuthName Foo
	    SetHandler perl-script
	    PerlResponseHandler	Apache2::AuthTicket->login_screen
	</Location>

	<Location /foologin>
	    AuthType	Apache2::AuthTicket
	    AuthName	Foo
	    SetHandler	perl-script
	    PerlResponseHandler	Apache2::AuthTicket->login
	</Location>

	<Location /foo/logout>
	    AuthType Apache2::AuthTicket
	    AuthName Foo
	    SetHandler perl-script
	    PerlResponseHandler	Apache2::AuthTicket->logout
	</Location>

   Apache Configuration	- startup.pl
       Any Apache2::AuthTicket configuration items can be set in startup.pl.
       You can configure an AuthName like this:

	Apache2::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 Apache2::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:
	Apache2::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.

	  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
       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
       Apache2::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
	  Apache2::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.

	  Apache2::AuthTicket also provides a mechanism	to determine why the
	  login	for is being displayed.	 This can be used in conjunction with
	  Apache2::AuthCookie's	"AuthCookieReason" setting to determine	why
	  the user is being asked to log in.  Apache2::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 Apache2::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 ($self) = @_;
	       return Foo::dbi_connect();
	   }

	  Note that you	can also adjust	the DBI	connection settings by setting
	  TicketDB, TicketDBUser, and TicketDBPassword in httpd.conf.

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.

SEE ALSO
       perl, mod_perl, Apache2::AuthCookie

SOURCE
       The development version is on github at
       <http://github.com/mschout/apache-authticket> and may be	cloned from
       <git://github.com/mschout/apache-authticket.git>

BUGS
       Please report any bugs or feature requests to
       bug-apache-authticket@rt.cpan.org or through the	web interface at:
	http://rt.cpan.org/Public/Dist/Display.html?Name=Apache-AuthTicket

AUTHOR
       Michael Schout <mschout@cpan.org>

COPYRIGHT AND LICENSE
       This software is	copyright (c) 2000 by Michael Schout.

       This is free software; you can redistribute it and/or modify it under
       the same	terms as the Perl 5 programming	language system	itself.

perl v5.24.1			  2011-06-06		Apache2::AuthTicket(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | CONFIGURATION | METHODS | CREDITS | SEE ALSO | SOURCE | BUGS | AUTHOR | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Apache2::AuthTicket&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help