NAME
Authen::NZRealMe::ResolutionResponse - Encapsulates the response from the IdP to the artifact resolution request
DESCRIPTION
This package is used by the Authen::NZRealMe::ServiceProvider to represent the response received from the Identity Provider.
The is_success or is_error methods can be used to determine whether the user's logon was successful.
On success, the user's FLT can be retrieved using the flt method.
On failure, the URN identifying the exact error can be determined using the status_urn method. Convenience methods are also provided for identifying common error codes that you might want to handle (see: is_cancel, is_timeout, is_not_registered).
METHODS
new
Constructor. Should not be called directly. Instead, call the resolve_artifact method on the service provider object.
xml
The raw XML response from the IdP. Useful for logging and diagnostics.
service_type
Accessor for the type of service ("login" or "assertion") this response originated from.
status_urn
The 'StatusCode' 'Value' (most specific if more than one) in the response from the IdP. You probably want to use the convenience methods (such as is_cancel) rather than querying this directly although in the case of errors you will want to log this value.
status_message
In some error cases the IdP will return a human readable message relating to the error condition. If provided, you should include it in the error screen you display to your users. This routine will return an empty string if the response contained no message.
is_success
Returns true if the artifact resolution was successful and an FLT is available. Returns false otherwise.
is_error
Returns true if the artifact resolution was not successful. Returns false otherwise.
is_timeout
Returns true if the RealMe Login service timed out waiting for the user to enter their account details. After this error, it is safe to present the user with a "try again" link.
is_cancel
Returns true if the user selected 'Cancel' or 'Return to agency site' rather than logging in. After this error, it is safe to present the user with a "try again" link.
is_not_registered
Returns true if the logon was successful but the user's RealMe Login account has not been associated with this service provider (agency web site).
This situation will only occur if the original authentication request specified a false value for the allow_create option. Agency sites which use a separate flow for the initial sign-up process will need to handle this error.
as_string
Returns a string listing all the attributes from the assertion (including the FLT if requested). This is useful for logging and debiugging purposes.
RESPONSE ATTRIBUTE METHODS
The following methods are available for querying attributes returned in the response (after the artifact resolution has been completed successfully).
Note most of the attributes will only be available if they were requested during your application's integration with the assertion service and if the user consented to those details being shared with your application.
flt
Returns the user's FLT (Federated Login Tag) - a token uniquely identifying the relationship between the user, the login service and your application.
logon_strength
The URN indicating the logon strength returned by the Login Service IdP (not available in responses from the assertion service).
Note: If you have specific logon strength requirements, you should specify them using the logon_strength and strength_match options when calling the service provider's resolve_artifact method.
fit
Returns the user's FIT (Federated Identity Tag) - a token uniquely identifying the relationship between the user, the assertion service and your application.
date_of_birth
Returns the user's date of birth as an ISO date string.
place_of_birth
Returns the user's place of birth as a string containing a town name.
country_of_birth
Returns the user's country of birth as a string containing a country name.
surname
Returns the user's surname.
first_name
Returns the user's first name (if they have one).
mid_names
Returns the user's midnames (if they have any).
gender
Returns the user's gender as "M" (Male), "F" (Female) or "U" (Unknown).
address
Returns all available details of the verified address (if one was available) as a hashref with keys: "unit", "street", "suburb", "town_city" and "postcode".
If no address details are available, returns undef.
address_unit
Returns the unit identifier (e.g.: "Flat 1") from the user's address if it has one.
address_street
Returns the house number and street name (e.g.: "25 Example Street") from the user's address.
address_rural_delivery
Returns the rural delivery identifier (e.g.: "RD 7") from the user's address (if it has one).
address_suburb
Returns the suburb name (e.g.: "Herne Bay") from the user's address if it has one.
address_town_city
Returns the town or city name (e.g.: "Auckland") from the user's address.
address_postcode
Returns the postcode (e.g.: "1001") from the user's address.
PRIVATE METHODS
The following methods are used by the service provider while setting up the response object and are not intended for use by the calling application.
- set_service_type
- set_status_urn
- set_status_message
- set_logon_strength
- set_flt
- set_fit
- set_surname
- set_first_name
- set_mid_names
- set_gender
- set_date_of_birth
- set_place_of_birth
- set_country_of_birth
- set_address_unit
- set_address_street
- set_address_rural_delivery
- set_address_suburb
- set_address_town_city
- set_address_postcode
SEE ALSO
See Authen::NZRealMe for documentation index.
LICENSE AND COPYRIGHT
Copyright (c) 2010-2014 Enrolment Services, New Zealand Electoral Commission
Written by Grant McLean <grant@catalyst.net.nz>
This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.
See http://dev.perl.org/licenses/ for more information.