/ 
RapidApp-1.3500
River stage one • 5 direct dependents • 5 total dependents
/ Catalyst::Plugin::RapidApp::AuthCore

NAME

Catalyst::Plugin::RapidApp::AuthCore - instant authentication, authorization and sessions

SYNOPSIS

package MyApp;

use Catalyst   qw/ RapidApp::AuthCore /;

DESCRIPTION

This plugin provides a full suite of standard users and sessions with authentication and authorization for Catalyst/RapidApp applications.

It loads and auto-configures a bundle of standard Catalyst plugins:

Authentication
Authorization::Roles
Session
Session::State::Cookie
Session::Store::DBIC

As well as the RapidApp::CoreSchema plugin, which sets up the backend model/store.

The common DBIC-based Catalyst::Model::RapidApp::CoreSchema database is used for the store and persistence of all data, which is automatically deployed as an SQLite database on first load.

New databases are automatically setup with one user:

username: admin
password: pass

An administrator role is also automatically setup, which the admin user belongs to.

For managing users and roles, seeing active sessions, etc, see the CoreSchemaAdmin plugin.

AUTH CONTROLLER

The AuthCore plugin automatically injects an Auth controller at /auth in the Catalyst application. This controller implements a login (/auth/login) and logout (/auth/logout) action.

The /auth/login action path handles both the rendering a login form (when accessed via GET) and the actual login/authentication (when accessed via POST). The login POST should send these params:

  • username

  • password

  • redirect (optional)

A redirect URL can be supplied for the client to redirect to after successful login. The redirect param can also be supplied to a GET/POST to /auth/logout to redirect after logout.

The login form is also internally rendered from other URL paths which are password-protected (which by default is all Module paths when AuthCore is loaded). The built-in login form template automatically detects this case and sends the path in redirect with the login POST. This allows RESTful paths to be accessed and automatically authenticate, if needed, and then continue on to the desired location thereafter.

CONFIG

Custom options can be set within the 'Plugin::RapidApp::AuthCore' config key in the main Catalyst application config. All configuration params are optional.

init_admin_password

Default password to assign to the admin user when initializing a fresh CoreSchema database for the first time. Defaults to

pass

passphrase_class

Authen::Passphrase class to use for password hashing. Defaults to 'BlowfishCrypt'. The Authen::Passphrase interface is implemented using the DBIx::Class::PassphraseColumn component class in the CoreSchema database.

passphrase_params

Params supplied to the passphrase_class above. Defaults to:

{
  cost        => 9,
  salt_random => 1,
}

expires

Set the timeout for Session expiration. Defaults to 3600 (1 hour)

role_checker

Optional CodeRef used to check user roles. By default, this is just a pass-through to the standard check_user_roles() function. When AuthCore is active, Modules which are configured with the require_role param will call the role_checker to verify the current user is allowed before rendering. This provides a very simple API for permissions and authorization. More complex authorization rules simply need to be implemented in code.

The require_role API is utilized by the CoreSchemaAdmin plugin to restrict access to the CoreSchema database to users with the administrator role (which will both hide the menu point and block module paths to non-administrator users).

Note that the role_checker is only called by AuthCore-aware code (Modules or custom user-code), and doesn't modify the behavior of the standard role methods setup by Catalyst::Plugin::Authorization::Roles which is automatically loaded by AuthCore. You can still call check_user_roles() in your custom controller code which will function in the normal manner (which performs lookups against the Role tables in the CoreSchema) regardless of the custom role_checker.

OVERRIDE CONFIGS

If any of the following configs are supplied, they will completely bypass and override the config settings above.

no_validate_passwords

Special temp/admin bool option which when set to a true value will make any supplied password successfully authenticate for any user. This is useful if you forget the admin password, so you don't have to either manually edit the rapidapp_coreschema.db database, or delete it to have it recreated. The setting can also be used if the passphrase settings are changed (which will break all pre-existing passwords already in the database) to be able to get back into the app, if needed.

Obviously, this setting would never be used in production.

credential

To override the credential param supplied to Plugin::Authentication

store

To override the store param supplied to Plugin::Authentication

Plugin::Authentication

To completely override the Plugin::Authentication config.

Plugin::Session

To completely override the Plugin::Session config.

SEE ALSO

AUTHOR

Henry Van Styn <vanstyn@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2013 by IntelliTree Solutions llc.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.