Cataly...impleDB(3pm)

💖 Cataly...impleDB — Catalyst::Authentication::Realm::SimpleDB 💖

okay bestie, so this is the Catalyst::Authentication::Realm::SimpleDB page, and honestly? it's giving "let me do the boring auth config for you" and we're obsessed. it lives in the User Contributed Perl Documentation corner of your manual, and it's the friend who shows up with a fully built IKEA shelf while you're still reading the instructions. 🫶

---

✨ NAME ✨

Catalyst::Authentication::Realm::SimpleDB — a simplified Catalyst authentication configurator, aka the one that does the config so you don't have to. periodt. 💅

---

🎀 SYNOPSIS 🎀

here's the whole vibe, copy-paste style:

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;

like… that's IT. look at her go. 🌸

---

🦋 DESCRIPTION 🦋

so Catalyst::Authentication::Realm::SimpleDB is literally a shortcut, no cap. it gives you a simple way to set up Catalyst Authentication when you're doing the most common thing ever: a password-protected user pulled out of an SQL database. that's the whole assignment, and she ate. ✨

---

👑 CONFIGURATION 👑

the SimpleDB Realm class configures the whole Catalyst authentication system based on these assumptions, bestie, so listen up:

• your user data lives in a table you can reach through $c->model($cfg->{user_model}) 🗂️
• your passwords are chillin' in the 'password' field of your users table, and they are not encrypted 🙈
• your roles for users live in a separate table, directly reachable through a DBIx::Class relationship called 'roles', and the actual text of the role sits in a field called 'role' inside that role table
• your user info gets stashed in the session once the user is authenticated 💾

for exactly that setup, only one config option is even necessary: 'user_model'. user_model should hold the class name of your user class. want the tea on setting up your database for this module? go peek at the "PREPARATION" section below. ⬇️

if your system is built different from the above, you might need a lil' bit of extra config. all the options are listed right here. these options match the config options used by the underlying credential and store modules — and if you want even more lore, it's in Catalyst::Authentication::Credential::Password and Catalyst::Authentication::Store::DBIx::Class. 🫶

• user_model — holds the class name (the thing you'd pass to $c->model() ) of the DBIx::Class schema you're using as the source for user info. this config item is REQUIRED. no user_model, no user, no cap. 😭
• password_field — if your password field isn't called 'password', set this option to whatever your password field is actually named. heads up though: if you rename it to, like, 'users_password', you gotta use that name in the authenticate call too:

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

• password_type — if your password isn't stored in plaintext, you gotta tell her 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 do the password hashing. 🔐
• password_hash_type — if you're using a hashed password type, this defines the type of hashing. more details on this setting live in Catalyst::Authentication::Credential::Password. 🧚
• role_column — if your user's roles are stored directly in your user table, set this to the column name that contains your roles. for example, if your user table has a field called 'permissions', then 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, plus the column that holds the role's name in plain text. see "CONFIGURATION" in Catalyst::Authentication::Store::DBIx::Class for more on these settings. 💜
• use_userdata_from_session — a simple 1 / 0 setting that decides how a user's data is saved / restored from the session. set it to 1 and the user's complete information (as it was at the moment of authentication) gets cached between requests. set it to 0 and the user's info is loaded fresh from the database on every single request. 🌈

---

🧚 PREPARATION 🧚

this module makes a few assumptions about your database structure, and honestly she's not shy about it. below is an example table structure that'll work with this module in its default configuration. use it as-is or add extra fields as needed. NOTE that this is the default SimpleDB configuration only — your table structure can look wildly different from this if you're 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! once you've loaded this table structure into your DBIx::Class schema, please please please make sure you've got a many_to_many DBIx::Class relationship defined for the users-to-roles relation. your schema files should have 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 ⭐

so like, if and when your app becomes that complex and you need more features than SimpleDB hands you, you can migrate over to a standard Catalyst Authentication configuration pretty easily. no big dramatic breakup, promise. 💔➡️💖

SimpleDB literally just creates a standard Auth config based on the inputs you give it. the config SimpleDB makes by default looks exactly 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 whole squad of other modules to do its job, so for more info you can go check out:

• Catalyst::Manual::Tutorial
• Catalyst::Plugin::Authentication
• Catalyst::Authentication::Credential::Password
• Catalyst::Authentication::Store::DBIx::Class
• Catalyst::Plugin::Authorization::Roles

---

and that's the whole page, bestie! 💜 this one came to you from perl v5.34.0, dated 2022-06-09, and the title up top was Cataly...impleDB(3pm) — yes the truncation is real and yes she's still iconic. go authenticate something. mwah. 💅✨