NAME

Net::SPID::SAML

VERSION

version 0.15

SYNOPSIS

    use Net::SPID;
    
    my $spid = Net::SPID->new(
        sp_entityid     => 'https://www.prova.it/',
        sp_key_file     => 'sp.key',
        sp_cert_file    => 'sp.pem',
        sp_assertionconsumerservice => [
            'http://localhost:3000/spid-sso',
        ],
        sp_singlelogoutservice => {
            'http://localhost:3000/spid-slo' => 'HTTP-Redirect',
        },
    );
    
    # load Identity Providers
    $spid->load_idp_metadata('idp_metadata/');
    # or:
    $spid->load_idp_from_xml_file('idp_metadata/prova.xml');
    # or:
    $spid->load_idp_from_xml($metadata_xml);
    
    # generate an AuthnRequest
    my $authnreq = $idp->authnrequest(
        acs_index   => 0,   # index of AssertionConsumerService as per our SP metadata
        attr_index  => 1,   # index of AttributeConsumingService as per our SP metadata
        level       => 1,   # SPID level
    );
    
    # prepare a HTTP-Redirect binding
    my $url = $authnreq->redirect_url;

ABSTRACT

This Perl module is aimed at implementing SPID Service Providers and Attribute Authorities. SPID is the Italian digital identity system, which enables citizens to access all public services with single set of credentials. This module provides a layer of abstraction over the SAML protocol by exposing just the subset required in order to implement SPID authentication in a web application. In addition, it will be able to generate the HTML code of the SPID login button and enable developers to implement an Attribute Authority.

This module is not bound to any particular web framework, so you'll have to do some plumbing yourself in order to route protocol messages over HTTP (see the example/ directory for a full working example). On top of this module, plugins for web frameworks can be developed in order to achieve even more API abstraction.

See README.md for a full feature list with details about SPID compliance.

CONSTRUCTOR

The preferred way to instantiate this class is to call Net::SPID-new(protocol => 'saml', ...)> instead of calling Net::SPID::SAML-new(...)> directly.

new

sp_entityid

(Required.) The entityID value for this Service Provider. According to SPID regulations, this should be a URI.

sp_key_file

(Required.) The absolute or relative file path to our private key file.

sp_cert_file

(Required.) The absolute or relative file path to our certificate file.

sp_assertionconsumerservice

An arrayref with the URL(s) of our AssertionConsumerService endpoint(s). It is used for metadata generation and for validating the Destination XML attribute of the incoming responses.

sp_singlelogoutservice

A hashref with the URL(s) of our SingleLogoutService endpoint(s), along with the specification of the binding. It is used for metadata generation and for validating the Destination XML attribute of the incoming responses.

sp_attributeconsumingservice

(Optional.) An arrayref with the AttributeConsumingServices to list in metadata, each one described by a servicename and a list of attributes. This is optional as it's only used for metadata generation.

    my $spid = Net::SPID->new(
        ...
        sp_attributeconsumingservice => [
            {
                servicename => 'Service 1',
                attributes => [qw(fiscalNumber name familyName dateOfBirth)],
            },
        ],
    );

METHODS

get_button

This method generates the HTML markup for the SPID login button:

    my $html = $spid->get_button(sub {
        return '/spid-login?idp=' . $_[0];
    });
    my $html = $spid->get_button('/spid-login?idp=%s');

The first argument can be a subroutine which will get passed the clicked IdP entityID and will need to return the full URL. As an alternative a string can be supplied, which will be handled as a format argument for a sprintf() call.

metadata

This method returns the XML representation of metadata for this Service Provider.

load_idp_metadata

This method accepts the absolute or relative path to a directory and loads one or multiple Identity Providers by reading all its files having a .xml suffix.

    $spid->load_idp_metadata('idp_metadata/');

load_idp_from_xml_file

This method accepts the absolute or relative path to a XML file containing metadata of an Identity Provider and loads it.

    $spid->load_idp_from_xml_file('idp_metadata/prova.xml');

load_idp_from_xml

This method accepts a scalar containing the XML metadata of an Identity Provider and loads it. This is useful in case you store metadata in a database.

    $spid->load_idp_from_xml($xml);

idps

This method returns a hashref of loaded Identity Providers as Net::SPID::SAML::IdP objects, having their entityIDs as keys.

    my %idps = %{$spid->idps};

get_idp

This method accepts an entityID and returns the corresponding Net::SPID::SAML::IdP object if any, or undef.

    my $idp = $spid->get_idp('https://www.prova.it/');

parse_response

This method accepts a XML payload and parses it as a Response/Assertion, returning a Net::SPID::SAML::In::Response object. Validation is performed (see the documentation for the "validate" in Net::SPID::SAML::In::Response method), so this method may throw an exception. A second argument can be supplied, containing the ID of the request message; in this case validation will also check the InResponseTo attribute.

    my $assertion = $spid->parse_assertion($xml, $request_id);

parse_logoutresponse

This method accepts a XML payload and parses it as a LogoutResponse, returning a Net::SPID::SAML::LogoutResponse object. Validation is performed automatically by calling the validate() method, so this method may throw an exception. The XML payload can be supplied also in Base64-encoded form, thus you can supply the value of SAMLResponse parameter directly. In case the LogoutResponse was supplied through a HTTP-Redirect binding (in other words, via GET), the request URI (inclusive of the query string) must be supplied as second argument. This is used for signature validation. If HTTP-POST was used the second argument is ignored. A third argument must be supplied, containing the ID of the request message; this is used for the mandatory security check of the InResponseTo attribute.

    my $response = $spid->parse_logoutresponse($xml, $url, $request_id);

parse_logoutrequest

This method accepts a XML payload and parses it as a LogoutRequest, returning a Net::SPID::SAML::LogoutRequest. Use this to handle third-party-initiated logout procedures. Validation is performed, so this method may throw an exception. In case HTTP-Redirect was used to deliver this LogoutRequest to our application, a second argument is required containing the request URI (see parse_logoutresponse).

    my $request = $spid->parse_logoutrequest($xml, $url);

AUTHOR

Alessandro Ranellucci <aar@cpan.org>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2018 by Alessandro Ranellucci.

This is free software, licensed under:

  The (three-clause) BSD License

cpanm Net::SPID

perl -MCPAN -e shell
install Net::SPID