6.5 KiB
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.