NAME

       Catalyst::Authentication::Realm::SimpleDB - A simplified Catalyst authentication
       configurator.

SYNOPSIS

           use Catalyst qw/
               Authentication
           /;

           __PACKAGE__->config->{'Plugin::Authentication'} =
               {
                   default => {
                       class      => 'SimpleDB',
                       user_model => 'MyApp::Schema::Users',
                   }
               }

           # later on ...
           $c->authenticate({ username => 'myusername',
                              password => 'mypassword' });

           my $age = $c->user->get('age');

           $c->logout;

DESCRIPTION

       The Catalyst::Authentication::Realm::SimpleDB provides a simple way to configure Catalyst
       Authentication when using the most common configuration of a password protected user
       retrieved from an SQL database.

CONFIGURATION

       The SimpleDB Realm class configures the Catalyst authentication system based on the
       following:

       •   Your user data is stored in a table that is accessible via
           $c->model($cfg->{user_model});

       •   Your passwords are stored in the 'password' field in your users table and are not
           encrypted.

       •   Your roles for users are stored in a separate table and are directly accessible via a
           DBIx::Class relationship called 'roles' and the text of the role is stored in a field
           called 'role' within the role table.

       •   Your user information is stored in the session once the user is authenticated.

       For the above usage, only one configuration option is necessary, 'user_model'.  user_model
       should contain the class name of your user class. See the "PREPARATION" section for info
       on how to set up your database for use with this module.

       If your system differs from the above, some minor configuration may be necessary. The
       options available are detailed below. These options match the configuration options used
       by the underlying credential and store modules.  More information on these options can be
       found in Catalyst::Authentication::Credential::Password and
       Catalyst::Authentication::Store::DBIx::Class.

       user_model
           Contains the class name (as passed to $c->model() ) of the DBIx::Class schema to use
           as the source for user information.  This config item is REQUIRED.

       password_field
           If your password field is not 'password' set this option to the name of your password
           field.  Note that if you change this to, say 'users_password' you will need to use
           that in the authenticate call:

               $c->authenticate({ username => 'bob', users_password => 'foo' });

       password_type
           If the password is not stored in plaintext you will need to define what format the
           password is in.  The common options are crypted and hashed.  Crypted uses the standard
           unix crypt to encrypt the password.  Hashed uses the Digest modules to perform
           password hashing.

       password_hash_type
           If you use a hashed password type - this defines the type of hashing. See
           Catalyst::Authentication::Credential::Password for more details on this setting.

       role_column
           If your users roles are stored directly in your user table, set this to the column
           name that contains your roles.  For example, if your user table contains a field
           called 'permissions', the value of role_column would be 'permissions'.  NOTE: If
           multiple values are stored in the role column, they should be space or pipe delimited.

       role_relation and role_field
           These define an alternate role relationship name and the column that holds the role's
           name in plain text.  See "CONFIGURATION" in
           Catalyst::Authentication::Store::DBIx::Class for more details on these settings.

       use_userdata_from_session
           This is a simple 1 / 0 setting which determines how a user's data is saved / restored
           from the session.  If it is set to 1, the user's complete information (at the time of
           authentication) is cached between requests.  If it is set to 0, the users information
           is loaded from the database on each request.

PREPARATION

       This module makes several assumptions about the structure of your database.  Below is an
       example of a table structure which will function with this module in it's default
       configuration. You can use this table structure as-is or add additional fields as
       necessary. NOTE that this is the default SimpleDB configuration only. Your table structure
       can differ significantly from this when using the DBIx::Class Store directly.

           --
           -- note that you can add any additional columns you require to the users table.
           --
           CREATE TABLE users (
                   id            INTEGER PRIMARY KEY,
                   username      TEXT,
                   password      TEXT,
           );

           CREATE TABLE roles (
                   id   INTEGER PRIMARY KEY,
                   role TEXT
           );
           CREATE TABLE user_roles (
                   user_id INTEGER,
                   role_id INTEGER,
                   PRIMARY KEY (user_id, role_id)
           );

       Also, after you have loaded this table structure into your DBIx::Class schema, please be
       sure that you have a many_to_many DBIx::Class relationship defined for the users to roles
       relation. Your schema files should contain something along these lines:

       "lib/MyApp/Schema/Users.pm":

           __PACKAGE__->has_many(map_user_role => 'MyApp::Schema::UserRoles', 'user_id');
           __PACKAGE__->many_to_many(roles => 'map_user_role', 'role');

       "lib/MyApp/Schema/UserRoles.pm":

           __PACKAGE__->belongs_to(role => 'MyApp::Schema::Roles', 'role_id');

MIGRATION

       If and when your application becomes complex enough that you need more features than
       SimpleDB gives you access to, you can migrate to a standard Catalyst Authentication
       configuration fairly easily.  SimpleDB simply creates a standard Auth config based on the
       inputs you give it.  The config SimpleDB creates by default looks like this:

           MyApp->config('Plugin::Authentication') = {
               default => {
                   credential => {
                       class => 'Password',
                       password_type => 'clear'
                   },
                   store => {
                       class => 'DBIx::Class',
                       role_relation => 'roles',
                       role_field => 'role',
                       use_userdata_from_session => '1',
                       user_model => $user_model_from_simpledb_config
                       }
                   }
           };

SEE ALSO

       This module relies on a number of other modules to do it's job.  For more information you
       can refer to the following:

       •   Catalyst::Manual::Tutorial

       •   Catalyst::Plugin::Authentication

       •   Catalyst::Authentication::Credential::Password

       •   Catalyst::Authentication::Store::DBIx::Class

       •   Catalyst::Plugin::Authorization::Roles

perl v5.26.1                                2018-01Catalyst::Authentication::Realm::SimpleDB(3pm)