The Perl Net::SAML2 module has been around a long time and although there have been some significant updates over the last several years, the last couple of releases have seen significant changes thanks to Wesley Schwengle.

With Net::SAML2 0.60-TRIAL however, there are multiple potentially BREAKING CHANGES depending on how you have written your application. Your application may need updates for this version.

Perl has always promoted test scripts to ensure that new versions were automatically tested with the same tests as old versions. In most cases a module will not ship if it breaks one of the existing test scripts. In this case, the changes serve to improve the functionality and the consistency of the functions.

BREAKING CHANGES

1. Support multiple signing keys in the metadata. This version attempts to ensure compatibility but the call to Net::SAML2::IdP->cert will return an array of certs for each $use. It is, however, likely that there will only be one cert in the array.

2. Net::SAML2::Binding::SOAP was improved. The call to Net::SAML2::Binding::SOAP->handle_request() now returns the XML whereas in the past it returned the certificate's subject and the xml as an array. This make it consistent with the Redirect and POST Bindings.

3. Net::SAML2::Binding::POST was also improved. Previously the call to Net::SAML2::Binding::POST->handle_response() returned inconsistent results depending on whether a cacert was provided. This version returns the XML of the decoded request.

Other Changes of note

1. Redirects now validate the raw URI that is passed to the call. It is assumed that the URI that your application has sent is unmodified from the response that the web server received. lighttpd in particular normalises the response and will break Redirects from Microsoft Azure.

2. SAML trust anchors were implemented and the verification of the SAML response was improved. It is possible to validate the response with subject, issuer or issuer_hash as anchors in addition to the cacert. Neither cacert nor anchors are required as long as the signature of the response is valid. The cacert has not been required for the Redirect or SOAP binding so this treats SOAP the same.

Required Application Updates

There were several changes to the test suite that will likely need to be made in your application:

1. To support metadata.xml containing multiple KeyDescriptors the call to Net::SAML2::IdP->cert($use) now returns an ARRAY.
   As this is an helper function that is meant to allow you to pass the cert to another Net::SAML2 call it was deemed low risk. Your code may be unaffected.

2. The call to Net::SAML2::Binding::SOAP->handle_request() needs to be updated to reflect that it returns only the decoded XML not an array of the certificate Subject and XML.

3. The call to Net::SAML2::Binding::POST->handle_response() returned inconsistent results depending on whether a cacert was provided. This version returns the XML of the decoded request. Previously it returned either 1 for success or if a cacert was used either "(verified) and the certificate Subject" or 0 if the certificate verification failed.

4. The lighttpd.conf for the testapp did require a change to prevent it from "normalizing" a SAML Logout Redirect. There are contradictory RFCs concerning SAML and the "normalising" URIs. If you use lighttpd in a SAML application with AZURE as your SAML IdP see lighttpd.conf

Possible Impacts

It is worth noting that the testapp (that implements a rudimentary Service Provider) included in the git repo did not require any code changes to the application for this version.

While my setup tests against multiple IdPs I do not have a working SOAP IdP at present.