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
wmdba 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) andargs(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_optsfor "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
$responseor 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
Issueris not theentityIDin 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
identifierin "sp_configuration" and$request_id(code 400);the assertion has no
NameID, or an empty one (code 400): theNameIDis 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 theissuerin "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 parameterassertion_urlwhen 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.