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

FreeBSD Manual Pages


home | help
Apache2_4::AuthCookie(User Contributed Perl DocumentatApache2_4::AuthCookie(3)

       Apache2_4::AuthCookie - Perl Authentication and Authorization via
       cookies for Apache 2.4

       version 3.26

       Make sure your mod_perl is at least 2.0.9, with StackedHandlers,
       MethodHandlers, Authen, and Authz compiled in.

	# In httpd.conf	or .htaccess:
	PerlModule Sample::Apache2::AuthCookieHandler
	PerlSetVar WhatEverPath	/
	PerlSetVar WhatEverLoginScript /

	# The following	line is	optional - it allows you to set	the domain
	# scope	of your	cookie.	 Default is the	current	domain.
	PerlSetVar WhatEverDomain

	# Use this to only send	over a secure connection
	PerlSetVar WhatEverSecure 1

	# Use this if you want user session cookies to expire if the user
	# doesn't request a auth-required or recognize_user page for some
	# time period.	If set,	a new cookie (with updated expire time)
	# is set on every request.
	PerlSetVar WhatEverSessionTimeout +30m

	# to enable the	HttpOnly cookie	property, use HttpOnly.
	# this is an MS	extension.  See:
	PerlSetVar WhatEverHttpOnly 1

	# Usually documents are	uncached - turn	off here
	PerlSetVar WhatEverCache 1

	# Use this to make your	cookies	persistent (+2 hours here)
	PerlSetVar WhatEverExpires +2h

	# Use to make AuthCookie send a	P3P header with	the cookie
	# see for details about what the	value
	# of this should be
	PerlSetVar WhatEverP3P "CP=\"...\""

	# optional: enable decoding of intercepted GET/POST params:
	PerlSetVar WhatEverEncoding UTF-8

	# optional: enable decoding of httpd.conf "Requires" directives
	PerlSetVar WhatEverRequiresEncoding UTF-8

	# These	documents require user to be logged in.
	<Location /protected>
	 AuthType Sample::Apache2::AuthCookieHandler
	 AuthName WhatEver
	 PerlAuthenHandler Sample::Apache2::AuthCookieHandler->authenticate
	 Require valid-user

	# How to handle	a custom requirement (non-user).
	PerlAddAuthzProvider species Sample::Apache2::AuthCookieHandler->authz_species
	<Location /protected/species>
	  Require species klingon

	# These	documents don't	require	logging	in, but	allow it.
	<FilesMatch "\.ok$">
	 AuthType Sample::Apache2::AuthCookieHandler
	 AuthName WhatEver
	 PerlFixupHandler Sample::Apache2::AuthCookieHandler->recognize_user

	# This is the action of	the script above.
	<Files LOGIN>
	 AuthType Sample::Apache2::AuthCookieHandler
	 AuthName WhatEver
	 SetHandler perl-script
	 PerlResponseHandler Sample::Apache2::AuthCookieHandler->login

       This module is for "mod_perl" version 2 for "Apache" version 2.4.x.  If
       you are running mod_perl	version	1, you need Apache::AuthCookie
       instead.	 If you	are running "Apache" 2.0.0-2.2.x, you need
       Apache2::AuthCookie instead.

       Apache2_4::AuthCookie allows you	to intercept a user's first
       unauthenticated access to a protected document. The user	will be
       presented with a	custom form where they can enter authentication
       credentials. The	credentials are	posted to the server where AuthCookie
       verifies	them and returns a session key.

       The session key is returned to the user's browser as a cookie. As a
       cookie, the browser will	pass the session key on	every subsequent
       accesses. AuthCookie will verify	the session key	and re-authenticate
       the user.

       All you have to do is write a custom module that	inherits from
       AuthCookie.  Your module	is a class which implements two	methods:

	   Verify the user-supplied credentials	and return a session key.  The
	   session key can be any string - often you'll	use some string
	   containing username,	timeout	info, and any other information	you
	   need	to determine access to documents, and append a one-way hash of
	   those values	together with some secret key.

	   Verify the session key (previously generated	by "authen_cred()",
	   possibly during a previous request) and return the user ID.	This
	   user	ID will	be fed to "$r->user()" to set Apache's idea of who's
	   logged in.

       By using	AuthCookie versus Apache's built-in AuthBasic you can design
       your own	authentication system.	There are several benefits.

       1.  The client doesn't *have* to	pass the user credentials on every
	   subsequent access.  If you're using passwords, this means that the
	   password can	be sent	on the first request only, and subsequent
	   requests don't need to send this (potentially sensitive)
	   information.	 This is known as "ticket-based" authentication.

       2.  When	you determine that the client should stop using	the
	   credentials/session key, the	server can tell	the client to delete
	   the cookie.	Letting	users "log out"	is a notoriously impossible-
	   to-solve problem of AuthBasic.

       3.  AuthBasic dialog boxes are ugly.  You can design your own HTML
	   login forms when you	use AuthCookie.

       4.  You can specify the domain of a cookie using	"PerlSetVar" commands.
	   For instance, if your AuthName is "WhatEver", you can put the

	    PerlSetVar WhatEverDomain

	   into	your server setup file and your	access cookies will span all
	   hosts ending	in "".

       5.  You can optionally specify the name of your cookie using the
	   "CookieName"	directive.  For	instance, if your AuthName is
	   "WhatEver", you can put the command

	    PerlSetVar WhatEverCookieName MyCustomName

	   into	your server setup file and your	cookies	for this AuthCookie
	   realm will be named MyCustomName.  Default is AuthType_AuthName.

       This is the flow	of the authentication handler, less the	details	of the
       redirects. Two HTTP_MOVED_TEMPORARILY's are used	to keep	the client
       from displaying the user's credentials in the Location field. They
       don't really change AuthCookie's	model, but they	do add another round-
       trip request to the client.

	(-----------------------)     +---------------------------------+
	( Request a protected	)     |	AuthCookie sets	custom error	|
	( page,	but user hasn't	)---->|	document and returns		|
	( authenticated	(no	)     |	HTTP_FORBIDDEN.	Apache abandons	|
	( session key cookie)	)     |	current	request	and creates sub	|
	(-----------------------)     |	request	for the	error document.	|<-+
				      |	Error document is a script that	|  |
				      |	generates a form where the user	|  |
			return	      |	enters authentication		|  |
		 ^------------------->|	credentials (login & password).	|  |
		/ \	 False	      +---------------------------------+  |
	       /   \				       |		   |
	      /	    \				       |		   |
	     /	     \				       V		   |
	    /	      \		      +---------------------------------+  |
	   /   Pass    \	      |	User's client submits this form	|  |
	  /   user's	\	      |	to the LOGIN URL, which	calls	|  |
	  | credentials	|<------------|	AuthCookie->login().		|  |
	  \	to	/	      +---------------------------------+  |
	   \authen_cred/						   |
	    \ function/							   |
	     \	     /							   |
	      \	    /							   |
	       \   /		+------------------------------------+	   |
		\ /   return	| Authen cred returns a	session	     |	+--+
		 V------------->| key which is opaque to AuthCookie.*|	|
		       True	+------------------------------------+	|
						     |			|
		      +--------------------+	     |	    +---------------+
		      |			   |	     |	    | If we had	a   |
		      V			   |	     V	    | cookie, add   |
	 +----------------------------+	 r |	     ^	    | a	Set-Cookie  |
	 | If we didn't	have a session|	 e |T	    / \	    | header to	    |
	 | key cookie, add a	      |	 t |r	   /   \    | override the  |
	 | Set-Cookie header with this|	 u |u	  /	\   | invalid cookie|
	 | session key.	Client then   |	 r |e	 /	 \  +---------------+
	 | returns session key with   |	 n |	/  pass	  \		  ^
	 | successive requests	      |	   |   /  session  \		  |
	 +----------------------------+	   |  /	  key to    \	 return	  |
		      |			   +-| authen_ses_key|------------+
		      V			      \		    /	  False
	 +-----------------------------------+ \	   /
	 | Tell	Apache to set Expires header,|	\	  /
	 | set user to user ID returned	by   |	 \	 /
	 | authen_ses_key, set authentication|	  \	/
	 | to our type (e.g. AuthCookie).    |	   \   /
	 +-----------------------------------+	    \ /
		(---------------------)		     ^
		( Request a protected )		     |
		( page,	user has a    )--------------+
		( session key cookie  )

	*  The session key that	the client gets	can be anything	you want.  For
	   example, encrypted information about	the user, a hash of the
	   username and	password (similar in function to Digest
	   authentication), or the user	name and password in plain text
	   (similar in function	to HTTP	Basic authentication).

	   The only requirement	is that	the authen_ses_key function that you
	   create must be able to determine if this session_key	is valid and
	   map it back to the originally authenticated user ID.

       You must	define this method yourself in your subclass of
       "Apache2_4::AuthCookie".	 Its job is to create the session key that
       will be preserved in the	user's cookie.	The arguments passed to	it

	sub authen_cred	($$\@) {
	    my $self = shift;  # Package name (same as AuthName	directive)
	    my $r    = shift;  # Apache	request	object
	    my @cred = @_;     # Credentials from login	form

	    ...blah blah blah, create a	session	key...
	    return $session_key;

       The only	limitation on the session key is that you should be able to
       look at it later	and determine the user's username.  You	are
       responsible for implementing your own session key format.  A typical
       format is to make a string that contains	the username, an expiration
       time, whatever else you need, and an MD5	hash of	all that data together
       with a secret key.  The hash will ensure	that the user doesn't tamper
       with the	session	key.

       You must	define this method yourself in your subclass of
       "Apache2_4::AuthCookie".	 Its job is to look at a session key and
       determine whether it is valid.  If so, it returns the username of the
       authenticated user.

	sub authen_ses_key ($$$) {
	    my ($self, $r, $session_key) = @_;
	    ...blah blah blah, check whether $session_key is valid...
	    return $ok ? $username : undef;

       Optionally, return an array of 2	or more	items that will	be passed to
       method custom_errors. It	is the responsibility of this method to	return
       the correct response to the main	Apache module.

       This method handles the server response when you	wish to	access the
       Apache custom_response method. Any suitable response can	be used. this
       is particularly useful when implementing	'by directory' access control
       using the user authentication information. i.e.

		       /one	       user is allowed access here
		       /two	       not here
		       /three	       AND here

       The authen_ses_key method would return a	normal response	when the user
       attempts	to access 'one'	or 'three' but return (NOT_FOUND, 'File	not
       found') if an attempt was made to access	subdirectory 'two'. Or,	in the
       case of expired credentials, (AUTH_REQUIRED,'Your session has timed
       out, you	must login again').

	 example 'custom_errors'

	 sub custom_errors {
	     my	($self,$r,$CODE,$msg) =	@_;

	     # return custom message else use the server's standard message
	     $r->custom_response($CODE,	$msg) if $msg;


	 where CODE is a valid code from Apache2::Const

       For an example of how to	use "Apache2_4::AuthCookie", you may want to
       check out the test suite, which runs AuthCookie through a few of	its
       paces.  The documents are located in t/eg/, and you may want to peruse
       t/real.t	to see the generated httpd.conf	file (at the bottom of real.t)
       and check out what requests it's	making of the server (at the top of

       AuthCookie provides support for decoding	POST/GET data if you tell it
       what the	client encoding	is.  You do this by setting the
       "${auth_name}Encoding" setting in "httpd.conf".	E.g.:

	PerlSetVar WhateEverEncoding UTF-8
	# and you also need to arrange for charset=UTF-8 at the	end of the
	# Content-Type header with something like:
	AddDefaultCharset UTF-8

       Note that you can use charsets other than "UTF-8", however, you need to
       arrange for the browser to send the right encoding back to the server.

       If you have turned on Encoding support by setting
       "${auth_name}Encoding", this has	the following effects:

       o   The internal	pure-perl params processing subclass will be used,
	   even	if libapreq2 is	installed.  libapreq2 does not have any
	   support for encoding	or unicode.

       o   POST/GET data intercepted by	AuthCookie will	be decoded to perl's
	   internal format using "decode" in Encode.

       o   The value stored in "$r->user" will be encoded as bytes, not
	   characters using the	configured encoding name.  This	is because the
	   value stored	by mod_perl is a C API string, and not a perl string.
	   You can use decoded_user() to get user string encoded using
	   character semantics.

       This does has some caveats:

       o   your	authen_cred() and authen_ses_key() function is expected	to
	   return a decoded username, either by	passing	it through "decode()"
	   in Encode, or, by turning on	the UTF8 flag if appropriate.

       o   Due to the way HTTP works, cookies cannot contain non-ASCII
	   characters.	Because	of this, if you	are including the username in
	   your	generated session key, you will	need to	escape any non-ascii
	   characters in the session key returned by authen_cred().

       o   Similarly, you must reverse this escaping process in
	   authen_ses_key() and	return a "decode()" in Encode decoded
	   username.  If your authen_cred() function already only generates
	   ASCII-only session keys then	you do not need	to worry about any of

       o   The value stored in "$r->user" will be encoded using	bytes
	   semantics using the configured Encoding.  If	you want the decoded
	   user	value, use decoded_user() instead.

       You can also specify what the charset is	of the Apache "$r->requires"
       data is by setting "${auth_name}RequiresEncoding" in httpd.conf.


	PerlSetVar WhatEverRequiresEncoding UTF-8

       This will make it so that AuthCookie will decode	your "requires"
       directives using	the configured character set.  You really only need to
       do this if you have used	non-ascii characters in	any of your "requires"
       directives in httpd.conf.  e.g.:

	requires user programmA,r

       You will	need to	create a login script (called above) that
       generates an HTML form for the user to fill out.	 You might generate
       the page	using a	ModPerl::Registry script, a HTML::Mason	component, an
       Apache handler, or perhaps even using a static HTML page.  It's usually
       useful to generate it dynamically so that you can define	the
       'destination' field correctly (see below).

       The following fields must be present in the form:

       1.  The ACTION of the form must be /LOGIN (or whatever you defined in
	   your	server configuration as	handled	by the "->login()" method -
	   see example in the SYNOPSIS section).

       2.  The various user input fields (username, passwords, etc.) must be
	   named 'credential_0', 'credential_1', etc. on the form.  These will
	   get passed to your "authen_cred()" method.

       3.  You must define a form field	called 'destination' that tells
	   AuthCookie where to redirect	the request after successfully logging
	   in.	Typically this value is	obtained from "$r->prev->uri".	See
	   the	script in t/eg/.

       In addition, you	might want your	login page to be able to tell why the
       user is being asked to log in.  In other	words, if the user sent	bad
       credentials, then it might be useful to display an error	message	saying
       that the	given username or password are invalid.	 Also, it might	be
       useful to determine the difference between a user that sent an invalid
       auth cookie, and	a user that sent no auth cookie	at all.	 To cope with
       these situations, AuthCookie will set
       "$r->subprocess_env('AuthCookieReason')"	to one of the following

	   The user presented no cookie	at all.	 Typically this	means the user
	   is trying to	log in for the first time.

	   The cookie the user presented is invalid.  Typically	this means
	   that	the user is not	allowed	access to the given page.

	   The user tried to log in, but the credentials that were passed are

       You can examine this value in your login	form by	examining
       "$r->prev->subprocess_env('AuthCookieReason')" (because it's a sub-

       Of course, if you want to give more specific information	about why
       access failed when a cookie is present, your "authen_ses_key()" method
       can set arbitrary entries in "$r->subprocess_env".

       If you want to let users	log themselves out (something that can't be
       done using Basic	Auth), you need	to create a logout script.  For	an
       example,	see t/htdocs/docs/  Logout scripts may want to take
       advantage of AuthCookie's "logout()" method, which will set the proper
       cookie headers in order to clear	the user's cookie.  This usually looks
       like "$r->auth_type->logout($r);".

       Note that if you	don't necessarily trust	your users, you	can't count on
       cookie deletion for logging out.	 You'll	have to	expire some server-
       side login information too.  AuthCookie doesn't do this for you,	you
       have to handle it yourself.

       Unlike the sample AuthCookieHandler, you	have you verify	the user's
       login and password in "authen_cred()", then you do something like:

	   my $date = localtime;
	   my $ses_key = Digest::SHA::sha256_hex(join(';', $date, $PID,	$PAC));

       save $ses_key along with	the user's login, and return $ses_key.

       Now "authen_ses_key()" looks up the $ses_key passed to it and returns
       the saved login.	 I use a database to store the session key and
       retrieve	it later.

       o   I upgraded to Apache	2.4 and	now AuthCookie doesn't work!

	   Apache 2.4 radically	changed	the authenciation and authorization
	   API.	 You will need to port your AuthCookie subclass	over to	the
	   Apache 2.4 API.  See	the POD	documenation in	README.apache-2.4 for
	   more	information, but the quick rundown is you need to:

	   o   Inherit from "Apache2_4::AuthCookie"

	   o   Remove all "PerlAuthzHandler" configuration entries.

	   o   Write Authz Provider methods for	any "Requires" directives that
	       you are using that apache does not provide for already (e.g.
	       apache already handles "user" and "valid-user") and register
	       them with something like.

		PerlAddAuthzProvier species Sample::AuthCookieHandler->authz_species

	   o   Replace instances of "${AuthName}Satistfy" with either
	       "RequireAll" or "RequireAny" blocks.

       o   Why is my authz method called twice per request?

	   This	is normal behaviour under Apache 2.4.  This is to accommodate
	   for authorization of	anonymous access. You are expected to return
	   "Apache2::Const::AUTHZ_DENIED_NO_USER" IF "$r->user"	has not	yet
	   been	set if you want	authentication to proceed.  Your authz handler
	   will	be called a second time	after the user has been	authenticated.

       o   AuthCookie authenticates, but the authorization handler is
	   returning "UNAUTHORIZED" instead of "FORBIDDEN"!

	   In Apache 2.4, in "mod_authz_core", if no authz handlers return
	   "AUTHZ_GRANTED", then "HTTP_UNAUTHORIZED" is	returned.  In previous
	   versions of Apache, "HTTP_FORBIDDEN"	was returned.  You can get the
	   old behaviour if you	want it	with:

	    AuthzSendForbiddenOnFailure	On

       o   My log shows	an entry like:

	    authorization result of Require ...: denied	(no authenticated user yet)

	   These are normal.  This happens because the authz provider returned
	   "AUTHZ_DENIED_NO_USER" and the authz	provider will be called	again
	   after authentication	happens.

       Originally written by Eric Bartley <>

       versions	2.x were written by Ken	Williams <>

       Copyright (c) 2015 Michael Schout. All rights reserved.

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


       The development version is on github at
       <> and may be	cloned from

       Please report any bugs or feature requests to or through the	web interface at:

       Michael Schout <>

       This software is	copyright (c) 2000 by Ken Williams.

       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			  2016-09-30	      Apache2_4::AuthCookie(3)


Want to link to this manual page? Use this URL:

home | help