.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. | will give a
.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. nr % 0
. rr F
.\}
.\"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Gantry::Plugins::AuthCookie 3"
.TH Gantry::Plugins::AuthCookie 3 "2008-01-18" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
Gantry::Plugins::AuthCookie \- Plugin for cookie based authentication
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
Plugin must be included in the Applications use statment.
.PP
.Vb 8
\&
\& use MyApp qw{
\& -Engine=CGI
\& -TemplateEngine=TT
\& -PluginNamespace=your_module_name
\& AuthCookie
\& };
\&
.Ve
.PP
Bigtop:
.PP
.Vb 5
\& config {
\& engine MP20;
\& template_engine TT;
\& plugins AuthCookie;
\& ...
.Ve
.PP
There are various config options.
.PP
Apache Conf:
.PP
.Vb 4
\&
\& PerlSetVar auth_deny yes
\& PerlSetVar auth_require valid-user
\&
.Ve
.PP
Gantry Conf:
.PP
.Vb 4
\&
\& auth_deny yes
\& auth_require valid-user
\&
.Ve
.PP
Controller Config: (putting auth restictions on the method/action)
.PP
.Vb 10
\& sub controller_config {
\& my ( $self ) = @_;
\& {
\& authed_methods => [
\& { action => 'do_delete', group => '' },
\& { action => 'do_add', group => '' },
\& { action => 'do_edit', group => '' },
\& ],
\& }
\& } # END controller_config
.Ve
.PP
Controller Config via Bigtop:
.PP
.Vb 6
\& method controller_config is hashref {
\& authed_methods
\& do_delete => ``,
\& do_edit => ``,
\& do_add => ``;
\& }
.Ve
.SH "DESCRIPTION"
.IX Header "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.
.PP
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.
.SH "CONFIGURATION"
.IX Header "CONFIGURATION"
Authentication can be turned on and off by setting 'auth_deny'
or auth_optional.
.PP
.Vb 1
\& $self->auth_deny( 'yes' );
.Ve
.PP
If 'yes', then validation is turned on and the particular location will
require that the user is authed.
.PP
Just like Apache, you must define the type of auth, valid-user or group.
.PP
.Vb 1
\& $self->auth_require( 'valid-user' ); # default
.Ve
.PP
.Vb 1
\& or
.Ve
.PP
.Vb 1
\& $self->auth_require( 'group' );
.Ve
.PP
After successful login the user row, groups (if any) will be set into the
Gantry self object and can be retrieved using:
.PP
.Vb 2
\& $self->auth_user_row
\& $self->auth_user_groups
.Ve
.PP
For example, to access the username
.PP
$self\->auth_user_row\->username or whatever you have set for your
auth_user_field see \*(L"Gantry::Plugins::AuthCookie#CONFIG \s-1OPTIONS\s0\*(R"
.PP
And to access the groups
.PP
.Vb 1
\& my $groups = $self->auth_user_groups();
.Ve
.PP
.Vb 3
\& foreach my $group ( keys %{ $groups } ) {
\& print $group;
\& }
.Ve
.PP
AuthCookie assumes that you have the following tables:
.PP
.Vb 5
\& table user (
\& id int,
\& username varchar,
\& password varchar,
\& )
.Ve
.PP
.Vb 4
\& table user_group (
\& id int,
\& ident int,
\& )
.Ve
.PP
.Vb 5
\& # join table
\& table user_groups (
\& user
\& user_group
\& )
.Ve
.PP
Optionally you can modify some the table expections like so:
.PP
.Vb 3
\& $self->auth_table( 'my_usertable' );
\& $self->auth_user_field( 'myusername' );
\& $self->auth_password_field( 'mypassword' );
.Ve
.PP
.Vb 2
\& $self->auth_group_table( 'user_group' );
\& $self->auth_group_join_table( 'user_user_group' );
.Ve
.SH "CONFIG OPTIONS"
.IX Header "CONFIG OPTIONS"
.Vb 12
\& 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'
.Ve
.SH "METHODS"
.IX Header "METHODS"
.IP "do_login" 4
.IX Item "do_login"
this method provides the login form and login routines.
.IP "auth_user_row" 4
.IX Item "auth_user_row"
This is mixed into the gantry object and can be called retrieve the \s-1DBIC\s0 user
row.
.IP "auth_user_groups" 4
.IX Item "auth_user_groups"
This is mixed into the gantry object and can be called to retrieve the
defined groups for the authed user.
.IP "auth_execute_login" 4
.IX Item "auth_execute_login"
.Vb 1
\& $self->auth_execute_login( { user => 'joe', password => 'mypass' } );
.Ve
.Sp
This method can be called at anytime to log a user in.
.IP "auth_execute_logout" 4
.IX Item "auth_execute_logout"
.Vb 1
\& $self->auth_execute_logout();
.Ve
.Sp
This method can be called at anytime to log a user out.
.IP "get_callbacks" 4
.IX Item "get_callbacks"
For use by Gantry.pm. Registers the callbacks needed to auth pages
during PerlHandler Apache phase or its moral equivalent.
.SH "CONFIGURATION ACCESSORS"
.IX Header "CONFIGURATION ACCESSORS"
.IP "auth_deny" 4
.IX Item "auth_deny"
accessor for auth_deny. Turns authentication on when set to 'yes'.
.IP "auth_optional" 4
.IX Item "auth_optional"
accessor for auth_optional. User validation is active when set to 'yes'.
.IP "auth_table" 4
.IX Item "auth_table"
accessor for auth_table. Tells AuthCookie the name of the user table.
default is 'user'.
.IP "auth_group_join_table" 4
.IX Item "auth_group_join_table"
accessor for the name of the auth group to members joining table. Defaults
to 'user_groups'.
.IP "auth_group_table" 4
.IX Item "auth_group_table"
accessor for the name of the auth group table. Defaults to 'user_group'.
.IP "auth_file" 4
.IX Item "auth_file"
accessor for auth_file. Tells AuthCookie to use the Apache style htpasswd file
and where the file is located.
.IP "auth_user_field" 4
.IX Item "auth_user_field"
accessor for auth_user_field. Tells AuthCookie the name of the username field
in the user database table. Defaults to 'ident'.
.IP "auth_password_field" 4
.IX Item "auth_password_field"
accessor for auth_password_field. Tells AuthCookie the name of the password
field in the user database table.
.IP "auth_require" 4
.IX Item "auth_require"
accessor for auth_require. Tells AuthCookie the type of requirement for the
set authentication. It's either 'valid\-user' (default) or 'group'
.IP "auth_groups" 4
.IX Item "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.
.IP "auth_secret" 4
.IX Item "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.
.IP "auth_logout_url" 4
.IX Item "auth_logout_url"
accessor for auth_logout_url. auth_logout_url is a full \s-1URL\s0 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.
.IP "auth_cookie_name" 4
.IX Item "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.
.IP "auth_cookie_domain" 4
.IX Item "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.
.SH "PRIVATE SUBROUTINES"
.IX Header "PRIVATE SUBROUTINES"
.IP "auth_check" 4
.IX Item "auth_check"
callback for auth check.
.IP "checkvals" 4
.IX Item "checkvals"
check for login form.
.IP "decrypt_cookie" 4
.IX Item "decrypt_cookie"
decryption routine for cookie.
.IP "encrypt_cookie" 4
.IX Item "encrypt_cookie"
encryption routine for cookie.
.IP "initialize" 4
.IX Item "initialize"
callback to initialize plugin configuration.
.IP "login_form" 4
.IX Item "login_form"
html login form.
.IP "validate_user" 4
.IX Item "validate_user"
validation routines.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.Vb 1
\& Gantry
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
Timotheus Keefer
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (C) 2006 Timotheus Keefer
.PP
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.