/ 
Authen-NZRealMe-1.23
River stage zero No dependents
/ Authen::NZRealMe::ServiceProvider

NAME

Authen::NZRealMe::ServiceProvider - Class representing the local SAML2 Service Provider

DESCRIPTION

This class is used to represent the local SAML2 SP (Service Provider) which will be used to access the NZ RealMe Login service IdP (Identity Provider) or the NZ RealMe Assertion service IdP. In normal use, an object of this class is initialised from the metadata-sp.xml in the configuration directory. This class can also be used to generate that metadata file.

METHODS

new

Constructor. Should not be called directly. Instead, call:

Authen::NZRealMe->service_provider( args );

The following options are recognised:

conf_dir => '/path/to/directory'

The conf_dir parameter must be provided. It specifies the full pathname of the directory containing SP and IdP metadata files as well as certificate and key files for request signing and mutual-SSL.

type => ( "login" | "assertion" )

Indicate whether you wish to communicate with the "login" service or the "assertion" service (for identity information). Default: "login".

skip_signature_check => [ 0 | 1 | 2 ]

This (seldom used) option allows you to turn off verification of digital signatures in the assertions returned from the IdP. The default value is 0 - meaning signatures will be checked.

If set to 1, a failed signature check will result in a warning to STDERR but further processing of the assertion will continue. This mode is useful if the signing certificate is scheduled to be replaced on the IdP. Enabling this option allows you to update your metadata before or after the scheduled change without needing to coordinate your timing exactly with the IdP service.

Setting this option to 2 will completely skip signature checks (i.e. no errors or warnings will be generated).

new_defaults

Alternative constructor which is called to set up some sensible defaults when generating metadata.

conf_dir

Accessor for the conf_dir parameter passed in to the constructor.

entity_id

Accessor for the entityID parameter in the Service Provider metadata file.

acs_list

Accessor for the details from the AssertionConsumerService parameters in the Service Provider metadata file. This method returns a list of hashes.

organization_name

Accessor for the OrganizationName component of the Organization parameter in the Service Provider metadata file.

organization_url

Accessor for the OrganizationURL component of the Organization parameter in the Service Provider metadata file.

contact_company

Accessor for the Company component of the ContactPerson parameter in the Service Provider metadata file.

signing_cert_pathname

Accessor for the pathname of the Service Provider's signing certificate. This will always be the file sp-sign-crt.pem in the configuration directory.

signing_key_pathname

Accessor for the pathname of the Service Provider's signing key. This will always be the file sp-sign-key.pem in the configuration directory.

ssl_cert_pathname

Accessor for the pathname of the Service Provider's mutual SSL certificate. This will always be the file sp-ssl-crt.pem in the configuration directory.

ssl_key_pathname

Accessor for the pathname of the Service Provider's mutual SSL private key. This will always be the file sp-sign-crt.pem in the configuration directory.

ca_cert_pathname

Name of the sub-directory (beneath conf_dir) that contains the CA certficates required to verify the certficate presented by the IdP on the back channel when resolving an assertion.

idp

Accessor for an object representing the Identity Provider for the selected service type ("login" or "assertion"). See: Authen::NZRealMe::IdentityProvider.

nameid_format

Returns a string URN representing the format of the NameID requested/expected from the Identity Provider.

When this value is urn:urn:oasis:names:tc:SAML:2.0:nameid-format:persistent then the NameID value is the Federated Logon Tag (FLT).

Otherwise, it is urn:oasis:names:tc:SAML:2.0:nameid-format:transient and the FLT must be obtained via the back-channel service, iCMS.

token_generator

Creates and returns an object of the class responsible for generating random ID tokens.

generate_saml_id

Used by the request classes to generate a unique identifier for each request. It accepts one argument, being a string like 'AuthenRequest' to identify the type of request.

generate_certs

Called by the nzrealme make-certs command to run an interactive Q&A session to generate either self-signed certificates or Certificate Signing Requests (CSRs). Delegates to Authen::NZRealMe::ServiceProvider::CertFactory

build_meta

Called by the nzrealme make-meta command to run an interactive Q&A session to initialise or edit the contents of the Service Provider metadata file. Delegates to Authen::NZRealMe::ServiceProvider::Builder

make_bundle

Called by the nzrealme make-bundle command to create a zip archive of the files needed by the IdP. The archive will include the SP metadata and certificate files. Delegates to Authen::NZRealMe::ServiceProvider::Builder

new_request( options )

Creates a new Authen::NZRealMe::AuthenRequest object. The caller would typically use the as_url method of the request to redirect the client to the Identity Provider's single logon service. The request object's request_id method should be used to get the request ID and save it in session state for use later during artifact resolution.

The new_request method does not require any arguments, but accepts the following optional key => value pairs:

allow_create => boolean

Controls whether the user should be allowed to create a new account on the "login" service IdP. Not used when talking to the "assertion service". Default: false.

auth_strength => string

The logon strength required. May be supplied as a URN, or as keyword ('low', 'mod', 'sms', etc). See Authen::NZRealMe::LogonStrength for constants. Default: 'low'.

relay_state => string

User-supplied string value that will be returned as a URL parameter to the assertion consumer service.

acs_index => integer or 'default'

Used to specify the numeric index of the Assertion Consumer Service you would like the response sent to. The value default may also be used to specify the ACS marked as the default.

metadata_xml

Serialises the current Service Provider config parameters to a SAML2 EntityDescriptor metadata document.

sign_query_string

Used by the Authen::NZRealMe::AuthenRequest class to create a digital signature for the AuthnRequest HTTP-Redirect URL.

resolve_posted_assertion

Used to resolve the SAML response when the HTTP-POST binding is being used.

Takes the value of the SAMLResponse from the IdP's HTTP-POST response; validates the contents and return an Authen::NZRealMe::ResolutionResponse object.

Parameters (including the original request_id) must be supplied as key => value pairs, for example:

my $resp = $sp->resolve_artifact(
    saml_response   => $framework->param('SAMLResponse'),
    request_id      => $framework->state('login_request_id'),
    logon_strength  => 'low',        # optional
    strength_match  => 'minimum',    # optional - default: 'minimum'
);

Recognised parameter names are:

saml_response

The contents of the 'SMLResponse' parameter in the HTTP POST request from the IdP. This will be a Base-64 encoded string, but it should simply be passed on without any processing.

see "Common resolver parameters" below

resolve_artifact

Used to resolve the SAML response when the HTTP-Artifact binding is being used.

Takes an artifact (either the whole URL or just the SAMLart parameter) and contacts the Identity Provider to resolve it to a set of attributes. An artifact from the login server will only provide an 'FLT' attribute. An artifact from the assertion server will provide identity and/or address attributes.

Parameters (including the original request_id) must be supplied as key => value pairs, for example:

my $resp = $sp->resolve_artifact(
    artifact        => $framework->param('SAMLart'),
    request_id      => $framework->state('login_request_id'),
    logon_strength  => 'low',        # optional
    strength_match  => 'minimum',    # optional - default: 'minimum'
);

The assertion returned by the Identity Provider will be validated and its contents returned as an Authen::NZRealMe::ResolutionResponse object. If an unexpected error occurs while resolving the artifact or while validating the resulting assertion, an exception will be thrown. Expected error conditions (eg: timeouts, user presses 'Cancel' etc) will not throw an exception, but will return a response object that can be interrogated to determine the nature of the error. The calling application may wish to log the expected errors with a severity of 'WARN' or 'INFO'.

Recognised parameter names are:

artifact

Either the whole URL of the client request to the ACS, or just the SAMLart parameter from the querystring.

see "Common resolver parameters" below

Common resolver parameters

The following parameters can be used with both the resolve_posted_assertion() method (for HTTP-POST binding) and the resolve_artifact() method (for HTTP-Artifact binding).

request_id

The request_id returned in the original call to new_request. Your application will need to store this in session state when initiating the dialogue with the IdP and retrieve it from state when resolving the artifact.

acs_index

Optional parameter which may be used to specify the numeric index of the Assertion Consumer Service you would like the response sent to. This would normally be omitted, resulting in the default being used. Currently the primary reason for specifying this value is if your metadata defines one or more ACS entries using the HTTP-Artifact binding and one or more which use the HTTP-POST binding. This parameter will allow you to tell the server which binding to use - which may be useful while transitioning your system from one binding to another.

logon_strength

Optional parameter which may be used to check that the response from the logon service matches your application's logon strength requirements. Specify as a URN string or a word (e.g.: "low", "moderate"). If not provided, no check will be performed.

strength_match

If a logon_strength was specified, this parameter will determine how the values will be matched. Provide either "minimum" (the default) or "exact".

resolve_flt

When resolving an artifact from the assertion service, you can provide this option with a true value to indicate that the opaque token should be resolved to an FLT. If this option is not set, only the attributes from the assertion service will be returned and no attempt will be made to connect to the iCMS service.

decrypt_assertion( $xml_string )

Called by resolve_posted_assertion (or optionally by resolve_artifact if an encrypted assertion was returned) to replace any <EncryptedData> elements with their unencrypted contents.

As a security precuation, this method will die if any unencrypted <Assertion> elements are present in the supplied XML.

select_acs_by_index ( $index )

Used by new_request to validate the requested acs_index value. The value default may also be used to specify the ACS marked as the default.

Returns the selected ACS.

now_as_iso

Convenience method returns the current time (UTC) formatted as an ISO date/time string.

SEE ALSO

See Authen::NZRealMe for documentation index.

LICENSE AND COPYRIGHT

Copyright (c) 2010-2022 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.