NAME
MojoX::Authentication::Model::Role::Local
SYNOPSIS
package Some::Class;
use Moo;
with 'MojoX::Authentication::Model::Role::Local';
sub load_user_by_username ($self, $controller, $name) { ... }
...
DESCRIPTION
Role to manage local accounts, ensuring the usage of Crypt::Passphrase compatible ways of managing secrets.
This role demands that the class implements method load_user_by_username with the following signature:
sub load_user_by_username ($self, $controller, $name);
where $controller is a Mojolicious::Controller compatible class. The return value from this method MUST be a hash reference holding the secret associated to the user identified by $name in the value corresponding to key "key_for_secret" (secret by default); this value is supposed to be a valid value previously hashed with Crypt::Passphrase or anything compatible with it, or missing or empty for an account that cannot log in with a password (see "validate_user").
The key for the secret and the "protected_keys" are kept out of what reaches current_user (see "tamed_user_record") and, in classes that also compose MojoX::Authentication::Model::Role::Remap, out of reach of the remaps.
INTERFACE
crypt_passphrase
my $cp = $provider->crypt_passphrase;
Accessor for the Crypt::Passphrase object passed during construction.
handles_username
my $bool = $provider->handles_username($controller, $username);
Returns a true value if the provider knows the provided username, false otherwise. The first provider returning true owns the username (see "Owner of a username" in MojoX::Authentication::Model).
hash_secret
my $hashed = $provider->hash_secret($secret);
Wrapper for $provider->crypt_passphrase->hash_password($secret).
key_for_secret
my $key = $provider->key_for_secret;
The key holding the (hashed) secret in user records, e.g. the name of the column in a database. Defaults to secret; it can be set at construction and MUST be defined.
protected_keys
my $aref = $provider->protected_keys;
Array reference with keys holding secret material besides "key_for_secret", e.g. a seed for one-time passwords. Empty by default; it can be set at construction.
protected_keys_list
my @keys = $provider->protected_keys_list;
The list of all protected keys: "key_for_secret" first, then the "protected_keys". Used by "tamed_user_record" and by MojoX::Authentication::Model::Role::Remap.
run_fake_validation
$provider->run_fake_validation; # always throws
Check a password against a hash that was made up for the purpose, then throw the same exception as a wrong password (code 401). It makes refused logins for unknown users cost the same as real ones (see "run_fake_validation" in MojoX::Authentication::Model). The made-up hash is computed the first time it is needed.
tamed_user_record
my $safe = $provider->tamed_user_record($user);
Returns a shallow copy of $user without the keys in "protected_keys_list". See "What reaches current_user" in MojoX::Authentication::Model.
user_for_save
my $record = $provider->user_for_save($user, $is_secret_cleartext);
Prepare $user for saving: returns a shallow copy, where the value for "key_for_secret" is hashed with "hash_secret" if $is_secret_cleartext is true. A missing or empty secret is never hashed, so that it cannot turn into the hash of an empty password. Used by save_user in the classes compositing the role.
validate_user
my $uid = $provider->validate_user($controller, $name, $secret, $extra);
Validate the user identified by $name against the provided $secret. Parameter $extra is ignored and only present to support the right signature.
Returns $name if the secret is right, nothing if the provider does not know $name (so that other providers can be tried). If the provider knows $name but the secret is wrong, it throws an exception (401): the login ends there, without trying other providers.
A missing or empty secret means that the account cannot log in with a password (e.g. it logs in through SAML2 only, or it is disabled): it is refused in the same way, after a fake password check, so that response times do not tell it from an unknown username.
To disable an account, empty its secret instead of writing a marker in it (e.g. ! or *, as in /etc/shadow): Crypt::Passphrase refuses at once, without hashing anything, a hash that none of its validators accepts, so the faster answer would tell that the account exists. For the same reason, every format of the stored hashes needs a validator in "crypt_passphrase".
This method calls method load_user_by_username that must be provided by the class compositing the role.
ANYTHING ELSE (INCLUDING AUTHOR, COPYRIGHT AND LICENSE)
See documentation for MojoX::Authentication.