View on
Bill Moseley > Apache-AuthCookieURL-1.003 > Apache::AuthCookieURL



Annotate this POD

View/Report Bugs
Module Version: 1.003   Source  


Apache::AuthCookieURL - Perl Authentication and Authorization or session management via cookies or URL munging


In httpd.conf

    # Your module that overrides AuthCookieURL methods
    PerlModule My::AuthCookieURLHandler

    # Or to use simple session generation w/o persistence
    #PerlModule Apache::AuthCookieURL

    ## Some settings -- "Whatever" is set by AuthName ##
    # most can be set within <directory> sections

    # Send expires with cookie
    PerlSetVar WhateverExpires +90d

    # Other cookie settings
    #PerlSetVar WhateverDomain some.domain

    # This can only be set to "/" if using URL sessions
    #PerlSetVar WhateverPath /path
    #PerlSetVar WhateverSecure 1

    # Login script to call
    PerlSetVar WhateverLoginScript /

    # Or for just session management without a login script
    #PerlSetVar WhateverLoginScript NONE

    # Debugging options
    #PerlSetVar AuthCookieURLDebug 5

    # Disable cookies (only URL based sessions)
    #PerlSetVar WhateverNoCookie 1

    # Define a string that indicates to AuthCookieURL
    # what a session looks like
    # This can only be in main config
    #PerlSetVar SessionPrefix Session-

    # This block enables URL session handling
    PerlTransHandler  Apache::AuthCookieURLHandler->URLsession

    ErrorDocument 302 /MISSING
    ErrorDocument 301 /MISSING
    <Location /MISSING>
        SetHandler perl-script
        PerlHandler Apache::AuthCookieURLHandler->error_document

    <Location /protected>
        AuthType Apache::AuthCookieURLHandler
        AuthName Whatever
        PerlAuthenHandler Apache::AuthCookieURLHandler->authenticate
        PerlAuthzHandler Apache::AuthCookieURLHandler->authorize
        require valid-user

    # provide open access to some areas below
    <Location /protected/open>
        PerlSetVar DisableAuthCookieURL 1

    # or if the entire directory tree was protected
    <Location /images>
        PerlSetVar DisableAuthCookieURL 1

    # Make sure the login script can be run
         Options +ExecCGI
         SetHandler perl-script
         PerlHandler Apache::Registry

    # LOGIN is the action defined by the script

    <Files LOGIN>
         AuthType Apache::AuthCookieURLHandler
         AuthName Whatever
         SetHandler perl-script
         PerlHandler Apache::AuthCookieURLHandler->login

    # Note: If protecting the entire web site (from root down) then
    # the action *must* be C</LOGIN> as the module looks for this string.

    # better to just invalidate the session, of course
    <Files LOGOUT>
         AuthType Apache::AuthCookieURLHandler
         PerlSetVar WhateverLogoutURI /
         AuthName Whatever
         SetHandler perl-script
         PerlHandler Apache::AuthCookieURLHandler->logout


** Warning: beta software. This should be used for testing purposes only. That said, there are a few people using it and I've been using it for a few months without problem. The interface may change (or disappear) without notice. Please report any problems or comments back to Bill Moseley <>.

This module is a modification of Ken Williams <> Apache::AuthCookie. Please see perldoc Apache::AuthCookie for complete instructions. As this is intended to be a drop-in replacement for Apache::AuthCookie you may wish to install and test with Ken's Apache::AuthCookie before trying AuthCookieURL.

Basically, this module allows you to catch any unauthenticated access and redirect to a login script that you define. The login script posts credentials (e.g. username and password) and your module can then validate and provide a session key. The session key is sent in a cookie, and also in a munged URL and a redirect is issued and the process starts all over.

Typically, you will write your own module that will override methods in Apache::AuthCookieURL. These methods are described completely in Ken's Apache::AuthCookie. Your methods will be used to generate and validate session keys. You can use Apache::AuthCookieURL without overriding its methods and then AuthCookieURL can be used as a simple session manager.

With this module you should be able to enable session management for an entire site using <Location />, and then allow access to, say, the images directory, and also require password access to other locations. One issue at this point is that the session key is stripped from URLs in a Trans handler. So you would need to use cookies to use different session keys for different parts of your web tree.

Apache::AuthCookieURL adds the following features to Apache::AuthCookie.

Unless you are not subclassing this module (and using the default methods provide), your own module must define two methods: authen_cred() and authen_ses_key(), and then subclass by including Apache::AuthCookieURL in your module's @ISA array. Again, please see Apache::AuthCookie for complete documentation.


Configuration settings are set with the PerlSetVar directive:

    PerlSetVar WhateverExpires +90d

"Whatever" is whatever the current AuthName is set. I think I might remove this and instead just use the settings as Apache dir_merge returns them. In other words, if you want a setting to override a global setting, then use it within a <directory>, <file>, or <location> section.


Apache::AuthCookieURL sets some environment variables and Apache notes:

authen_ses_key() returns a value that is placed in $ENV{REMOTE_USER}. authen_ses_key() normally converts the session key into a username.

$ENV{SESSION} contains the current session key

$ENV{AuthCookieURLReason} contains the reason authentication failed. Either 'no_session_provided' or 'bad_session_provided'.

$r->notes( 'URI_Session' ) is the session extracted from the URI

$r->notes('Session_prefix') is the prefix used with the session keys, of course.

$r->notes( 'SESSION' ) is the full session, including the prefix.


URL munging has security issues. Session keys can get written to access logs, cached by browsers, leak outside your site, and are broken if your pages use absolute links to other pages on-site.


Apache::AuthCookieURL uses error documents to try to fixup any redirects. The obvious example is when a request is made for a directory without a trailing slash and Apache issues a redirect. (Actually, AuthCookieURL tries to detect this case and rewrite the URL before Apache redirects.) I wish I knew a better way to fixup Location: headers in redirects without sub-requesting every request. There's no way to catch a CGI script or module that might issue a Location: header or REDIRECT. I guess that's left for Apache 2.0 when all output can be filtered.


mod_perl 1.24, Apache::Cookie


Bill Moseley <> made minor changes to Ken Williams' <> Apache::AuthCookie.

Thanks very much to Ken for Apache::AuthCookie.


    $Revision: 1.3 $



syntax highlighting: