view release on metacpan or  search on metacpan

lib/Authen/NZRealMe.pm  view on Meta::CPAN

package Authen::NZRealMe;
$Authen::NZRealMe::VERSION = '1.23';
use warnings;
use strict;


=head1 NAME

Authen::NZRealMe - Integrate with RealMe login and identity services (formerly "igovt logon")

=head1 DESCRIPTION

Provides an API for integrating your application with the New Zealand RealMe
login service and the RealMe assertion service (for verified identity and
address details) using SAML 2.0 messaging.

Note: If you are looking at this code as an example implementation of SAML2,
then you can safely ignore any code referring to "iCMS" - it is a (deprecated)
supplementary API provided by the RealMe IdP, which uses WS-Trust protocols.

The distribution also includes a command-line tool called C<nzrealme> which can
be used for:

=over 4

=item *

generating certificate/key pairs for signing and SSL encryption

=item *

creating/editing the Service Provider metadata file

=item *

creating a bundle (zip file) containing metadata and certs for upload to the
IdP

=item *

generating AuthnRequest URLs

=item *

decoding/dumping AuthnRequest URLs

=item *

resolving SAMLart artifact responses and validating the response

=back

Run C<< nzrealme --help >> for more information about using the command-line
tool.

=cut


my %class_map = (
    service_provider        => 'Authen::NZRealMe::ServiceProvider',
    identity_provider       => 'Authen::NZRealMe::IdentityProvider',
    token_generator         => 'Authen::NZRealMe::TokenGenerator',
    xml_signer              => 'Authen::NZRealMe::XMLSig',
    xml_encrypter           => 'Authen::NZRealMe::XMLEnc',
    sp_builder              => 'Authen::NZRealMe::ServiceProvider::Builder',
    sp_cert_factory         => 'Authen::NZRealMe::ServiceProvider::CertFactory',
    resolution_request      => 'Authen::NZRealMe::ResolutionRequest',
    icms_resolution_request => 'Authen::NZRealMe::ICMSResolutionRequest',
    resolution_response     => 'Authen::NZRealMe::ResolutionResponse',
    authen_request          => 'Authen::NZRealMe::AuthenRequest',
    logon_strength          => 'Authen::NZRealMe::LogonStrength',
    term_readline           => 'Authen::NZRealMe',
);


sub service_provider {
    my $class = shift;

    return $class->class_for('service_provider')->new(@_);
}


sub _sp_from_opt {
    my $class      = shift;
    my $opt        = shift;

    my $service_type = $opt->{type} || "login";
    my %sp_options = (
        conf_dir  => _conf_dir($opt),
        type      => $service_type,
    );
    $sp_options{disable_ssl_verify} = $opt->{disable_ssl_verify} if $opt->{disable_ssl_verify};
    return $class->service_provider(%sp_options);
}

lib/Authen/NZRealMe.pm  view on Meta::CPAN

=head3 Certificate/Key pairs

Once you've decided on a location, you need to generate one or possibly two SSL
certificates and their corresponding private keys.  The first certificate/key
pair will be used for signing the SAML AuthnRequest messages.  If you are using
the HTTP-POST binding, the IdP will use the public key from this same
certificate to encrypt the SAMLResponse.  If you are using the HTTP-Artifact
binding, you'll need a second certificate/key pair to be used for mutual SSL
encryption of communications over the back-channel.

It is not necessary to generate the certificates on the same machine where
they will be used however you must have the C<openssl> command-line tools
installed on the machine where you wish to generate them.

The process for generating certificates will depend on which environment you
are connecting to:

=over 4

=item MTS (Development)

You do not need to generate certificates at all for the MTS environment -
simply use the files provided in the MTS integration resources pack.  Copy them
into your config directory and rename as follows:

  mts_mutual_ssl_sp.pem => sp-sign-key.pem
  mts_mutual_ssl_sp.cer => sp-sign-crt.pem
  mts_saml_sp.pem       => sp-ssl-key.pem
  mts_saml_sp.cer       => sp-ssl-crt.pem

=item ITE (Staging) and PROD (Production)

For both the ITE and production environments you can use the C<nzrealme> tool
to generate Certificate Signing Requests which you will then submit to a
Certification Authority who will issue signed certificate files.  Save them in
the config directory using the filenames listed above.

  nzrealme --conf-dir /etc/nzrealme make-certs --env PROD ...

(Note: it used to be possible to use self-signed certificates with ITE - this
is no longer possible).

=back

=head3 SP Metadata

After you have generated the certificates, you can generate a metadata file
with the command:

  nzrealme --conf-dir /etc/nzrealme make-meta

You will be prompted to provide the necessary details and can re-run the
command to revise your answers.

Note: Whilst this command should give you a metadata file which passes
validation it is likely that you will need to edit the file in a text editor to
fine tune the parameters - particularly if you need more than one Assertion
Consumer Service.

You will need to provide the SP metadata file to the RealMe login service. For
MTS you can upload the SP metadata file directly using the menu option on the
MTS site.  If you need to revise the file you can simply upload a new version.
For ITE and PROD you will need to provide the metadata and also the certificate
files to RealMe - who will schedule an upload to the relevant services.  You
can assemble a 'bundle' of the required files with this command:

  nzrealme --conf-dir /etc/nzrealme make-bundle


=head1 TESTING

Normally your application would generate an authentication request URL and
redirect the client to it, however it is also possible to generate one from the
command-line:

  nzrealme --conf-dir /etc/nzrealme make-req

You can paste this URL into a browser and complete a log on.  Once you have
logged on you will be redirected back to the URL for the ACS (as specified in
the SP metadata file that you uploaded).  You can copy the ACS URL from your
browser and paste it into the following command to resolve the artifact passed
in the URL to an FLT:

  nzrealme --conf-dir /etc/nzrealme resolve <ACS URL> <Request ID>

The ACS URL will contain special characters that may need to be quoted.  You'll
also need to supply the Request ID which was output by the original C<make-req>
command.


=head1 API REFERENCE

The C<Authen::NZRealMe> class provides entry points for interactions with the
RealMe login service and is also responsible for dispatching the various
command implemented by the C<nzrealme> command-line utility.

=head2 service_provider( conf_dir => $path_to_config_directory )

This method is the main entry point for the API.  It returns a service_provider
object that will then be used to generate AuthnRequest messages and to resolve
either an encrypted assertion or a returned artifact.  Unless you have set up
alternative class mappings (see below), this method is a simple wrapper for the
L<Authen::NZRealMe::ServiceProvider> constructor.

=head2 class_for( identifier )

This method forms half of a simple dependency injection framework.  Rather
than hard-code the classnames for the various parts of the API, this method
is used to turn a simple functional name (e.g.: C<'service_provider'>) into a
classname like C<Authen::NZRealMe::ServiceProvider>.  This method will also
load the package using C<require>.

You would not usually call this method directly - instead you would use the
C<service_provider> method which calls this.

=head2 register_class( identifier => package )

This method forms the other half of the dependency injection implementation
and is used to override the default mappings.  The most common reason to use
this method is to inject mock object classnames for use during automated
testing.

=head2 run_command( command, args )

This method is called by the C<nzrealme> command-line tool, to delegate tasks to
the appropriate classes.  For more information about available commands, see
C<< nzrealme --help >>

=head2 init_readline( )

This method is used by the implemntations of C<'make-cert'> and C<'make-meta'>
when it is necessary to prompt the user for interactive input.

=cut

=head2 Related Classes

Your application should only need to directly interface with the Service
Provider module (as shown above).  The service provider will delegate to other
classes as required.  Reference documentation is available for these other