Mojolicious::Plugin::SAML - A simple SAML Service Provider plugin
This plugin is an early attempt at making a somewhat turn-key SAML Service Provider (SP) plugin. It is explicitly for a single SP communicating with a single Identity Provider (IdP).
In the future it is imagined that other more robust plugins might encompass more complex interactions.
Nothing about this plugin should be considered stable. Things can and will change incompatibly until this warning is removed.
my $saml = $app->plugin('SAML', \%conf);
The plugin can be configured in two ways. A hash reference of configuration options can be passed to the plugin loader. Additionally configuration will be taken from the application's configuration under the SAML toplevel key.
SAML
The two sources of configuration will be shallow merged with the application configuration taking precedence.
The following configuration keys are accepted.
The location of the IdP metadata. Passed to "from" in Mojo::SAML::Entity, it can be a url, string containing xml, or file path.
The file path location of an RSA private key.
The file path location of an X509 certificate generated by the "key".
The fully qualified url of the SAML endpoint, including protocol and host.
The name of the SP entity to be created. Defaults to the value of "location" if not specified (the common case).
A callback called when a login attempt is made. This is called after the request is verified. Note that it does not check "saml.response_success"; the callback should and handle accordingly.
$c->saml->authn_request(%options);
Generate and render an AuthnRequest based on the following key-value options
The binding that should be used for the request. Defaults to HTTP-Redirect.
HTTP-Redirect
Currently no other bindings are supported, however that is planned.
Boolean indicating if the request should be passive. Defaults to false.
A passive request checks to see if the subject is already logged in. The user is not prompted to login and they aren't shown interactive pages though they may be redirected. The response is as usual for a login attempt, though on failure, the response is not successful (see "saml.response_success" and "saml.response_status").
Boolean indicating if the request should be signed. Defaults to true (though it should and probably will default to the IdP's preference).
my $dom = $c->saml->response;
Returns the parsed (and validated) SAML response (as a Mojo:DOM object). This must only be called during the response to a SAML interaction, notably during "handle_login".
my $bool = $c->saml->response_success;
Returns a boolean indicating if the SAML response was succesful. This must only be called during the response to a SAML interaction, notably during "handle_login".
my $status = $c->saml->response_status;
Returns the string status from the SAML response. This may be useful if "saml.response_success" was false in order to differentiate the cause of the failure. This must only be called during the response to a SAML interaction, notably during "handle_login".
This plugin creates several routes all existing under the base url derived from "location". They are described below by name and path, where the base path is assumed to be /saml.
/saml
This is the primary interaction point for the IdP service.
/saml/descriptor
This url renders the Entity Metadata for the service, containing the SP descriptor that the IdP will need for configuration.
/saml/authn_request
This url generates an AuthnRequest to the IdP via "saml.authn_request" helper called without options (ie, using the default options).
The plugin implements the following attributes.
my $doc = $saml->metadata;
Stores the generated metadata, an instance of Mojo::SAML::Document::EntityDescriptor. This can be modified before the first time is is served by "saml_descriptor". This is especially useful for injecting requested attributes.
Currently the plugin is designed to generate the SP metadata. Setting the metadata from an XML file is planned but not yet implemented. Setting this attribute is not recommended.
my $r = $saml->route;
This holds the Mojolicious::Routes::Route object that is the top-level of the tree of "ROUTES". The reference is weakened when initially stored.
This attribute is intended for interrogating and possibly modifying the route object itself. Setting this attribute will not be very useful.
my $saml = $app->plugin('SAML');
The method called when the plugin is loaded by the application. Returns the plugin instance itself.
Note that this is useful to change definitions before the application has begun serving requests. Once the application has begun to serve requests, changes to this object or its data are not recommended and the behavior in that case will be undefined.
my $doc = $saml->sp_metadata;
Returns the generated metadata for the SP, an instance of Mojo::SAML::Document::SPSSODescriptor. This reference is also available from "metadata" but this is more convenient.
Note that the implementation of this method is still undetermined. Specifically don't rely on what would happen if you replace this element from the "metadata".
To install Mojo::SAML, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Mojo::SAML
CPAN shell
perl -MCPAN -e shell install Mojo::SAML
For more information on module installation, please visit the detailed CPAN module installation guide.