NAME

MojoX::Authentication::Model::Hash

SYNOPSIS

use MojoX::Authentication::Model::Hash;

DESCRIPTION

This class is not supposed to be used directly but through MojoX::Authentication::Model instead.

This class composes role MojoX::Authentication::Model::Role::Local and inherits its methods.

INTERFACE

create

my $instance = MojoX::Authentication::Model::Hash->create(
   $config, %args);

Constructor.

Can receive the configuration either from a more "generic" $config hash as well as direct named arguments.

First a name is determined, either from $args{name} or hashy by default. Then $config is looked at for a corresponding value, which is either expected to be missing/undef or be a hash reference. In case a hash reference is found, its pairs override those on %args, with the only exception of the key name which is preserved if already present or set to the default otherwise.

Argument db is mandatory (an exception is thrown otherwise) and holds the accounts, in one of the following forms:

  • a hash reference, whose keys are the usernames and whose values are hash references with the accounts' data;

  • an array reference of hash references with the accounts' data, each MUST contain key username;

  • a string holding JSON text for the array reference above (it MUST start with [, possibly preceded by spaces);

  • a path to a file holding JSON text for either of the two references above.

The accounts' data hold the secret under its key (secret, unless set otherwise with key_for_secret); an account without it (or with an empty one) cannot log in with a password (see "validate_user" in MojoX::Authentication::Model::Role::Local). Any other key/value pair is kept as-is. Key username is always set to the account's username.

The input data is copied and never modified: it is safe to use the same data for multiple instances. An exception is thrown if an account in an array lacks the username, or if db is a reference of any other type.

Also accepts parameters name (from %args only see above), secrets_are_cleartext, key_for_secret, protected_keys (see MojoX::Authentication::Model::Role::Local) and crypt_passphrase. The latter can be either a Crypt::Passphrase instance or arguments to instantiate one (an Crypt::Passphrase::Argon2 encoder is used by default).

When secrets_are_cleartext is set to a true value, the secret in each account is assumed to be in cleartext and is hashed when the instance is created. This is only meant for development and testing, as it implies that cleartext passwords are kept somewhere.

db

my $db_hash = $provider->db;

Accessor to the hash holding the accounts database, keyed by username. Take extreme care when fiddling directly with its value.

load_user

my $user = $provider->load_user($ignored, $uid);

Load the user by its userid, compatibly with Mojolicious::Plugin::Authentication's interface for loading users. The first parameter (which is supposed to be a controller instance) is ignored.

This class has no distinction between user identifiers and usernames. Returns a (shallow) copy of the account's data, or nothing if the account is not present.

load_user_by_username

my $user = $provider->load_user_by_username($ignored, $username);

Alias for "load_user", as this class has no distinction between user identifiers and usernames.

name

my $name = $provider->name;
$provider->name($new_name);

Name assigned to the provider (e.g. if you want to use different databases at the same time and hence want to instantiate this class multiple times). It is read-write: MojoX::Authentication::Model sets it to the name it registers the provider under (see "Provider names" in MojoX::Authentication::Model).

save_user

$provider->save_user($user);    # OR
$provider->save_user($user, $is_secret_cleartext);

Save a user.

The input $user is supposed to be a hash reference with at least key username (for the username/userid) and, for an account that logs in with a password, the key for the secret (secret by default, see key_for_secret). It MAY contain other key/value pairs, which will be copied. A user with the same username is replaced.

A user returned by "load_user" can be modified and passed to this method to save the changes.

The secret is supposed to be already hashed. It is possible to set the optional additional parameter $is_secret_cleartext to a true value to indicate that the hashing should be done by the function before saving the user.

ANYTHING ELSE (INCLUDING AUTHOR, COPYRIGHT AND LICENSE)

See documentation for MojoX::Authentication.