Robert Norris > Postini-SAML-0.001 > Postini::SAML

Download:
Postini-SAML-0.001.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 0.001   Source  

NAME ^

Postini::SAML - Do SAML-based sign-in to Postini services

VERSION ^

version 0.001

SYNOPSIS ^

    use Postini::SAML;

    # setup keys and certificates
    my $saml = Postini::SAML->new({
        keyfile  => 'postini.key',
        certfile => 'postini.crt',
        issuer   => 'example.com',
    });

    # get a signed SAML response that will sign in the given user
    my $response_xml = $saml->get_response_xml('user@example.com');
 
    # quick and dirty HTML form for testing
    print $saml->get_form('user@example.com');

DESCRIPTION ^

Postini::SAML creates signed SAML responses suitable for signing your users into Postini services (aka "Google Message Security" and/or "Google Message Discovery").

It is not a complete SAML implementation or SSO solution. It implements just enough of the SAML spec to get you into Postini. The author is not an expert on SAML, XML or security in general. Don't be afraid though; this module does work and is production use at at least one site :)

Postini offers two modes of operation for SAML SSO - "push" (or "post") and "pull" (or "artifact). This modules implements the push model.

The typical SAML flow for Postini is slightly different to a standard SAML flow in that it is not initiated on the Postini side. Instead you need to set up a sign-in page on your website or application server and direct your users to it. The flow is as follows:

See the discussion of "get_form" for information on how to generate your own form.

SETUP ^

Before you use this module its necessary to have SSO configured for your Postini organisation. The Postini docs are a bit thin on what you need to do. A full explanation is well outside the scope of this document, but here's list of things you should have in place before trying to use this module:

CONSTRUCTOR ^

    my $saml = Postini::SAML->new({
        keyfile  => 'postini.key',
        certfile => 'postini.crt',
        issuer   => 'example.com',
    });

Creates an object that can produce SAML responses. You need to provide three arguments:

keyfile

Name of file containing the private key in PEM format.

certfile

Name of file containing the certificate in PEM format.

issuer

The issuer attached to this certificate in the Postini configuration.

METHODS ^

get_response_xml

    my $response_xml = $saml->get_response_xml('user@example.com');

Create a signed SAML response document that, when submitted to the Postini ACS URL, will sign in the specified user. The response is valid for 60 seconds and so should be returned to the user for submission immediately.

get_form

    print $saml->get_form('user@example.com');

Creates a basic HTML form that, when submitted, will sign in the specified user. This is provided for testing purposes only. While you could use it as part of a larger page you're probably better to make something tailored to your environment.

To submit the SAML response to Postini you need to perform a HTTP POST to the ACS URL, which can be obtained using "get_acs_url". The request takes two arguments:

SAMLResponse

The Base64-encoded response XML returned by "get_response_xml".

TARGET

The Postini ACS URL, obtained using "get_acs_url".

get_acs_url

    my $acs_url = $saml->get_acs_url;

Get the ACS URL to submit the SAML response document to. The is hardcoded to https://pfs.postini.com/pfs/spServlet.

BUGS ^

None known. Please report bugs via the CPAN Request Tracker at http://rt.cpan.org/NoAuth/Bugs.html?Dist=Postini-SAML

FEEDBACK ^

If you find this module useful, please consider rating it on the CPAN Ratings service at http://cpanratings.perl.org/rate?distribution=Postini-SAML.

If you like (or hate) this module, please tell the author! Send mail to <rob@eatenbyagrue.org>.

SEE ALSO ^

Google::SAML::Response

AUTHOR ^

Robert Norris <rob@eatenbyagrue.org>

COPYRIGHT AND LICENSE ^

Copyright (c) 2011 Monash University.

This module is free software, you can redistribute it and/or modify it under the same terms as Perl itself.

syntax highlighting: