Gantry::Plugins::AuthCookie(3)

NAME
Gantry::Plugins::AuthCookie - Plugin for cookie based authentication

SYNOPSIS
Plugin must be included in the Applications use statment.

    <Perl>
        use MyApp qw{
                -Engine=CGI
                -TemplateEngine=TT
                -PluginNamespace=your_module_name
                AuthCookie
        };
    </Perl>

Bigtop:

    config {
        engine MP20;
        template_engine TT;
        plugins AuthCookie;
        ...

There are various config options.

Apache Conf:

    <Location /controller>
        PerlSetVar auth_deny yes
        PerlSetVar auth_require valid-user
    </Location>

Gantry Conf:

    <GantryLocation /authcookie/sqlite/closed>
        auth_deny yes
        auth_require valid-user
    </GantryLocation>

Controller Config: (putting auth restictions on the method/action)

    sub controller_config {
        my ( $self ) = @_;
        {
            authed_methods => [
                { action => 'do_delete',  group => '' },
                { action => 'do_add',     group => '' },
                { action => 'do_edit',    group => '' },
            ],
        }
    } # END controller_config

Controller Config via Bigtop:

    method controller_config is hashref {
        authed_methods
            do_delete   => ``,
            do_edit     => ``,
            do_add      => ``;
    }

DESCRIPTION
This plugin mixes in a method that will supply the login routines and accessors that will store the authed user row and user groups.

Note that you must include AuthCookie in the list of imported items when you use your base app module (the one whose location is app_rootp). Failure to do so will cause errors.

CONFIGURATION
Authentication can be turned on and off by setting 'auth_deny' or auth_optional.

    $self->auth_deny( 'yes' );

If 'yes', then validation is turned on and the particular location will require that the user is authed.

Just like Apache, you must define the type of auth, valid-user or group.

    $self->auth_require( 'valid-user' ); # default

    or

    $self->auth_require( 'group' );

After successful login the user row, groups (if any) will be set into the Gantry self object and can be retrieved using:

    $self->auth_user_row
    $self->auth_user_groups

For example, to access the username

$self->auth_user_row->username or whatever you have set for your auth_user_field see "Gantry::Plugins::AuthCookie#CONFIG OPTIONS"

And to access the groups

    my $groups = $self->auth_user_groups();

    foreach my $group ( keys %{ $groups } ) {
        print $group;
    }

AuthCookie assumes that you have the following tables:

    table user (
        id          int,
        username    varchar,
        password    varchar,
    )

    table user_group (
        id      int,
        ident   int,
    )

    # join table
    table user_groups (
        user
        user_group
    )

Optionally you can modify some the table expections like so:

    $self->auth_table( 'my_usertable' );
    $self->auth_user_field( 'myusername' );
    $self->auth_password_field( 'mypassword' );

    $self->auth_group_table( 'user_group' );
    $self->auth_group_join_table( 'user_user_group' );

CONFIG OPTIONS
    auth_deny           'no' / 'yes'              # default 'off'
    auth_table          'user_table'              # default 'user'
    auth_file           '/path/to/htpasswd_file'  # Apache htpasswd file
    auth_user_field     'ident'                   # default 'ident'
    auth_password_field 'password'                # default 'password'
    auth_require        'valid-user' or 'group'   # default 'valid-user'
    auth_groups         'group1,group2'     # allow these groups
    auth_secret         'encryption_key'    # default 'w3s3cR7'
    auth_cookie_name    'my_auth_cookie'    # default 'auth_cookie'
    auth_cookie_domain  'www.example.com'   # default URL full domain
    auth_group_table    'user_group'
    auth_group_join_table 'user_groups'

METHODS

do_login
    this method provides the login form and login routines.

auth_user_row
    This is mixed into the gantry object and can be called retrieve the DBIC user row.

auth_user_groups
    This is mixed into the gantry object and can be called to retrieve the defined groups for the authed user.

auth_execute_login
        $self->auth_execute_login( { user => 'joe', password => 'mypass' } );

    This method can be called at anytime to log a user in.

auth_execute_logout
        $self->auth_execute_logout();

    This method can be called at anytime to log a user out.

get_callbacks
    For use by Gantry.pm. Registers the callbacks needed to auth pages during PerlHandler Apache phase or its moral equivalent.

CONFIGURATION ACCESSORS

auth_deny
    accessor for auth_deny. Turns authentication on when set to 'yes'.

auth_optional
    accessor for auth_optional. User validation is active when set to 'yes'.

auth_table
    accessor for auth_table. Tells AuthCookie the name of the user table. default is 'user'.

auth_group_join_table
    accessor for the name of the auth group to members joining table. Defaults to 'user_groups'.

auth_group_table
    accessor for the name of the auth group table. Defaults to 'user_group'.

auth_file
    accessor for auth_file. Tells AuthCookie to use the Apache style htpasswd file and where the file is located.

auth_user_field
    accessor for auth_user_field. Tells AuthCookie the name of the username field in the user database table. Defaults to 'ident'.

auth_password_field
    accessor for auth_password_field. Tells AuthCookie the name of the password field in the user database table.

auth_require
    accessor for auth_require. Tells AuthCookie the type of requirement for the set authentication. It's either 'valid-user' (default) or 'group'

auth_groups
    accessor for auth_groups. This tells AuthCookie which groups are allowed which is enforced only when auth_require is set to 'group'. You can supply multiple groups by separating them with commas.

auth_secret
    accessor for auth_secret. auth_secret is the encryption string used to encrypt the cookie. You can supply your own encryption string or just use the default the default value.

auth_logout_url
    accessor for auth_logout_url. auth_logout_url is a full URL where the user will go when they log out. Logging out happens when the do_login method is called with a query_string parameter logout=1.

auth_login_url
    accessor for auth_login_url. auth_login_url is a full/relative URL where the user will go after they login.

auth_cookie_name
    accessor for name of auth cookie. By default the cookie is called 'auth_cookie'. Import this and define a conf variable of the same name to change the cookie's name.

auth_cookie_domain
    accessor for the auth cookie's domain. By default undef is used, so the cookie will be set on the fully qualified domain of the login page. Import this method and define a conf variable of the same name to change the domain.

PRIVATE SUBROUTINES

auth_check
    callback for auth check.

checkvals
    check for login form.

decrypt_cookie
    decryption routine for cookie.

encrypt_cookie
    encryption routine for cookie.

initialize
    callback to initialize plugin configuration.

login_form
    html login form.

validate_user
    validation routines.

SEE ALSO
    Gantry

AUTHOR
Timotheus Keefer <tkeefer@gmail.com>

COPYRIGHT AND LICENSE
Copyright (C) 2006 Timotheus Keefer

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.6 or, at your option, any later version of Perl 5 you may have available.