NAME

Apache::AxKit::Plugin::Session - flexible session management for AxKit

SYNOPSIS

Session management only: (minimal configuration, uses cookies, won't work without cookies, in httpd.conf or .htaccess)

    AxAddPlugin Apache::AxKit::Plugin::Session

Session Management only: (uses cookies, falls back to URL session ID tracking, must be in httpd.conf)

    PerlModule Apache::AxKit::Plugin::Session;

Full-featured configuration:

    #### this must be in httpd.conf
    # want a different redirector location? (default is '/redirect')
    #<Perl>$Apache::AxKit::Plugin::Session::redirect_location = "/redir";</Perl>

    # use URL sessions
    PerlModule Apache::AxKit::Plugin::Session;

    #### the rest may go into .htaccess
    # don't use URL sessions
    #AxAddPlugin Apache::AxKit::Plugin::Session;

    # Your session manager, if not using the default "Apache::Session::File'
    #PerlModule Apache::Session::Counted

    ### Settings:
    # Prefix "AxKitSession" is set by AuthName
    # unless otherwise noted, all settings may appear
    # in main config and in directory config/.htaccess
    # how long a session is valid when idle (minutes, multiple of 5, default 30)
    #PerlSetVar AxKitSessionExpires 30

    # Cookie settings:
    #PerlSetVar AxKitSessionDomain some.domain
    #PerlSetVar AxKitSessionSecure 1

    # Disable cookies: (useful for Apache::Session::Counted, it won't currently work with cookies)
    #PerlSetVar AxKitSessionNoCookie 1

    # Location of login page: (it must call A:A:P:S->login($r) on successful login)
    #PerlSetVar AxKitSessionLoginScript /login.xsp
    # do not enforce logins (default, makes all users appear as 'guest' initially)
    #PerlSetVar AxKitSessionLoginScript NONE

    # Want a login screen when the guest privileges don't suffice?
    #ErrorDocument 403 /redirect?url=/login.xsp

    # Debugging:
    #PerlSetVar AuthCookieURLDebug 5

    # Prefix to session ID in URLs: (can only be set in main config)
    #PerlSetVar SessionPrefix Session-

    # Which session module to use: (supported are File, DB_File, Flex and (without cookies) Counted, File is default)
    #PerlSetVar AxKitSessionManager Apache::Session::File

    # Where to put session files (data and locks):
    #PerlSetVar AxKitSessionDir /tmp/sessions

    # What name the guest account shall have: (set to some false value to disable)
    #PerlSetVar AxKitSessionGuest guest

    # An arbitrary (nonexistant) session id for global data:
    # Note: This must be a valid session ID
    #PerlSetVar AxKitSessionGlobal 00000000000000000000000000000000

    # How to check IP addresses against a session:
    # 0 - not at all
    # 1 - use numeric IP address or X-Forwarded-For, if present
    # 2 - use numeric IP address with last part stripped
    # 3 - use numeric IP address
    #PerlSetVar AxKitSessionIPCheck 1

    #
    ### End of settings

    ### Directory settings
    #
    <Location /protected>
        AuthType Apache::AxKit::Plugin::Session
        AuthName AxKitSession
        PerlAuthenHandler Apache::AxKit::Plugin::Session->authenticate
        PerlAuthzHandler Apache::AxKit::Plugin::Session->authorize

        # Important: access is granted if at least one rule matches
        # allow access to any user (including 'guest' users)
        require valid-user

        # or: allow access to user JohnDoe and to user JaneDoe
        require user JohnDoe JaneDoe

        # or: allow access to members of group internal and mambers of group admin
        require group internal admin

        # or: allow access to members with level 42 or higher
        require level 42

        # or: allow access to all users except guest
        require not user guest

        # or: allow access to all users who are in group powerusers AND
        #  either longtimeusers or verylongtimeusers (compare "group" above)
        require combined group powerusers group "longtimeusers verylongtimeusers"

        # or: allow access if (group == longtimeusers AND (group == powerusers OR level >= 10))
        require combined group longtimeusers alternate "group powerusers level 10"

    </Location>


    # Directory without restrictions, but tracking sessions
    <Location />
      AuthType Apache::AxKit::Plugin::Session
      AuthName AxKitSession
      PerlFixupHandler Apache::AxKit::Plugin::Session->recognize_user
    </Location>

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

    #
    ### End of directory settings

DESCRIPTION

This module is an authentication and authorization handler for Apache, designed specifically to work with Apache::AxKit. That said, it should be generic enough to work without it as well, only much of its comfort lies in a separate XSP taglib which is distributed alongside this module.

It combines authentication and authorization in Apache::AuthCookieURL style with session management via one of the Apache::Session modules. It even works fine with Apache::Session::Counted. See those manpages for more information, but be sure to note the differences in configuration!

In addition to Apache::AuthCookieURL, you get:

session data in $r->pnotes('SESSION')
global application data in $r->pnotes('GLOBAL')
sessions without the need to login (guest account)
automatic expiration of sessions after 30 minutes (with automatic degradation to guest account, if any)
remote ip check of sessions, for a tiny bit more security
authorization based on users, groups or levels, including logical AND, OR and NOT of any requirement
$r->pnotes('INPUT','COOKIES','UPLOADS') from Apache::RequestNotes
great AxKit taglibs for retrieving, checking and changing most settings

To use authentication, you have to provide a login script which displays a login form, verifies those values and calls Apache::AxKit::Plugin::Session->login($r,$user_name) on success. This can easily be done with the PerForm XSP taglib combined with the Auth taglib. If you want logouts, you have to write a custom logout script. Both functions are provided in the Auth XSP taglib for ease of use.

Authorization via user name works by comparing the user name given at login time.

Authorization via groups and levels works by using 2 additional session variables:

$r->pnotes('SESSION')->{'auth_access_groups'} is a hash which contains an element for each group the user is in. The value associated with that key is ignored, use undef if you have no other use for that value. Nested groups have to be handled by manually adding subgroups to this hash. Access is granted if any of the given groups are present in this hash. (i.e., logical OR)
$r->pnotes('SESSION')->{'auth_access_level'} is a numeric level which must be or equal to the required level to be granted access. No value at all means 'do not grant access if any level is required'.

Multiple require lines are handled unlike in Apache::AuthCookieURL as a logical OR.

CONFIGURATION SETTINGS

Some settings apply only to one AuthName, but since settings can as well be overridden in <Directory|Location>/</Directory|Location>, there is no real need for different AuthNames. These settings are prefixed by the current AuthName.

All settings are set with PerlSetVar and may occur in any location PerlSetVar is allowed in, except SessionPrefix, which must be a global setting.

AuthCookieURLDebug, DisableAuthCookieURL, SessionPrefix, <AuthName>Cache, <AuthName>LoginScript, <AuthName>NoCookie, <AuthName>Domain, <AuthName>Secure

These settings are the same like in Apache::AuthCookieURL. Do not use any of the other settings provided by that module! They will not work as expected!
<AuthName>Expire

Sets the session expire timeout in minutes. The value must be a multiple of 5.

Example: PerlSetVar AxKitSessionExpire 30
<AuthName>Manager

Specifies the module to use for session handling. Directly supported are File, DB_File, Counted, and all DB server modules if connecting anonymously. For all other configurations (including Flex), you need <AuthName>ManagerArgs, too.

Example: PerlSetVar AxKitSessionManager Apache::Session::Counted
<AuthName>ManagerArgs

List of additional session manager parameters in the form: Name Value. Use with PerlAddVar.

Example: PerlAddVar AxKitSessionManagerArgs User foo
<AuthName>Dir

The location where all session files go, including lockfiles. If you are using a database server as session backend, this is the server specific db/table string.

Example: PerlSetVar AxKitSessionDir /home/sites/site42/data/session
<AuthName>Guest

The user name to be recognized as guest account. Setting this to a false value (the default) disables automatic guest login. If logins are used at all, this is the only way to get session management for unknown users. If no logins are used, this MUST be set to some value.

Example: PerlSetVar AxKitSessionGuest guest
<AuthName>Global

The "session" id used for global application data. This is just a simple session file and might not be very long-lasting. Real persistent application data does not belong here. But this is the right place to put "how many people are online?" counters and similar things.

Example: PerlSetVar AxKitSessionGlobal 0
<AuthName>IPCheck

The level of IP matching in sessions. A session id is only valid when the connection is coming from the same remote address. This setting lets you adjust what will be checked: 0 = nothing, 1 = numeric IP address or HTTP X-Forwarded-For header, if present, 2 = numeric IP address with last part stripped off, 3 = whole numeric IP address.

Example: PerlSetVar AxKitSessionIPCheck 3

WARNING

URL munging has security issues. Session keys can get written to access logs, cached by browsers, leak outside your site, and can be broken if your pages use absolute links to other pages on-site (but there is HTTP Referer: header tracking for this case). Keep this in mind.

The redirect handler tries to catch the case of external redirects by changing them into self-refreshing pages, thus removing a possibly sensitive http referrer header. This won't work from mod_perl, so use Apache::AuthCookieURL's fixup_redirect instead. If you are adding hyperlinks to your page, change http://www.foo.com to /redirect?url=http://www.foo.com

ADVANCED

By subclassing, you can modify the authorization scheme to your hearts desires. You can store directory and file permissions in an RDBMS and you can invent new permission types.

To store and retrieve permissions somewhere else than in httpd.conf, override 'get_permissions' and 'set_permissions'. 'get_permissions' should return a list of arrayrefs, each one containing a (type,argument-string) pair (e.g., the equivalent of a 'require group foo bar' would be ['group','foo bar']). Access is granted if one of these requirements are met. 'set_permissions' should store such a list somewhere, if dynamic modification of permissions is wanted. For more details, read the source.

For a new permission type 'foo', provide 3 subs: 'foo', 'pack_requirements_foo' and 'unpack_requirements_foo'. sub 'foo' should return OK or FORBIDDEN depending on the parameters and the session variable 'auth_access_foo'. The other two subs can be aliased to 'default_(un)pack_requirements' if your 'require foo' parses like a 'require group'. Read the source for more advanced usage.

TO DO

set cookie on changed SID; without this, Apache::Session::Counted will not work with cookies
somehow save (and restore) $r->pnotes('UPLOADS') in save_params, or maybe not (DoS)

REQUIRED

lots of stuff

AUTHOR

Jörg Walter <jwalt@cpan.org>.

VERSION

0.92

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)