/ 
MojoX-Authentication-0.003
/ MojoX::Authentication::Model::SAML2

NAME

MojoX::Authentication::Model::SAML2

SYNOPSIS

use MojoX::Authentication::Model::SAML2;

DESCRIPTION

Manage the model for the interaction with an Identity Provider in SAML 2.0.

Outstanding requests are cached for some time, based on a time-to-live that can be provided (either set in the object as "ttl" or when caching a user) and defaults to 5 minutes.

INTERFACE

cache

my $cache = $provider->cache;

Accessor to the cache management object. You're not supposed to need this.

create

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

Create a new instance, according to the interface consumed by MojoX::Authentication::Model.

The merging of $config and %args is such that $config wins except for the name key, which either comes from $args{name} or defaults to saml2.

Supported keys are "cache", "idp", "name" (only from %args, see above), "remaps", "request_ttl", "sig_hash", "sp_configuration", "user_key", "user_ttl", and "username_validator".

The value for key "cache" is turned into a cache-management object with an interface like MojoX::Authentication::Model::SAML2::Hash. In particular, you can pass:

  • an object of class MojoX::MojoDbWrap, in which case class MojoX::Authentication::Model::SAML2::Db is used, passing the object as parameter wmdb

  • a blessed object, in which case it's assumed to be already a valid cache management object

  • a hash reference with instructions to instantiate a cache management object. Expected to provide a class (required) and args (optional, either as hash or array reference if present).

The value for key "idp" is turned into a Net::SAML2::IdP if not blessed (in this case it's supposed to support that interface anyway).

The value for key "remaps" is an array reference, see the accessor documentation for its format.

handles_username

my $bool = $provider->handles_username($controller, $username);

Returns a true value if the provider handles the provided username, false otherwise. Useful to figure out what provider supports a username, especially if there can be multiple SAML 2.0 providers.

idp

my $idp_object = $provider->idp;

Accessor for the Net::SAML2::IdP object (or interface-compatible).

idp_login

my ($id, $url) = $provider->idp_login;

Create a new login context, providing back its identifier and the URL to send back to the client, redirecting them to the identity provider endpoint with the correct parameters.

The login context is saved for later processing and it's set to last for "request_ttl" seconds.

load_user

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

Load a user, if present. The interface is compatible with the call done by MojoX::Authentication::Model, which in turn implements what expected by Mojolicious::Plugin::Authentication.

logout

$provider->logout($controller, $user);

Do the logout. It's currently just a thin wrapper around the logout provided by Mojolicious::Plugin::Authentication but it should be enhanced in the future to support proper remote logout.

name

my $string = $provider->name;

Accessor to the name of the provider.

parse_assertion

$provider->parse_assertion($request_id, $response);

Parse an incoming $response, arguably associated to an ongoing request with identifier $request_id. In case the parsing is successful, the user is considered logged in and saved in the case for "user_ttl" seconds.

remaps

my $aref = $provider->remaps;

Array holding the mappings applied by "normalize_user" over the passed $user hashref.

Items in the array can be:

  • code reference: the sub is called passing the user hashref to be normalized.

  • hash reference: all key/value pairs are iterated. Each key is interpreted as a key to be found in the user hashref (it is skipped if not present) and the corresponding value a target key. As an example:

    user hashref   { foo => 'hello!', bar => 'not for much...' }

mapping        { bar => 'foo' }

{ foo => 'bar' }

    looks for key foo in the user hashref and, if found, sets the same value for key bar in the same hashref.

request_ttl

my $secs = $provider->request_ttl;

Accessor for the time-to-live related to caching of request identifiers. When a request is received past this time-to-live, it is considered expired.

sig_hash

my $string = $provider->sig_hash;

Accessor for the string holding the signature hashing function to be used. Defaults to undef, which means that none will be set in "idp_login".

sp_configuration

my $cfg = $provider->sp_configuration;

Accessor for the Service Provider configuration (hash reference). It is supposed to contain the following keys:

  • identifier: the value set as the issuer in "idp_login".

  • key: the private key of the Service Provider, used to sign the redirect. It's the path to a file.

  • sso-post-url-override: the URL to pass as parameter assertion_url when building the request in "idp_login".

user_key

my $key = $provider->user_key;

Accessor to the key that is set in the user's data with the user identifier.

user_ttl

my $secs = $provider->user_ttl;

The time-to-live of the cached user when it is correctly parsed. After this, there will be the need to perform a new interaction with the Identity Provider.

username_validator

my $sub = $provider->username_validator;

Accessor for the username validation function. This is wrapped by "handles_username" behind the scenes, so it should be set to some validation mechanism that allows figuring out if the specific SAML2 Identity Provider is the right one for the username.

validate_user

my $uid = $provider->validate_user($ctr, $user, $secret, $extra);

Do the user validation, compatibly with Mojolicious::Plugin::Authentication.

wipe_user

$provider->wipe_user($user);

Remove the user from the cache.

ANYTHING ELSE (INCLUDING AUTHOR, COPYRIGHT AND LICENSE)

See documentation for MojoX::Authentication.