NAME
Gantry::Plugins::AuthCookie - Plugin for cookie based authentication
SYNOPSIS
In Apache Perl startup or app.cgi or app.server:
<Perl>
# ...
use MyApp qw{
-Engine=CGI
-TemplateEngine=TT
-PluginNamespace=your_module_name
AuthCookie
};
</Perl>
Inside MyApp.pm:
use Gantry::Plugins::AuthCookie;
sub namespace {
return 'your_module_name';
# the string is up to you, but needs to match -PluginNamespace
}
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.
You also need a namespace method in the base module. The namespace is up to you, but don't pick 'Gantry'. The namespace will be used to register callbacks for this plugin. If you don't set a namespace, all apps in the apache instance with your app will have to use the AuthCookie plugin, or they will die horrible deaths for lack of accessors, while they are being needlessly subjected to auth.
CONFIGURATION
Authentication can be turned on and off by setting 'auth_deny'. If 'on', then validation is turned on and the particular location will require that the user is authed. After the successful login the user row and the user groups ( if any ) will be set into the Gantry site object and can be retrieved using the $self->auth_user_row and $self->auth_user_groups accessors.
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
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.
- 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 'on'.
- auth_optional
-
accessor for auth_optional. User validation is active when set to 'on'.
- auth_table
-
accessor for auth_table. Tells AuthCookie the name of the user table. default is 'user'.
- 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.
- 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.
-
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.
-
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.
-
decryption routine for 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.