/ 
Mojo-SAML-0.07
River stage zero No dependents
/ Mojolicious::Plugin::SAML

NAME

Mojolicious::Plugin::SAML - A simple SAML Service Provider plugin

SYNOPSIS

DESCRIPTION

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.

CAVEATS

Nothing about this plugin should be considered stable. Things can and will change incompatibly until this warning is removed.

CONFIGURATION

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.

The two sources of configuration will be shallow merged with the application configuration taking precedence.

The following configuration keys are accepted.

idp

The location of the IdP metadata. Passed to "from" in Mojo::SAML::Entity, it can be a url, string containing xml, or file path.

key

The file path location of an RSA private key.

cert

The file path location of an X509 certificate generated by the "key".

location

The fully qualified url of the SAML endpoint, including protocol and host.

entity_id

The name of the SP entity to be created. Defaults to the value of "location" if not specified (the common case).

handle_login

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.

HELPERS

saml.authn_request

$c->saml->authn_request(%options);

Generate and render an AuthnRequest based on the following key-value options

binding

The binding that should be used for the request. Defaults to HTTP-Redirect.

Currently no other bindings are supported, however that is planned.

passive

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

sign

Boolean indicating if the request should be signed. Defaults to true (though it should and probably will default to the IdP's preference).

saml.response

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

saml.response_success

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

saml.response_status

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

ROUTES

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_endpoint

/saml

This is the primary interaction point for the IdP service.

saml_descriptor

/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

/saml/authn_request

This url generates an AuthnRequest to the IdP via "saml.authn_request" helper called without options (ie, using the default options).

ATTRIBUTES

The plugin implements the following attributes.

metadata

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.

route

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.

METHODS

register

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.

sp_metadata

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