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 the config.

  • a reference to a sub. This is supposed to act as a factory, so it will be called passing the config as the only argument and its return value will be the provider. It's acceptable for this factory to return undef and ignore the provider altogether (e.g. because there were not the right configurations in config).

  • 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 named update_from_config it will be called passing the config and 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 method create to generate an instance.

    • args: arguments to pass to the create method of the class. 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.