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 "request_ttl" seconds (30 by default), users parsed from a valid response for "user_ttl" seconds (5 minutes by default).

INTERFACE

cache

my $cache = $provider->cache;

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

Every key the provider uses in the cache starts with its encoded "name" (see "encode_name" in MojoX::Authentication::Util), so several SAML2 providers can share one cache (e.g. the same table) without seeing each other's requests or users.

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).

If no "cache" is given, MojoX::Authentication::Model::SAML2::Hash is used. It keeps everything in the memory of the process, so it only works when the application runs as a single process (e.g. with morbo or the daemon command). With more than one process (e.g. hypnotoad or the prefork command), a login request stored by one worker is unknown to the worker receiving the response from the Identity Provider, and a user logged in by one worker is unknown to the others: logins fail at random and users appear logged out. In this case pass a MojoX::MojoDbWrap object (or any cache shared among the processes) instead.

The value for key "idp" is the identity provider's metadata, in one of these forms:

  • an object, used as-is: it is supposed to be a Net::SAML2::IdP or to support the same interface. Build it yourself when you need control over how the metadata is fetched (e.g. ssl_opts for "new_from_url" in Net::SAML2::IdP);

  • a URL (anything starting with scheme://), fetched with "new_from_url" in Net::SAML2::IdP. Note that this uses LWP::UserAgent with its default settings, including its User-Agent string, which some sites refuse;

  • a string with the XML metadata itself, recognized by starting with < (possibly after some whitespace);

  • anything else is taken as the path to a file holding the XML metadata. An exception is thrown if it cannot be read.

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 claims the provided username, false otherwise, by calling "username_validator". With default settings it claims every username (see "username_validator").

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. The $user is what MojoX::Authentication::Model provides as the current user (a hash reference with the user identifier in key uid): the user is removed from the cache, then the logout provided by Mojolicious::Plugin::Authentication is called.

It should be enhanced in the future to support proper remote logout.

name

my $string = $provider->name;
$provider->name($new_name);

Accessor to the name of the provider, which also scopes the keys in the "cache". It is read-write: MojoX::Authentication::Model sets it to the name it registers the provider under (see "Provider names" in MojoX::Authentication::Model), so that two SAML2 providers sharing a cache never share its entries.

parse_assertion

my $user = $provider->parse_assertion($request_id, $response);

Parse an incoming $response (the base64-encoded SAMLResponse as posted by the client), arguably associated to an ongoing request with identifier $request_id. In case the parsing is successful, the user is considered logged in, saved in the cache for "user_ttl" seconds and returned (after applying "remaps").

The request identifier can be used only once: it is removed from the cache as soon as a response for it is processed, whatever the outcome, so the same response cannot be replayed.

Exceptions are thrown when any of the following happen; they are Ouch exceptions where a code is indicated, plain ones coming from Net::SAML2 otherwise:

  • there is no $response or no $request_id, or the request is unknown (never issued, already used) or older than "request_ttl" seconds (code 400);

  • the signature of the response cannot be verified against the identity provider's signing certificate;

  • the identity provider answered with a status other than success, e.g. because the user could not be authenticated (code 403). The message names the status and, if present, the sub-status, e.g. IdP refused with urn:oasis:names:tc:SAML:2.0:status:Responder/urn:oasis:names:tc:SAML:2.0:status:AuthnFailed;

  • the assertion was issued by somebody other than the identity provider, i.e. its Issuer is not the entityID in the metadata of "idp", even if signed with the right key (as when several issuers share one signing key, e.g. the tenants of a multi-tenant platform);

  • the assertion is not valid for this service provider, i.e. for the identifier in "sp_configuration" and $request_id (code 400);

  • the assertion has no NameID, or an empty one (code 400): the NameID is the user identifier, so it is required. Nothing is cached in this case.

remaps

my $aref = $provider->remaps;

Array holding the mappings applied over the user's data, when it is extracted from the response in "parse_assertion". Their format is the one of "remap" in MojoX::Authentication::Model::Role::Remap (code, array or hash references), applied forward only.

The default copies the givenname and surname claims (http://schemas.xmlsoap.org/ws/2005/05/identity/claims/...) to keys givenname and surname, joining multiple values with , , then sets fullname to the two joined by a space.

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".

tamed_user_record

my $safe = $provider->tamed_user_record($user);

Returns $user as it is: records built from SAML2 assertions hold no secret material (see "What reaches current_user" in MojoX::Authentication::Model). If the IdP sends attributes that must not reach current_user, override this method in a subclass.

user_key

my $key = $provider->user_key;

Accessor to the key that is set in the user's data with the user identifier. It is also used to find the user identifier when caching users. Defaults to key.

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, e.g.:

username_validator => sub ($name) { $name =~ m{\@example\.com\z}mxs },

The default validator accepts every username. As the first provider claiming a username owns it (see "Owner of a username" in MojoX::Authentication::Model), a SAML2 provider with the default validator shadows all the providers after it: put it last, or set a validator. A SAML2 provider never accepts credentials, so a login with username and password for a username it owns is always refused.

wipe_user

$provider->wipe_user($uid);   # OR
$provider->wipe_user($user);

Remove the user from the cache. The input can be the user identifier, or a hash reference holding it in key "user_key".

ANYTHING ELSE (INCLUDING AUTHOR, COPYRIGHT AND LICENSE)

See documentation for MojoX::Authentication.