view release on metacpan or  search on metacpan

lib/Mojolicious/Plugin/SAML.pm  view on Meta::CPAN

=head2 key

The file path location of an RSA private key.

=head2 cert

The file path location of an X509 certificate generated by the L</key>.

=head2 location

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

=head2 entity_id

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

=head2 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 L</"saml.response_success">; the callback should and handle accordingly.

=head1 HELPERS

=head2 saml.authn_request

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

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

=over

=item binding

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

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

=item 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 L</"saml.response_success"> and L</"saml.response_status">).

=item sign

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

=back

=head2 saml.response

  my $dom = $c->saml->response;

Returns the parsed (and validated) SAML response (as a L<Mojo:DOM> object).
This must only be called during the response to a SAML interaction, notably during L</handle_login>.

=head2 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 L</handle_login>.

=head2 saml.response_status

  my $status = $c->saml->response_status;

Returns the string status from the SAML response.
This may be useful if L</"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 L</handle_login>.

=head1 ROUTES

This plugin creates several routes all existing under the base url derived from L</location>.
They are described below by name and path, where the base path is assumed to be C</saml>.

=head2 saml_endpoint

  /saml

This is the primary interaction point for the IdP service.

=head2 saml_descriptor

  /saml/descriptor

This url renders the Entity Metadata for the service, containing the SP descriptor that the IdP will need for configuration.

=head2 saml_authn_request

  /saml/authn_request

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

=head1 ATTRIBUTES

The plugin implements the following attributes.

=head2 metadata

  my $doc = $saml->metadata;

Stores the generated metadata, an instance of L<Mojo::SAML::Document::EntityDescriptor>.
This can be modified before the first time is is served by L</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.

=head2 route

  my $r = $saml->route;