view release on metacpan or  search on metacpan

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

You set up which URL you want the logon service to redirect back to when you
generate your service provider metadata (see L</CONFIGURATION>).  This URL is
known as the Assertion Consumer Service or 'ACS'.

If you're using the HTTP-POST binding, you'll need to get the value of the
'SAMLResponse' form parameter and pass it to the C<resolve_posted_assertion()>
method (along with the original request_id retrieved from the user's session
state).

If you're using the HTTP-Artifact binding, you'll need to get the value of
the 'SAMLart' querystring parameter and pass it to the C<resolve_artifact()>
method (along with the original request_id retrieved from the user's session
state).

In either case, a SAML Assertion will be retrieved. For HTTP-POST, the API call
will decode and decrypt the posted response.  For HTTP-Artifact, the API call
will look after: generating a SAML ArtifactResolve message; passing it to the
IdP over a backchannel; accepting the SAML ArtifactResponse message.

Once the SAML assertion is retrieved, the API call will also: validate the
assertion (checking digital signature, timestamps and other validity
constraints); extract and return the attributes (or error detail) in a response
object

The method call will return a response object containing either the attribute
details or details of the condition which meant the logon was unsuccessful.  In
the case of an unexpected error, the method call will generate an exception
which you will need to catch and log.

A response from the login service will only include an FLT attribute, whereas a
response from the assertion service may contain a number of identity attributes
and, optionally, the FLT attribute.
See L<Authen::NZRealMe::ResolutionResponse> for details of methods provided to
access the attribute values.

Sample code for processing HTTP-POST would look like this:

  my $sp   = Authen::NZRealMe->service_provider(
      conf_dir => $path_to_config_directory
  );
  my $resp = eval {
      $sp->resolve_posted_assertion(
          saml_response => $framework->param('SAMLart'),
          request_id    => $framework->get_state('login_request_id'),
      );
  };
  if($@) {
      # handle catastrophic failures (e.g.: malformed response) here
  }
  if($resp->is_success) {
      $framework->set_state(login_flt => $resp->flt);
      # ... redirect to main menu etc
  }
  elsif($resp->is_timeout) {
      # Present logon screen again with message
  }
  elsif($resp->is_cancel) {
      # Present logon screen again with message
  }
  elsif($resp->is_not_registered) {
      # Only happens if allow_create set to false
      # and user does not have a logon for our site
  }
  else {
      # Some other failure occurred, user might like to try again later.
      # Should present $resp->status_message to user and also give contact
      # details for RealMe Help Desk
  }

Sample code for HTTP-Artifact would be identical except for the 'resolve'
method call:

  my $resp = eval {
      $sp->resolve_artifact(
          artifact   => $framework->param('SAMLart'),
          request_id => $framework->get_state('login_request_id'),
      );
  };
  # Process response as for HTTP-POST, above

Note: there are two different categories of 'error': the C<resolve_artifact()>
method might throw an exception (caught by eval, details in $@); or a response
object might be returned but with C<< $resp->is_success >> set to false.  The
details of an exception should be logged, but not displayed back to the user.
In the event that your application displays the contents of
C<< $resp->status_message >> you should ensure that you apply appropriate HTML
escaping.

For reference documentation about the Service Provider API, see
L<Authen::NZRealMe::ServiceProvider>.


=head1 CONFIGURATION

This module is configuration-driven - when making an API call, you specify the
path to the config directory and the module picks up everything it needs to
talk to the RealMe login service IdP (Identity Provider) from metadata files
and certificate/key-pair files used for signing/encryption.

=head2 Config Files Overview

The files in the config directory use the following naming convention so you
just need to point the module at the right directory.  The filenames are:

=over 4

=item C<metadata-login-sp.xml>

This file contains config parameters for the 'Service Provider' - your end of
the authentication dialog - which will talk to the login service.  Once you
have generated the SP metadata file (see: L</Generating Config Files>) you will
need to provide it to the RealMe logon service to install at their end.  You
will need to generate separate metadata files for each of your development,
staging and production environments.

=item C<metadata-login-idp.xml>

The login service IdP or Identity Provider metadata file will be provided to
you by RealMe/DIA.  You will simply need to copy it to the config directory and
give it the correct name.