Ken Williams > Apache-AuthCookie-2.011 > Apache::AuthCookie



Annotate this POD

Related Modules



Open  1
Stalled  1
View/Report Bugs
Module Version: 2.011   Source  


Apache::AuthCookie - Perl Authentication and Authorization via cookies


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

 # In httpd.conf or .htaccess:
 PerlModule Sample::AuthCookieHandler
 PerlSetVar WhatEverPath /
 PerlSetVar WhatEverLoginScript /
 # scope of your cookie.  Default is the current domain.
 PerlSetVar WhatEverDomain

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

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

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

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

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








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->connection->user() to set Apache's idea of who's logged in.


     PerlSetVar WhatEverDomain


This is the flow of the authentication handler, less the details of the redirects. Two REDIRECT'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    |
 ( authenticated (no     )     | FORBIDDEN. Apache abandons      |      
                               | Error document is a script that |  |
                               | generates a form where the user |  |
                 return        | enters authentication           |  |
        /   \                                   |                   |
       /     \                                  |                   |
      /       \                                 V                   |
    /   Pass    \              | User's client submits this form |  |
    \authen_cred/                                                   |
     \ function/                                                    |
      \       /                                                     |
       \     /                                                      |
                                              |                  |
               |                    |         |      | If we had a   |
               V                    |         V      | cookie, add   |
  | returns session key with   |  n |    /  pass   \               ^    
  | sucsesive requests         |    |   /  session  \              |    
               V                       \             /     False
  | Tell Apache to set Expires header,|  \         /
  | set user to user ID returned by   |   \       /
  | authen_ses_key, set authentication|    \     /
         ( Request a protected )              |
         ( session key cookie  )

    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.




There are a few interface changes that you need to be aware of when migrating from version 1.x to 2.x. First, the authen() and authz() methods are now deprecated, replaced by the new authenticate() and authorize() methods. The old methods will go away in a couple versions, but are maintained intact in this version to ease the task of upgrading. The use of these methods is essentially the same, though.

Second, when you change to the new method names (see previous paragraph), you must change the action of your login forms to the location /LOGIN (or whatever URL will call your module's login() method). You may also want to change their METHOD to POST instead of GET, since that's much safer and nicer to look at (but you can leave it as GET if you bloody well want to, for some god-unknown reason).

Third, you must change your login forms (see "THE LOGIN SCRIPT" below) to indicate how requests should be redirected after a successful login.

Fourth, you might want to take advantage of the new logout() method, though you certainly don't have to.




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 an Apache::Registry script, or an HTML::Mason component, 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:


In addition, you might want your login page to be able to tell the difference between a user that sent an incorrect auth cookie, and a user that sent no auth cookie at all. These typically correspond, respectively, to users who logged in incorrectly or aren't allowed to access the given page, and users who are trying to log in for the first time. To help you differentiate between the two, AuthCookie will set $r->subprocess_env('AuthCookieReason') to either bad_cookie or no_cookie. You can examine this value in your login form by examining $r->prev->subprocess_env('AuthCookieReason') (because it's a sub-request).







    my $date = localtime;




If the first unauthenticated request is a POST, it will be changed to a GET after the user fills out the login forms, and POSTed data will be lost.



Ken Williams,

Originally written by Eric Bartley,



syntax highlighting: