NAME
MojoX::Authentication::Model
SYNOPSIS
use MojoX::Authentication::Model;
my $am = MojoX::Authentication::Model->new(
config => {}, # might contain stuff useful for specific providers
providers => [
{
class => 'MojoX::Authentication::Model::Hash',
name => 'memory-hash', # override default in class
args => {
db => [
{ username => foo => secret => 12345 },
{ username => bar => secret => 67890 },
],
secrets_are_cleartext => 1,
}
},
{
class => 'MojoX::Authentication::Model::Db',
name => 'local-db',
args => {
wmdb => $wmdb, # MojoX::MojoDbWrap compatible
},
},
{
class => 'MojoX::Authentication::Model::SAML2',
name => 'external-idp',
args => { ... },
},
],
);
my $provider = $am->provider_named('local-db');
# mostly used with Mojolicious::Plugin::Authentication
$app->plugin(Authentication => {
...
load_user => sub (@args) { $am->load_user(@args) },
validate_user => sub (@args) { $am->validate_user(@args) },
});
DESCRIPTION
This module provides a model that acts as an entry point for several competing <identity providers> of different nature.
As an example, you might want to support holding users in a hash (possibly configured in a development environment) as well as in a database or externally in a SAML 2.0 identity provider. This module lets you set all of them in order of priority: for each username, the first provider that claims it (see "Owner of a username") owns it, and is the only one asked to validate credentials for it.
Let's take the example in the "SYNOPSIS" and change it a bit:
my $development_users = [
{ username => foo => secret => '12345' },
{ username => bar => secret => '67890' },
];
my $am = MojoX::Authentication::Model->new(
config => {}, # might contain stuff useful for specific providers
providers => [
{
class => 'MojoX::Authentication::Model::Hash',
name => 'memory-hash', # override default in class
args => {
db => ( $ENV{DEVEL} ? $development_users : [] ),
secrets_are_cleartext => 1,
},
},
{
class => 'MojoX::Authentication::Model::Db',
name => 'local-db',
args => {
wmdb => $wmdb, # MojoX::MojoDbWrap compatible
},
},
{
class => 'MojoX::Authentication::Model::SAML2',
name => 'external-idp',
args => { ... },
},
],
);
$app->plugin(Authentication => {
...
load_user => sub (@args) { $am->load_user(@args) },
validate_user => sub (@args) { $am->validate_user(@args) },
});
The constructor for this module is fed with three providers.
The first one takes a definition from a reference with hardcoded values and cleartext passwords, which is of course NOT secure at all. Anyway, we only use $development_users if the environment variable DEVEL is true, otherwise it's the empty array to win. This means that in the development environment we get users foo and bar with their simple password, while elsewhere we don't get them (at least not from the hash).
The second provider uses a local database, possibly based on SQLite or Postgresql. This is probably the way to go for handling users locally in a robust manner.
The third provider lets us plug into an external identity provider using SAML 2.0. It is set as the last option so that we can override it in case of need (e.g. if we decide to handle a user locally instead, or even with the hash in case we are in development). This is also the only sensible place for a SAML2 provider with default settings: it claims every username, so if it came first it would shadow all the providers after it (see "username_validator" in MojoX::Authentication::Model::SAML2).
The final goal is simple: code the Mojolicious application with the sequence of providers that are anticipated and supported, allowing for deployment-specific customizations.
INTERFACE
The interface of this module can be divided into two parts:
methods that deal with the object itself, e.g. the constructor;
methods that dispatch requests to the providers, either to the owner of a username or to the provider recorded in a user identifier.
Methods for the object
config
my $config = $am->config;
Accessor to the config set during construction. It's supposed to hold a hash reference with configurations that apply to specific providers, by name.
new
my $am = MojoX::Authentication::Model->new(%args); # OR
my $am = MojoX::Authentication::Model->new(\%args);
Create a new instance of the class.
Supported arguments:
"config": a hash reference holding any configuration that might be useful for the providers. Depending on the provider, it will be exposed to them so that they will be able to grab the needed values, if any.
providers: an array reference holding a list of providers. These are supposed to be sorted in the way they will be tried later, so put them in order of priority.
Each provider in providers can be:
a blessed object. This is supposed to be the provider that supports the needed interface, partially or completely. If it supports method
update_from_config, it will be called passing theconfig.a reference to a sub. This is supposed to act as a factory, so it will be called passing the
configas the only argument and its return value will be the provider. It's acceptable for this factory to returnundefand ignore the provider altogether (e.g. because there were not the right configurations inconfig).a reference to a hash. This is supposed to include instructions for getting a provider instance and the following keys are supported:
name: the name of the provider. If present, it overrides any name that might be set in the provider instance itself, and it is written into the instance (see "Provider names").instance: the instance as an already formed object. This is taken at face value. If it has a method namedupdate_from_configit will be called passing theconfigand this hash reference, so that the instance can pick parameters meant for it alone:$instance->update_from_config($config, $hash_ref);The name is written into the instance afterwards anyway (see "Provider names").
When this key is present, other keys might be ignored (e.g.
class).class: the name of the class that supports a methodcreateto generate an instance.args: arguments to pass to thecreatemethod of theclass. It is not mandatory; if present, it can be either an array reference or a hash reference.
Provider names
Every provider ends up with a name: the name key of the hash form if present, else the provider's own name, else unnamed-0, unnamed-1 and so on. This is the name sessions carry (see "User identifiers") and the one "provider_named" answers to.
The Model is the authority on it: it writes this name into every provider that has a name method, calling $provider->name($name), so that a provider scoping anything by its own name (e.g. MojoX::Authentication::Model::SAML2 cache keys) uses the same one. Hence, a provider with a name method must accept being renamed (e.g. is => 'rw' with Moo): if the call dies, or the provider keeps answering another name afterwards, the construction of the Model fails with a 400 exception. For the same reason, the same instance cannot be given twice (it would answer to the last name only): this is a 400 exception too. Two providers with the same name are a 400 exception as well. Sharing one instance between two Models is not supported either, although nothing checks it: the last Model to set its name wins.
A provider without a name method only has a name in the Model, so it must not scope anything by name on its own.
provider_named
my $provider = $am->provider_named($name);
Get the provider associated to $name, if any.
Methods for the providers
Owner of a username
Every provider MUST implement handles_username:
my $bool = $provider->handles_username($controller, $username);
The owner of a username is the first provider, in the order they were passed upon construction, whose handles_username returns a true value. The order is entirely up to the consumer and it is preserved: put first the providers that should win. A provider that claims every username (like a SAML2 provider with default settings) shadows all the providers after it.
"validate_user" asks only the owner, so a wrong password ends the login: other providers with the same username do not get a chance. "load_user" asks only the provider that authenticated the user, which is recorded in the user identifier kept in the session (see "User identifiers").
All refused logins look the same from the outside: an unknown username, a wrong password, an account without a password (see "validate_user" in MojoX::Authentication::Model::Role::Local) and a username whose owner does not accept credentials (e.g. a SAML2 provider) all end with the same exception (code 401), after the same amount of work (one password check, see "run_fake_validation"). This avoids telling which usernames exist, by message or by timing.
What reaches current_user
Every provider that implements load_user MUST also implement tamed_user_record:
my $safe = $provider->tamed_user_record($user);
It receives the hash reference returned by the provider's load_user and returns a hash reference with what can be exposed: this is what becomes data in "load_user", hence in current_user, the stash, templates, JSON and logs. A provider that keeps secret material in its records (password hashes, tokens, seeds...) MUST leave it out; one that keeps none can return $user as it is (like MojoX::Authentication::Model::SAML2). Providers built on MojoX::Authentication::Model::Role::Local get it from the role.
A provider with load_user and without tamed_user_record is a configuration error: an exception (code 400) is thrown when the providers are set up.
The result is deep-copied (with "dclone" in Storable), so that changing current_user never changes what the provider keeps. For this reason, user records MUST be plain data: no code references, file handles and the like.
load_user
my $user = $am->load_user($app, $euid);
Load the user's data from the provider named in $euid, which is the identifier returned by "validate_user" (see "User identifiers").
Returns a hash reference with keys provider (the name of the provider), uid (the identifier within the provider) and data (a deep copy of what the provider's tamed_user_record returned, see "What reaches current_user"). To get the full record, e.g. to save it back, call load_user on the provider itself.
Returns nothing if $euid is malformed, names a provider that is not configured or a user that the provider does not know. In these cases, Mojolicious::Plugin::Authentication considers the user as not authenticated.
Throws an exception if the provider has no load_user method, or if it returns something that is not a hash reference: both are configuration errors.
The interface is compatible with Mojolicious::Plugin::Authentication like this:
my $am = ...;
$app->plugin(Authentication => {
...
load_user => sub (@args) { $am->load_user(@args) },
});
provider_name_for
my $name = $am->provider_name_for($controller, $username);
Retrieve the name of the owner of $username (see "Owner of a username"), or undef if no provider claims it.
provider_for
my $provider = $am->provider_for($controller, $username);
my ($name, $provider) = $am->provider_for($controller, $username);
Retrieve the owner of $username (see "Owner of a username"). In scalar context, returns the provider object (or undef if no provider claims $username); in list context, returns its name and the provider object (or an empty list).
run_fake_validation
$am->run_fake_validation; # always throws
Make a refused login cost the same as checking a real password, then throw the same exception as a wrong password (code 401). The fake check is delegated to the first provider supporting run_fake_validation (e.g. those composing MojoX::Authentication::Model::Role::Local); if there is none, the exception is thrown right away. Used by "validate_user" when no provider claims the username, or when its owner does not support validate_user.
validate_user
my $euid = $am->validate_user($controller, $username, $secret, $extra);
Perform validation of credentials for $username.
Only the owner of $username is asked (see "Owner of a username"). Returns the user identifier as built by "euid_join", i.e. the name of the owner and the identifier it returned. Throws an exception (code 401) if the login is refused: the owner refuses the credentials, no provider claims $username or the owner does not support validate_user. Exceptions from the owner are not caught.
The interface is compatible with Mojolicious::Plugin::Authentication like this:
my $am = ...;
$app->plugin(Authentication => {
...
validate_user => sub (@args) { $am->validate_user(@args) },
});
User identifiers
The identifier kept in the session (and returned by "validate_user") is the name of the provider, followed by a slash /, followed by the identifier of the user within the provider. The provider name is encoded (see "encode_name" in MojoX::Authentication::Util) so that it never contains a slash: the first slash is always the separator and the user identifier can contain anything. For SAML2, the same form must be passed in auto_validate.
euid_join
my $euid = $am->euid_join($provider_name, $uid);
Build a user identifier from the provider name and the user identifier within the provider.
euid_split
my ($provider_name, $uid) = $am->euid_split($euid);
Reverse of "euid_join". Returns nothing (an empty list) if $euid has no slash.
ANYTHING ELSE (INCLUDING AUTHOR, COPYRIGHT AND LICENSE)
See documentation for MojoX::Authentication.