Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Contact Us
Online Help
Domain Status
Man Pages

Virtual Servers

Topology Map

Server Agreement
Year 2038

USA Flag



Man Pages

Manual Reference Pages  -  GANTRY::PLUGINS::AUTHCOOKIE (3)

.ds Aq ’


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



Plugin must be included in the Applications use statment.

        use MyApp qw{


    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

Gantry Conf:

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

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 {
            do_delete   => ``,
            do_edit     => ``,
            do_add      => ``;


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.


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


    $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:


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 (

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 );


    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   # default URL full domain
    auth_group_table    user_group
    auth_group_join_table user_groups


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.

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

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



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

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


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.
auth_ldap Accessor method for auth_ldap. Tells AuthCookie to use ldap for auth.
auth_ldap_binddn Accessor method for auth_ldap_binddn. The bind dn is the user that is allowed to search the directory.
auth_ldap_filter Accessor method for auth_ldap_filter. The ldap search filter is used to map the username to the ldap directory attribute used to select the desired entry.
auth_ldap_groupdn Accessor method for auth_ldap_groupdn. Used to set the base for searching for user groups in the directory.
auth_ldap_hostname Accessor method for auth_ldap_hostname. This is the hostname of the ldap server.
auth_ldap_userdn Accessor method for auth_ldap_userdn. Not currently used.


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.




Timotheus Keefer <>


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.

Search for    or go to Top of page |  Section 3 |  Main Index

perl v5.20.3 GANTRY::PLUGINS::AUTHCOOKIE (3) 2016-04-03

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.