Skip to content

Latest commit

 

History

History
149 lines (102 loc) · 6.47 KB

UPGRADING.md

File metadata and controls

149 lines (102 loc) · 6.47 KB

Ruby SAML Migration Guide

Updating from 1.12.x to 1.13.0

Version 1.13.0 adds settings.idp_sso_service_binding and settings.idp_slo_service_binding, and deprecates settings.security[:embed_sign]. If specified, new binding parameters will be used in place of :embed_sign to determine how to handle SAML message signing (HTTP-POST embeds signature and HTTP-Redirect does not.)

In addition, the IdpMetadataParser#parse, #parse_to_hash and #parse_to_array methods now retrieve idp_sso_service_binding and idp_slo_service_binding.

Lastly, for convenience you may now use the Symbol aliases :post and :redirect for any settings.*_binding parameter.

Upgrading from 1.11.x to 1.12.0

Version 1.12.0 adds support for gcm algorithm and change/adds specific error messages for signature validations

idp_sso_target_url and idp_slo_target_url attributes of the Settings class deprecated in favor of idp_sso_service_url and idp_slo_service_url. The IdpMetadataParser#parse, #parse_to_hash and #parse_to_array methods now retrieve SSO URL and SLO URL endpoints with idp_sso_service_url and idp_slo_service_url (previously idp_sso_target_url and idp_slo_target_url respectively).

Upgrading from 1.10.x to 1.11.0

Version 1.11.0 deprecates the use of settings.issuer in favour of settings.sp_entity_id. There are two new security settings: settings.security[:check_idp_cert_expiration] and settings.security[:check_sp_cert_expiration] (both false by default) that check if the IdP or SP X.509 certificate has expired, respectively.

Version 1.10.2 includes the valid_until attribute in parsed IdP metadata.

Version 1.10.1 improves Ruby 1.8.7 support.

Upgrading from 1.9.0 to 1.10.0

Version 1.10.0 improves IdpMetadataParser to allow parse multiple IDPSSODescriptor, Add Subject support on AuthNRequest to allow SPs provide info to the IdP about the user to be authenticated and updates the format_cert method to accept certs with /\x0d/

Upgrading from 1.8.0 to 1.9.0

Version 1.9.0 better supports Ruby 2.4+ and JRuby 9.2.0.0. Settings initialization now has a second parameter, keep_security_settings (default: false), which saves security settings attributes that are not explicitly overridden, if set to true.

Upgrading from 1.7.x to 1.8.0

On Version 1.8.0, creating AuthRequests/LogoutRequests/LogoutResponses with nil RelayState param will not generate a URL with an empty RelayState parameter anymore. It also changes the invalid audience error message.

Upgrading from 1.6.0 to 1.7.0

Version 1.7.0 is a recommended update for all Ruby SAML users as it includes a fix for the CVE-2017-11428 vulnerability.

Upgrading from 1.5.0 to 1.6.0

Version 1.6.0 changes the preferred way to construct instances of Logoutresponse and SloLogoutrequest. Previously the SAMLResponse, RelayState, and SigAlg parameters of these message types were provided via the constructor's options[:get_params] parameter. Unfortunately this can result in incompatibility with other SAML implementations; signatures are specified to be computed based on the sender's URI-encoding of the message, which can differ from that of Ruby SAML. In particular, Ruby SAML's URI-encoding does not match that of Microsoft ADFS, so messages from ADFS can fail signature validation.

The new preferred way to provide SAMLResponse, RelayState, and SigAlg is via the options[:raw_get_params] parameter. For example:

# In this example `query_params` is assumed to contain decoded query parameters,
# and `raw_query_params` is assumed to contain encoded query parameters as sent by the IDP.
settings = {
  settings.security[:signature_method] = XMLSecurity::Document::RSA_SHA1
  settings.soft = false
}
options = {
  get_params: {
    "Signature" => query_params["Signature"],
  },
  raw_get_params: {
    "SAMLRequest" => raw_query_params["SAMLRequest"],
    "SigAlg" => raw_query_params["SigAlg"],
    "RelayState" => raw_query_params["RelayState"],
  },
}
slo_logout_request = OneLogin::RubySaml::SloLogoutrequest.new(query_params["SAMLRequest"], settings, options)
raise "Invalid Logout Request" unless slo_logout_request.is_valid?

The old form is still supported for backward compatibility, but all Ruby SAML users should prefer options[:raw_get_params] where possible to ensure compatibility with other SAML implementations.

Upgrading from 1.4.2 to 1.4.3

Version 1.4.3 introduces Recipient validation of SubjectConfirmation elements. The 'Recipient' value is compared with the settings.assertion_consumer_service_url value.

If you want to skip that validation, add the :skip_recipient_check option to the initialize method of the Response object.

Parsing metadata that contains more than one certificate will propagate the idp_cert_multi property rather than idp_cert. See signature validation section for details.

Upgrading from 1.3.x to 1.4.x

Version 1.4.0 is a recommended update for all Ruby SAML users as it includes security improvements.

Upgrading from 1.2.x to 1.3.x

Version 1.3.0 is a recommended update for all Ruby SAML users as it includes security fixes. It adds security improvements in order to prevent Signature wrapping attacks. CVE-2016-5697

Upgrading from 1.1.x to 1.2.x

Version 1.2 adds IDP metadata parsing improvements, uuid deprecation in favour of SecureRandom, refactor error handling and some minor improvements.

There is no compatibility issue detected.

For more details, please review CHANGELOG.md.

Upgrading from 1.0.x to 1.1.x

Version 1.1 adds some improvements on signature validation and solves some namespace conflicts.

Upgrading from 0.9.x to 1.0.x

Version 1.0 is a recommended update for all Ruby SAML users as it includes security fixes.

Version 1.0 adds security improvements like entity expansion limitation, more SAML message validations, and other important improvements like decrypt support.

Important Changes

Please note the get_idp_metadata method raises an exception when it is not able to fetch the idp metadata, so review your integration if you are using this functionality.

Upgrading from 0.8.x to 0.9.x

Version 0.9 adds many new features and improvements.

Upgrading from 0.7.x to 0.8.x

Version 0.8.x changes the namespace of the gem from OneLogin::Saml to OneLogin::RubySaml. Please update your implementations of the gem accordingly.