File Coverage

blib/lib/Authen/NZRealMe.pm

Criterion	Covered	Total	%
statement	11	79	13.9
branch	1	42	2.3
condition	0	2	0.0
subroutine	3	15	20.0
pod	4	4	100.0
total	19	142	13.3

package Authen::NZRealMe;
{
  $Authen::NZRealMe::VERSION = '1.15';
}

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: This distribution was renamed from Authen::NZigovt following the
rebranding of the service from "igovt" to "RealMe".  When migrating systems to
use the new module, it will be necessary to rename some of the config files to
the new names listed under L below.

The distribution also includes a command-line tool called C 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',
    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',
);


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);
}


sub class_for {
    my($class, $key) = @_;
    my $module = $class_map{$key} or die "No class defined for '$key'";
    $module =~ s{::}{/}g;
    require $module . '.pm';
    return $class_map{$key};
}


sub register_class {
    my($class, $key, $package) = @_;
    $class_map{$key} = $package;
}


sub run_command {
    my $class   = shift;
    my $opt     = shift;
    my $command = shift or die "no command specified\n";

    my $method = '_dispatch_' . $command;
    $method =~ s{[^a-z0-9]+}{_}g;
    die "unrecognised command: '$command'\n" unless $class->can($method);

    $class->$method($opt, @_);
}


sub _dispatch_make_certs {
    my($class, $opt) = @_;

    my %args;
    $args{env}      = $opt->{env}      if $opt->{env};
    $args{org}      = $opt->{org}      if $opt->{org};
    $args{org_unit} = $opt->{org_unit} if $opt->{org_unit};
    $args{domain}   = $opt->{domain}   if $opt->{domain};
    $class->class_for('service_provider')->generate_certs(
        _conf_dir($opt), %args
    );
}


sub _dispatch_make_meta {
    my($class, $opt) = @_;

    $class->class_for('service_provider')->build_meta(
        conf_dir => _conf_dir($opt)
    );
}


sub _dispatch_make_bundle {
    my($class, $opt) = @_;

    my $file = $class->class_for('service_provider')->make_bundle(
        conf_dir => _conf_dir($opt),
    );
    print "Created metadata bundle for IDP at: $file\n";
}


sub _dispatch_make_req {
    my($class, $opt) = @_;

    my $sp  = $class->_sp_from_opt($opt);
    my @req_options;
    if($sp->type eq 'login') {
        my $allow_create = $opt->{allow_create} ? 1 : 0;
        push @req_options, allow_create => $allow_create;
    }
    my $req = $sp->new_request( @req_options );

    print "Request ID: ", $req->request_id, "\n" if -t 1;
    print $req->as_url, "\n";
}


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

    $class->class_for('authen_request')->dump_request(@_);
}


sub _dispatch_resolve {
    my $class      = shift;
    my $opt        = shift;
    my $artifact   = shift or die "Must provide artifact or URL\n";
    my $request_id = shift or die "Must provide ID from original request\n";

    my $sp   = $class->_sp_from_opt($opt);
    my %args = (
        artifact   => $artifact,
        request_id => $request_id,
    );
    $args{resolve_flt}    = 1 if $opt->{resolve_flt};
    $args{logon_strength} = shift if @_;
    $args{strength_match} = shift if @_;
    $args{_to_file_}      = $opt->{to_file}   if $opt->{to_file};
    $args{_from_file_}    = $opt->{from_file} if $opt->{from_file};
    my $response = eval {
        $sp->resolve_artifact(%args);
    };
    if($@) {
        print "Failed to resolve artifact:\n$@";
        exit 1;
    }
    print $response->as_string();
}


sub _dispatch_version {
    print $Authen::NZRealMe::VERSION, "\n";
}


sub _conf_dir {
    my($opt) = @_;

    if($opt->{conf_dir}) {
        $opt->{conf_dir} =~ s{/\z}{};
        return $opt->{conf_dir} if -d $opt->{conf_dir};
        die "Directory does not exist: $opt->{conf_dir}";
    }
    my $cmnd = (caller(1))[3];
    $cmnd =~ s/^.*::_dispatch_//;
    $cmnd =~ s/_/-/g;
    die "$cmnd command needs --conf-dir option\n";
}

1;


__END__