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.