ruby-saml 1.12.4 → 1.18.1

data/README.md

@@ -1,169 +1,109 @@
-# Ruby SAML [![Build Status](https://secure.travis-ci.org/onelogin/ruby-saml.svg)](http://travis-ci.org/onelogin/ruby-saml) [![Coverage Status](https://coveralls.io/repos/onelogin/ruby-saml/badge.svg?branch=master)](https://coveralls.io/r/onelogin/ruby-saml?branch=master)
+# Ruby SAML
+[![ruby-saml CI](https://github.com/SAML-Toolkits/ruby-saml/actions/workflows/test.yml/badge.svg)](https://github.com/SAML-Toolkits/ruby-saml/actions/workflows/test.yml)
+[![Coverage Status](https://coveralls.io/repos/github/SAML-Toolkits/ruby-saml/badge.svg?branch=master)](https://coveralls.io/github/SAML-Toolkits/ruby-saml?branch=master)
+[![Rubygem Version](https://badge.fury.io/rb/ruby-saml.svg)](https://badge.fury.io/rb/ruby-saml)
+[![GitHub version](https://badge.fury.io/gh/SAML-Toolkits%2Fruby-saml.svg)](https://badge.fury.io/gh/SAML-Toolkits%2Fruby-saml) ![GitHub](https://img.shields.io/github/license/SAML-Toolkits/ruby-saml) ![Gem](https://img.shields.io/gem/dtv/ruby-saml?label=gem%20downloads%20latest) ![Gem](https://img.shields.io/gem/dt/ruby-saml?label=gem%20total%20downloads)
 
-## Updating 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
+Minor and patch versions of Ruby SAML may introduce breaking changes. Please read
+[UPGRADING.md](UPGRADING.md) for guidance on upgrading to new Ruby SAML versions.
 
-`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`.
-In 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).
+### Pay it Forward: Support RubySAML and Strengthen Open-Source Security
 
-## Updating 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.
+RubySAML is a trusted authentication library used by startups and enterprises alike.
 
-Version `1.10.2` includes the `valid_until` attribute in parsed IdP metadata.
+But security doesn't happen in a vacuum. Vulnerabilities in authentication libraries can
+have widespread consequences. Maintaining open-source security requires continuous
+effort, expertise, and funding. By supporting RubySAML, you’re not just securing your
+own systems—you’re strengthening auth security globally.
 
-Version `1.10.1` improves Ruby 1.8.7 support.
+#### How you can help
 
-## Updating 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/
+* Sponsor RubySAML: [GitHub Sponsors](https://github.com/sponsors/SAML-Toolkits)
+* Contribute to secure-by-design improvements
+* Responsibly report vulnerabilities (see "Vulnerability Reporting" above)
 
-## Updating 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.
+Security is a shared responsibility. If RubySAML has helped your organization, please
+consider giving back. Together, we can keep authentication secure.
 
-## Updating 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.
+### Sponsors
 
-## Updating from 1.6.0 to 1.7.0
+Thanks to the following sponsors for securing the open source ecosystem,
 
-Version `1.7.0` is a recommended update for all Ruby SAML users as it includes a fix for the [CVE-2017-11428](https://www.cvedetails.com/cve/CVE-2017-11428/) vulnerability.
+[<img alt="84codes" src="https://avatars.githubusercontent.com/u/5353257" width="75px">](https://www.84codes.com)
 
-## Updating 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.
+## Vulnerabilities
 
-The new preferred way to provide _SAMLResponse_, _RelayState_, and _SigAlg_ is via the `options[:raw_get_params]` parameter. For example:
+CVE-2025-54572 affects version ruby-saml < 1.18.1
 
-```ruby
-# 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.
-
-## Updating 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](#signature-validation) for details.
-
-## Updating 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.
 
-## Updating from 1.2.x to 1.3.X
+There are critical vulnerabilities affecting ruby-saml < 1.18.0, two of them allows SAML authentication bypass (CVE-2025-25291, CVE-2025-25292, CVE-2025-25293). Please upgrade to a fixed version (1.18.0)
 
-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](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2016-5697)
-
-## Updating 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 [the changelog](changelog.md).
-
-## Updating from 1.0.x to 1.1.X
-
-Version `1.1` adds some improvements on signature validation and solves some namespace conflicts.
-
-## Updating 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.
+## Overview
 
-Version `1.0` adds security improvements like entity expansion limitation, more SAML message validations, and other important improvements like decrypt support.
+The Ruby SAML library is for implementing the client side of a SAML authorization,
+i.e. it provides a means for managing authorization initialization and confirmation
+requests from identity providers.
 
-### 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.
+SAML authorization is a two-step process and you are expected to implement support for both.
 
-## Updating from 0.8.x to 0.9.x
-Version `0.9` adds many new features and improvements.
+We created a demo project for Rails 4 that uses the latest version of this library:
+[ruby-saml-example](https://github.com/saml-toolkits/ruby-saml-example)
 
-## Updating 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.
+### Supported Ruby Versions
 
-## Overview
+The following Ruby versions are covered by CI testing:
 
-The Ruby SAML library is for implementing the client side of a SAML authorization, i.e. it provides a means for managing authorization initialization and confirmation requests from identity providers.
-
-SAML authorization is a two step process and you are expected to implement support for both.
-
-We created a demo project for Rails4 that uses the latest version of this library: [ruby-saml-example](https://github.com/onelogin/ruby-saml-example)
-
-### Supported versions of Ruby
-* 1.8.7
-* 1.9.x
-* 2.0.x
-* 2.1.x
-* 2.2.x
-* 2.3.x
-* 2.4.x
-* 2.5.x
-* 2.6.x
-* 2.7.x
-* 3.0.x
-* JRuby 1.7.x
-* JRuby 9.0.x
-* JRuby 9.1.x
-* JRuby 9.2.x
+* Ruby (MRI) 2.1 to 3.4
+* JRuby 9.1 to 9.4
+* TruffleRuby (latest)
 
 ## Adding Features, Pull Requests
+
 * Fork the repository
 * Make your feature addition or bug fix
 * Add tests for your new features. This is important so we don't break any features in a future version unintentionally.
-* Ensure all tests pass.
-* Do not change rakefile, version, or history.
+* Ensure all tests pass by running `bundle exec rake test`.
+* Do not change Rakefile, version, or history.
 * Open a pull request, following [this template](https://gist.github.com/Lordnibbler/11002759).
 
 ## Security Guidelines
 
-If you believe you have discovered a security vulnerability in this gem, please report it at https://www.onelogin.com/security with a description. We follow responsible disclosure guidelines, and will work with you to quickly find a resolution.
+If you believe you have discovered a security vulnerability in this gem, please report it
+by mail to the maintainer: sixto.martin.garcia+security@gmail.com
 
-### Security warning
+### Security Warning
 
 Some tools may incorrectly report ruby-saml is a potential security vulnerability.
-ruby-saml depends on Nokogiri, and it's possible to use Nokogiri in a dangerous way
+ruby-saml depends on Nokogiri, and it is possible to use Nokogiri in a dangerous way
 (by enabling its DTDLOAD option and disabling its NONET option).
 This dangerous Nokogiri configuration, which is sometimes used by other components,
 can create an XML External Entity (XXE) vulnerability if the XML data is not trusted.
 However, ruby-saml never enables this dangerous Nokogiri configuration;
 ruby-saml never enables DTDLOAD, and it never disables NONET.
 
+The OneLogin::RubySaml::IdpMetadataParser class does not validate the provided URL before parsing.
+
+Usually, the same administrator who handles the Service Provider also sets the URL to
+the IdP, which should be a trusted resource.
+
+But there are other scenarios, like a SaaS app where the administrator of the app
+delegates this functionality to other users. In this case, extra precautions should
+be taken in order to validate such URL inputs and avoid attacks like SSRF.
 
 ## Getting Started
-In order to use the toolkit you will need to install the gem (either manually or using Bundler), and require the library in your Ruby application:
+
+In order to use Ruby SAML you will need to install the gem (either manually or using Bundler),
+and require the library in your Ruby application:
 
 Using `Gemfile`
 
 ```ruby
 # latest stable
-gem 'ruby-saml', '~> 1.11.0'
+gem 'ruby-saml', '~> 1.18.0'
 
 # or track master for bleeding-edge
-gem 'ruby-saml', :github => 'onelogin/ruby-saml'
+gem 'ruby-saml', :github => 'saml-toolkit/ruby-saml'
 ```
 
 Using RubyGems
@@ -172,7 +112,8 @@ Using RubyGems
 gem install ruby-saml
 ```
 
-When requiring the gem, you can add the whole toolkit
+You may require the entire Ruby SAML gem:
+
 ```ruby
 require 'onelogin/ruby-saml'
 ```
@@ -185,7 +126,9 @@ require 'onelogin/ruby-saml/authrequest'
 
 ### Installation on Ruby 1.8.7
 
-This gem uses Nokogiri as a dependency, which dropped support for Ruby 1.8.x in Nokogiri 1.6. When installing this gem on Ruby 1.8.7, you will need to make sure a version of Nokogiri prior to 1.6 is installed or specified if it hasn't been already.
+This gem uses Nokogiri as a dependency, which dropped support for Ruby 1.8.x in Nokogiri 1.6.
+When installing this gem on Ruby 1.8.7, you will need to make sure a version of Nokogiri
+prior to 1.6 is installed or specified if it hasn't been already.
 
 Using `Gemfile`
 
@@ -202,8 +145,8 @@ gem install nokogiri --version '~> 1.5.10'
 ### Configuring Logging
 
 When troubleshooting SAML integration issues, you will find it extremely helpful to examine the
-output of this gem's business logic. By default, log messages are emitted to RAILS_DEFAULT_LOGGER
-when the gem is used in a Rails context, and to STDOUT when the gem is used outside of Rails.
+output of this gem's business logic. By default, log messages are emitted to `RAILS_DEFAULT_LOGGER`
+when the gem is used in a Rails context, and to `STDOUT` when the gem is used outside of Rails.
 
 To override the default behavior and control the destination of log messages, provide
 a ruby Logger object to the gem's logging singleton:
@@ -214,7 +157,10 @@ OneLogin::RubySaml::Logging.logger = Logger.new('/var/log/ruby-saml.log')
 
 ## The Initialization Phase
 
-This is the first request you will get from the identity provider. It will hit your application at a specific URL that you've announced as your SAML initialization point. The response to this initialization is a redirect back to the identity provider, which can look something like this (ignore the saml_settings method call for now):
+This is the first request you will get from the identity provider. It will hit your application
+at a specific URL that you've announced as your SAML initialization point. The response to
+this initialization is a redirect back to the identity provider, which can look something
+like this (ignore the saml_settings method call for now):
 
 ```ruby
 def init
@@ -223,7 +169,7 @@ def init
 end
 ```
 
-If the SP knows who should be authenticated in the IdP, then can provide that info as follows:
+If the SP knows who should be authenticated in the IdP, it can provide that info as follows:
 
 ```ruby
 def init
@@ -234,7 +180,10 @@ def init
 end
 ```
 
-Once you've redirected back to the identity provider, it will ensure that the user has been authorized and redirect back to your application for final consumption. This can look something like this (the `authorize_success` and `authorize_failure` methods are specific to your application):
+Once you've redirected back to the identity provider, it will ensure that the user has been
+authorized and redirect back to your application for final consumption.
+This can look something like this (the `authorize_success` and `authorize_failure`
+methods are specific to your application):
 
 ```ruby
 def consume
@@ -252,16 +201,19 @@ def consume
 end
 ```
 
-In the above there are a few assumptions, one being that `response.nameid` is an email address. This is all handled with how you specify the settings that are in play via the `saml_settings` method. That could be implemented along the lines of this:
+In the above there are a few assumptions, one being that `response.nameid` is an email address.
+This is all handled with how you specify the settings that are in play via the `saml_settings` method.
+That could be implemented along the lines of this:
 
 ```
 response = OneLogin::RubySaml::Response.new(params[:SAMLResponse])
 response.settings = saml_settings
 ```
 
-If the assertion of the SAMLResponse is not encrypted, you can initialize the Response without the `:settings` parameter and set it later.
-If the SAMLResponse contains an encrypted assertion, you need to provide the settings in the
-initialize method in order to obtain the decrypted assertion, using the service provider private key in order to decrypt.
+If the assertion of the SAMLResponse is not encrypted, you can initialize the Response
+without the `:settings` parameter and set it later. If the SAMLResponse contains an encrypted
+assertion, you need to provide the settings in the initialize method in order to obtain the
+decrypted assertion, using the service provider private key in order to decrypt.
 If you don't know what expect, always use the former (set the settings on initialize).
 
 ```ruby
@@ -271,8 +223,10 @@ def saml_settings
   settings.assertion_consumer_service_url = "http://#{request.host}/saml/consume"
   settings.sp_entity_id                   = "http://#{request.host}/saml/metadata"
   settings.idp_entity_id                  = "https://app.onelogin.com/saml/metadata/#{OneLoginAppId}"
-  settings.idp_sso_service_url             = "https://app.onelogin.com/trust/saml2/http-post/sso/#{OneLoginAppId}"
-  settings.idp_slo_service_url             = "https://app.onelogin.com/trust/saml2/http-redirect/slo/#{OneLoginAppId}"
+  settings.idp_sso_service_url            = "https://app.onelogin.com/trust/saml2/http-post/sso/#{OneLoginAppId}"
+  settings.idp_sso_service_binding        = "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" # or :post, :redirect
+  settings.idp_slo_service_url            = "https://app.onelogin.com/trust/saml2/http-redirect/slo/#{OneLoginAppId}"
+  settings.idp_slo_service_binding        = "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" # or :post, :redirect
   settings.idp_cert_fingerprint           = OneLoginAppCertFingerPrint
   settings.idp_cert_fingerprint_algorithm = "http://www.w3.org/2000/09/xmldsig#sha1"
   settings.name_identifier_format         = "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"
@@ -285,27 +239,30 @@ def saml_settings
     "urn:oasis:names:tc:SAML:2.0:ac:classes:Password"
   ]
 
-  # Optional bindings (defaults to Redirect for logout POST for acs)
-  settings.single_logout_service_binding      = "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
-  settings.assertion_consumer_service_binding = "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
+  # Optional bindings (defaults to Redirect for logout POST for ACS)
+  settings.single_logout_service_binding      = "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" # or :post, :redirect
+  settings.assertion_consumer_service_binding = "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" # or :post, :redirect
 
   settings
 end
 ```
 
-The use of settings.issuer is deprecated in favour of settings.sp_entity_id since version 1.11.0
+The use of `settings.issuer` is deprecated in favor of `settings.sp_entity_id` since version 1.11.0
 
-Some assertion validations can be skipped by passing parameters to `OneLogin::RubySaml::Response.new()`.  For example, you can skip the `AuthnStatement`, `Conditions`, `Recipient`, or the `SubjectConfirmation` validations by initializing the response with different options:
+Some assertion validations can be skipped by passing parameters to `OneLogin::RubySaml::Response.new()`.
+For example, you can skip the `AuthnStatement`, `Conditions`, `Recipient`, or the `SubjectConfirmation`
+validations by initializing the response with different options:
 
 ```ruby
 response = OneLogin::RubySaml::Response.new(params[:SAMLResponse], {skip_authnstatement: true}) # skips AuthnStatement
 response = OneLogin::RubySaml::Response.new(params[:SAMLResponse], {skip_conditions: true}) # skips conditions
 response = OneLogin::RubySaml::Response.new(params[:SAMLResponse], {skip_subject_confirmation: true}) # skips subject confirmation
-response = OneLogin::RubySaml::Response.new(params[:SAMLResponse], {skip_recipient_check: true}) # doens't skip subject confirmation, but skips the recipient check which is a sub check of the subject_confirmation check
+response = OneLogin::RubySaml::Response.new(params[:SAMLResponse], {skip_recipient_check: true}) # doesn't skip subject confirmation, but skips the recipient check which is a sub check of the subject_confirmation check
 response = OneLogin::RubySaml::Response.new(params[:SAMLResponse], {skip_audience: true}) # skips audience check
 ```
 
-All that's left is to wrap everything in a controller and reference it in the initialization and consumption URLs in OneLogin. A full controller example could look like this:
+All that's left is to wrap everything in a controller and reference it in the initialization and
+consumption URLs in OneLogin. A full controller example could look like this:
 
 ```ruby
 # This controller expects you to use the URLs /saml/init and /saml/consume in your OneLogin application.
@@ -358,44 +315,56 @@ class SamlController < ApplicationController
 end
 ```
 
+## Signature Validation
 
-## Signature validation
+Ruby SAML allows different ways to validate the signature of the SAMLResponse:
+- You can provide the IdP X.509 public certificate at the `idp_cert` setting.
+- You can provide the IdP X.509 public certificate in fingerprint format using the
+ `idp_cert_fingerprint` setting parameter and additionally the `idp_cert_fingerprint_algorithm` parameter.
 
-On the ruby-saml toolkit there are different ways to validate the signature of the SAMLResponse:
-- You can provide the IdP x509 public certificate at the 'idp_cert' setting.
-- You can provide the IdP x509 public certificate in fingerprint format using the 'idp_cert_fingerprint' setting parameter and additionally the 'idp_cert_fingerprint_algorithm' parameter.
+When validating the signature of redirect binding, the fingerprint is useless and the certificate
+of the IdP is required in order to execute the validation. You can pass the option
+`:relax_signature_validation` to `SloLogoutrequest` and `Logoutresponse` if want to avoid signature
+validation if no certificate of the IdP is provided.
 
-When validating the signature of redirect binding, the fingerprint is useless and the certficate of the IdP is required in order to execute the validation.
-You can pass the option :relax_signature_validation to SloLogoutrequest and Logoutresponse if want to avoid signature validation if no certificate of the IdP is provided.
+In production also we highly recommend to register on the settings the IdP certificate instead
+of using the fingerprint method. The fingerprint, is a hash, so at the end is open to a collision
+attack that can end on a signature validation bypass. Other SAML toolkits deprecated that mechanism,
+we maintain it for compatibility and also to be used on test environment.
 
-In production also we highly recommend to register on the settings the IdP certificate instead of using the fingerprint method. The fingerprint, is a hash, so at the end is open to a collision attack that can end on a signature validation bypass. Other SAML toolkits deprecated that mechanism, we maintain it for compatibility and also to be used on test environment.
+## Handling Multiple IdP Certificates
 
-In some scenarios the IdP uses different certificates for signing/encryption, or is under key rollover phase and more than one certificate is published on IdP metadata.
+If the IdP metadata XML includes multiple certificates, you may specify the `idp_cert_multi`
+parameter. When used, the `idp_cert` and `idp_cert_fingerprint` parameters are ignored.
+This is useful in the following scenarios:
 
-In order to handle that the toolkit offers the 'idp_cert_multi' parameter.
-When used, 'idp_cert' and 'idp_cert_fingerprint' values are ignored.
+* The IdP uses different certificates for signing versus encryption.
+* The IdP is undergoing a key rollover and is publishing the old and new certificates in parallel.
 
-That 'idp_cert_multi' must be a Hash as follows:
+The `idp_cert_multi` must be a `Hash` as follows. The `:signing` and `:encryption` arrays below,
+add the IdP X.509 public certificates which were published in the IdP metadata.
+
+```ruby
 {
   :signing => [],
   :encryption => []
 }
-
-And on 'signing' and 'encryption' arrays, add the different IdP x509 public certificates published on the IdP metadata.
-
+```
 
 ## Metadata Based Configuration
 
-The method above requires a little extra work to manually specify attributes about the IdP.  (And your SP application)  There's an easier method -- use a metadata exchange.  Metadata is just an XML file that defines the capabilities of both the IdP and the SP application.  It also contains the X.509 public
-key certificates which add to the trusted relationship.  The IdP administrator can also configure custom settings for an SP based on the metadata.
+The method above requires a little extra work to manually specify attributes about both the IdP and your SP application.
+There's an easier method: use a metadata exchange. Metadata is an XML file that defines the capabilities of both the IdP
+and the SP application. It also contains the X.509 public key certificates which add to the trusted relationship.
+The IdP administrator can also configure custom settings for an SP based on the metadata.
 
-Using ```idp_metadata_parser.parse_remote``` IdP metadata will be added to the settings without further ado.
+Using `IdpMetadataParser#parse_remote`, the IdP metadata will be added to the settings.
 
 ```ruby
 def saml_settings
 
   idp_metadata_parser = OneLogin::RubySaml::IdpMetadataParser.new
-  # Returns OneLogin::RubySaml::Settings prepopulated with idp metadata
+  # Returns OneLogin::RubySaml::Settings pre-populated with IdP metadata
   settings = idp_metadata_parser.parse_remote("https://example.com/auth/saml2/idp/metadata")
 
   settings.assertion_consumer_service_url = "http://#{request.host}/saml/consume"
@@ -407,6 +376,7 @@ def saml_settings
   settings
 end
 ```
+
 The following attributes are set:
   * idp_entity_id
   * name_identifier_format
@@ -425,11 +395,32 @@ IdpMetadataParser by its Entity Id value:
 
 ```ruby
   validate_cert = true
-  settings =  idp_metadata_parser.parse_remote(
-                "https://example.com/auth/saml2/idp/metadata",
-                validate_cert,
-                entity_id: "http//example.com/target/entity"
-              )
+  settings = idp_metadata_parser.parse_remote(
+               "https://example.com/auth/saml2/idp/metadata",
+               validate_cert,
+               entity_id: "http//example.com/target/entity"
+             )
+```
+
+### Retrieve one Entity Descriptor with a specific binding and nameid format when several are available
+
+If the metadata contains multiple bindings and NameID formats, the relevant ones
+can be specified when retrieving the settings from the IdpMetadataParser
+by the values of binding and NameID:
+
+```ruby
+  validate_cert = true
+  options = {
+    entity_id: "http//example.com/target/entity",
+    name_id_format: "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
+    sso_binding: "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST",
+    slo_binding: "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
+  }
+  settings = idp_metadata_parser.parse_remote(
+               "https://example.com/auth/saml2/idp/metadata",
+               validate_cert,
+               options
+             )
 ```
 
 ### Parsing Metadata into an Hash
@@ -438,13 +429,58 @@ The `OneLogin::RubySaml::IdpMetadataParser` also provides the methods `#parse_to
 Those return an Hash instead of a `Settings` object, which may be useful for configuring
 [omniauth-saml](https://github.com/omniauth/omniauth-saml), for instance.
 
+
+### Validating Signature of Metadata and retrieve settings
+
+Right now there is no method at ruby_saml to validate the signature of the metadata that gonna be parsed,
+but it can be done as follows:
+* Download the XML.
+* Validate the Signature, providing the cert.
+* Provide the XML to the parse method if the signature was validated
+
+```ruby
+require "xml_security"
+require "onelogin/ruby-saml/utils"
+require "onelogin/ruby-saml/idp_metadata_parser"
+
+url = "<url_to_the_metadata>"
+idp_metadata_parser = OneLogin::RubySaml::IdpMetadataParser.new
+
+uri = URI.parse(url)
+raise ArgumentError.new("url must begin with http or https") unless /^https?/ =~ uri.scheme
+http = Net::HTTP.new(uri.host, uri.port)
+if uri.scheme == "https"
+    http.use_ssl = true
+    http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+end
+
+get = Net::HTTP::Get.new(uri.request_uri)
+get.basic_auth uri.user, uri.password if uri.user
+response = http.request(get)
+xml = response.body
+errors = []
+doc = XMLSecurity::SignedDocument.new(xml, errors)
+cert_str = "<include_cert_here>"
+cert = OneLogin::RubySaml::Utils.format_cert("cert_str")
+metadata_sign_cert = OpenSSL::X509::Certificate.new(cert)
+valid = doc.validate_document_with_cert(metadata_sign_cert, true)
+if valid
+  settings = idp_metadata_parser.parse(
+    xml,
+    entity_id: "<entity_id_of_the_entity_to_be_retrieved>"
+  )
+else
+  print "Metadata Signature failed to be verified with the cert provided"
+end
+```
+
 ## Retrieving Attributes
 
-If you are using `saml:AttributeStatement` to transfer data like the username, you can access all the attributes through `response.attributes`. It contains all the `saml:AttributeStatement`s with its 'Name' as an indifferent key and one or more `saml:AttributeValue`s as values. The value returned depends on the value of the
+If you are using `saml:AttributeStatement` to transfer data, such as the username, you can access all the attributes through `response.attributes`. It contains all the `saml:AttributeStatement`s with its 'Name' as an indifferent key and one or more `saml:AttributeValue`s as values. The value returned depends on the value of the
 `single_value_compatibility` (when activated, only the first value is returned)
 
 ```ruby
-response          = OneLogin::RubySaml::Response.new(params[:SAMLResponse])
+response = OneLogin::RubySaml::Response.new(params[:SAMLResponse])
 response.settings = saml_settings
 
 response.attributes[:username]
@@ -529,7 +565,7 @@ pp(response.attributes.multi(:not_exists))
 pp(response.attributes.fetch(/givenname/))
 # => "usersName"
 
-# Deactive single_value_compatibility
+# Deprecated single_value_compatibility
 OneLogin::RubySaml::Attributes.single_value_compatibility = false
 
 pp(response.attributes[:uid])
@@ -572,74 +608,212 @@ To add a `saml:AuthnContextDeclRef`, define `settings.authn_context_decl_ref`.
 In a SP-initiated flow, the SP can indicate to the IdP the subject that should be authenticated. This is done by defining the `settings.name_identifier_value_requested` before
 building the authrequest object.
 
+## Service Provider Metadata
 
-## Signing
+To form a trusted pair relationship with the IdP, the SP (you) need to provide metadata XML
+to the IdP for various good reasons. (Caching, certificate lookups, relaying party permissions, etc)
 
-The Ruby Toolkit supports 2 different kinds of signature: Embeded and `GET` parameters
+The class `OneLogin::RubySaml::Metadata` takes care of this by reading the Settings and returning XML.  All you have to do is add a controller to return the data, then give this URL to the IdP administrator.
 
-In order to be able to sign, define the private key and the public cert of the service provider:
+The metadata will be polled by the IdP every few minutes, so updating your settings should propagate
+to the IdP settings.
 
 ```ruby
-  settings.certificate = "CERTIFICATE TEXT WITH HEAD AND FOOT"
-  settings.private_key = "PRIVATE KEY TEXT WITH HEAD AND FOOT"
+class SamlController < ApplicationController
+  # ... the rest of your controller definitions ...
+  def metadata
+    settings = Account.get_saml_settings
+    meta = OneLogin::RubySaml::Metadata.new
+    render :xml => meta.generate(settings), :content_type => "application/samlmetadata+xml"
+  end
+end
 ```
 
-The settings related to sign are stored in the `security` attribute of the settings:
+You can add `ValidUntil` and `CacheDuration` to the SP Metadata XML using instead:
 
 ```ruby
-  settings.security[:authn_requests_signed]   = true     # Enable or not signature on AuthNRequest
-  settings.security[:logout_requests_signed]  = true     # Enable or not signature on Logout Request
-  settings.security[:logout_responses_signed] = true     # Enable or not signature on Logout Response
-  settings.security[:want_assertions_signed]  = true     # Enable or not the requirement of signed assertion
-  settings.security[:metadata_signed]         = true     # Enable or not signature on Metadata
+  # Valid until => 2 days from now
+  # Cache duration = 604800s = 1 week
+  valid_until = Time.now + 172800
+  cache_duration = 604800
+  meta.generate(settings, false, valid_until, cache_duration)
+```
+
+## Signing and Decryption
+
+Ruby SAML supports the following functionality:
+
+1. Signing your SP Metadata XML
+2. Signing your SP SAML messages
+3. Decrypting IdP Assertion messages upon receipt (EncryptedAssertion)
+4. Verifying signatures on SAML messages and IdP Assertions
+
+In order to use functions 1-3 above, you must first define your SP public certificate and private key:
+
+```ruby
+  settings.certificate = "CERTIFICATE TEXT WITH BEGIN/END HEADER AND FOOTER"
+  settings.private_key = "PRIVATE KEY TEXT WITH BEGIN/END HEADER AND FOOTER"
+```
+
+Note that the same certificate (and its associated private key) are used to perform
+all decryption and signing-related functions (1-4) above. Ruby SAML does not currently allow
+to specify different certificates for each function.
 
+You may also globally set the SP signature and digest method, to be used in SP signing (functions 1 and 2 above):
+
+```ruby
   settings.security[:digest_method]    = XMLSecurity::Document::SHA1
   settings.security[:signature_method] = XMLSecurity::Document::RSA_SHA1
+```
+
+#### Signing SP Metadata
+
+You may add a `<ds:Signature>` digital signature element to your SP Metadata XML using the following setting:
+
+```ruby
+  settings.certificate = "CERTIFICATE TEXT WITH BEGIN/END HEADER AND FOOTER"
+  settings.private_key = "PRIVATE KEY TEXT WITH BEGIN/END HEADER AND FOOTER"
 
-  # Embeded signature or HTTP GET parameter signature
-  # Note that metadata signature is always embedded regardless of this value.
-  settings.security[:embed_sign] = false
-  settings.security[:check_idp_cert_expiration] = false   # Enable or not IdP x509 cert expiration check
-  settings.security[:check_sp_cert_expiration] = false   # Enable or not SP x509 cert expiration check
+  settings.security[:metadata_signed] = true # Enable signature on Metadata
 ```
 
-Notice that the RelayState parameter is used when creating the Signature on the HTTP-Redirect Binding.
+#### Signing SP SAML Messages
+
+Ruby SAML supports SAML request signing. The Service Provider will sign the
+request/responses with its private key. The Identity Provider will then validate the signature
+of the received request/responses with the public X.509 cert of the Service Provider.
+
+To enable, please first set your certificate and private key. This will add `<md:KeyDescriptor use="signing">`
+to your SP Metadata XML, to be read by the IdP.
+
+```ruby
+  settings.certificate = "CERTIFICATE TEXT WITH BEGIN/END HEADER AND FOOTER"
+  settings.private_key = "PRIVATE KEY TEXT WITH BEGIN/END HEADER AND FOOTER"
+```
+
+Next, you may specify the specific SP SAML messages you would like to sign:
+
+```ruby
+  settings.security[:authn_requests_signed]   = true  # Enable signature on AuthNRequest
+  settings.security[:logout_requests_signed]  = true  # Enable signature on Logout Request
+  settings.security[:logout_responses_signed] = true  # Enable signature on Logout Response
+```
+
+Signatures will be handled automatically for both `HTTP-Redirect` and `HTTP-POST` Binding.
+Note that the RelayState parameter is used when creating the Signature on the `HTTP-Redirect` Binding.
 Remember to provide it to the Signature builder if you are sending a `GET RelayState` parameter or the
 signature validation process will fail at the Identity Provider.
 
-The Service Provider will sign the request/responses with its private key.
-The Identity Provider will validate the sign of the received request/responses with the public x509 cert of the
-Service Provider.
+#### Decrypting IdP SAML Assertions
 
-Notice that this toolkit uses 'settings.certificate' and 'settings.private_key' for the sign and decrypt processes.
+Ruby SAML supports EncryptedAssertion. The Identity Provider will encrypt the Assertion with the
+public cert of the Service Provider. The Service Provider will decrypt the EncryptedAssertion with its private key.
 
-Enable/disable the soft mode with the `settings.soft` parameter. When set to `false`, saml validations errors will raise an exception.
+You may enable EncryptedAssertion as follows. This will add `<md:KeyDescriptor use="encryption">` to your
+SP Metadata XML, to be read by the IdP.
 
-## Decrypting
+```ruby
+  settings.certificate = "CERTIFICATE TEXT WITH BEGIN/END HEADER AND FOOTER"
+  settings.private_key = "PRIVATE KEY TEXT WITH BEGIN/END HEADER AND FOOTER"
 
-The Ruby Toolkit supports EncryptedAssertion.
+  settings.security[:want_assertions_encrypted] = true # Invalidate SAML messages without an EncryptedAssertion
+```
+
+#### Verifying Signature on IdP Assertions
 
-In order to be able to decrypt a SAML Response that contains a EncryptedAssertion you need define the private key and the public cert of the service provider, then share this with the Identity Provider.
+You may require the IdP to sign its SAML Assertions using the following setting.
+With will add `<md:SPSSODescriptor WantAssertionsSigned="true">` to your SP Metadata XML.
+The signature will be checked against the `<md:KeyDescriptor use="signing">` element
+present in the IdP's metadata.
 
 ```ruby
-  settings.certificate = "CERTIFICATE TEXT WITH HEAD AND FOOT"
-  settings.private_key = "PRIVATE KEY TEXT WITH HEAD AND FOOT"
+  settings.security[:want_assertions_signed]  = true  # Require the IdP to sign its SAML Assertions
 ```
 
-The Identity Provider will encrypt the Assertion with the public cert of the Service Provider.
-The Service Provider will decrypt the EncryptedAssertion with its private key.
+#### Certificate and Signature Validation
+
+You may require SP and IdP certificates to be non-expired using the following settings:
+
+```ruby
+  settings.security[:check_idp_cert_expiration] = true  # Raise error if IdP X.509 cert is expired
+  settings.security[:check_sp_cert_expiration] = true   # Raise error SP X.509 cert is expired
+```
 
-Notice that this toolkit uses 'settings.certificate' and 'settings.private_key' for the sign and decrypt processes.
+By default, Ruby SAML will raise a `OneLogin::RubySaml::ValidationError` if a signature or certificate
+validation fails. You may disable such exceptions using the `settings.security[:soft]` parameter.
 
+```ruby
+  settings.security[:soft] = true  # Do not raise error on failed signature/certificate validations
+```
 
-## Key rollover
+#### Advanced SP Certificate Usage & Key Rollover
 
-If you plan to update the SP x509cert and privateKey you can define the parameter 'certificate_new' at the settings and that new SP public certificate will be published on the SP metadata so Identity Providers can read them and get ready for rollover.
+Ruby SAML provides the `settings.sp_cert_multi` parameter to enable the following
+advanced usage scenarios:
+- Rotating SP certificates and private keys without disruption of service.
+- Specifying separate SP certificates for signing and encryption.
 
+The `sp_cert_multi` parameter replaces `certificate` and `private_key`
+(you may not specify both pparameters at the same time.) `sp_cert_multi` has the following shape:
+
+```ruby
+settings.sp_cert_multi = {
+  signing: [
+    { certificate: cert1, private_key: private_key1 },
+    { certificate: cert2, private_key: private_key2 }
+  ],
+  encryption: [
+    { certificate: cert1, private_key: private_key1 },
+    { certificate: cert3, private_key: private_key1 }
+  ],
+}
+```
+
+Certificate rotation is acheived by inserting new certificates at the bottom of each list,
+and then removing the old certificates from the top of the list once your IdPs have migrated.
+A common practice is for apps to publish the current SP metadata at a URL endpoint and have
+the IdP regularly poll for updates.
+
+Note the following:
+- You may re-use the same certificate and/or private key in multiple places, including for both signing and encryption.
+- The IdP should attempt to verify signatures with *all* `:signing` certificates,
+  and permit if *any one* succeeds. When signing, Ruby SAML will use the first SP certificate
+  in the `sp_cert_multi[:signing]` array. This will be the first active/non-expired certificate
+  in the array if `settings.security[:check_sp_cert_expiration]` is true.
+- The IdP may encrypt with any of the SP certificates in the `sp_cert_multi[:encryption]`
+  array. When decrypting, Ruby SAML attempt to decrypt with each SP private key in
+  `sp_cert_multi[:encryption]` until the decryption is successful. This will skip private
+  keys for inactive/expired certificates if `:check_sp_cert_expiration` is true.
+- If `:check_sp_cert_expiration` is true, the generated SP metadata XML will not include
+  inactive/expired certificates. This avoids validation errors when the IdP reads the SP
+  metadata.
+
+#### Audience Validation
+
+A service provider should only consider a SAML response valid if the IdP includes an <AudienceRestriction>
+element containing an <Audience> element that uniquely identifies the service provider. Unless you specify
+the `skip_audience` option, Ruby SAML will validate that each SAML response includes an <Audience> element
+whose contents matches `settings.sp_entity_id`.
+
+By default, Ruby SAML considers an <AudienceRestriction> element containing only empty <Audience> elements
+to be valid. That means an otherwise valid SAML response with a condition like this would be valid:
+
+```xml
+<AudienceRestriction>
+  <Audience />
+</AudienceRestriction>
+```
+
+You may enforce that an <AudienceRestriction> element containing only empty <Audience> elements
+is invalid using the `settings.security[:strict_audience_validation]` parameter.
+
+```ruby
+settings.security[:strict_audience_validation] = true
+```
 
 ## Single Log Out
 
-The Ruby Toolkit supports SP-initiated Single Logout and IdP-Initiated Single Logout.
+Ruby SAML supports SP-initiated Single Logout and IdP-Initiated Single Logout.
 
 Here is an example that we could add to our previous controller to generate and send a SAML Logout Request to the IdP:
 
@@ -654,7 +828,7 @@ def sp_logout_request
     delete_session
   else
 
-    logout_request = OneLogin::RubySaml::Logoutrequest.new()
+    logout_request = OneLogin::RubySaml::Logoutrequest.new
     logger.info "New SP SLO for userid '#{session[:userid]}' transactionid '#{logout_request.uuid}'"
 
     if settings.name_identifier_value.nil?
@@ -670,7 +844,7 @@ def sp_logout_request
     session[:transaction_id] = logout_request.uuid
     session[:logged_out_user] = logged_user
 
-    relayState =  url_for controller: 'saml', action: 'index'
+    relayState = url_for(controller: 'saml', action: 'index')
     redirect_to(logout_request.create(settings, :RelayState => relayState))
   end
 end
@@ -717,7 +891,13 @@ Here is an example that we could add to our previous controller to process a SAM
 # Method to handle IdP initiated logouts
 def idp_logout_request
   settings = Account.get_saml_settings
-  logout_request = OneLogin::RubySaml::SloLogoutrequest.new(params[:SAMLRequest])
+  # ADFS URL-Encodes SAML data as lowercase, and the toolkit by default uses
+  # uppercase. Turn it True for ADFS compatibility on signature verification
+  settings.security[:lowercase_url_encoding] = true
+
+  logout_request = OneLogin::RubySaml::SloLogoutrequest.new(
+    params[:SAMLRequest], settings: settings
+  )
   if !logout_request.is_valid?
     logger.error "IdP initiated LogoutRequest was not valid!"
     return render :inline => logger.error
@@ -752,38 +932,6 @@ def logout
 end
 ```
 
-
-
-## Service Provider Metadata
-
-To form a trusted pair relationship with the IdP, the SP (you) need to provide metadata XML
-to the IdP for various good reasons.  (Caching, certificate lookups, relaying party permissions, etc)
-
-The class `OneLogin::RubySaml::Metadata` takes care of this by reading the Settings and returning XML.  All you have to do is add a controller to return the data, then give this URL to the IdP administrator.
-
-The metadata will be polled by the IdP every few minutes, so updating your settings should propagate
-to the IdP settings.
-
-```ruby
-class SamlController < ApplicationController
-  # ... the rest of your controller definitions ...
-  def metadata
-    settings = Account.get_saml_settings
-    meta = OneLogin::RubySaml::Metadata.new
-    render :xml => meta.generate(settings), :content_type => "application/samlmetadata+xml"
-  end
-end
-```
-
-You can add ValidUntil and CacheDuration to the XML Metadata using instead
-```ruby
-  # Valid until => 2 days from now
-  # Cache duration = 604800s = 1 week
-  valid_until = Time.now + 172800
-  cache_duration = 604800
-  meta.generate(settings, false, valid_until, cache_duration)
-```
-
 ## Clock Drift
 
 Server clocks tend to drift naturally. If during validation of the response you get the error "Current time is earlier than NotBefore condition", this may be due to clock differences between your system and that of the Identity Provider.
@@ -798,13 +946,33 @@ response = OneLogin::RubySaml::Response.new(params[:SAMLResponse], :allowed_cloc
 
 Make sure to keep the value as comfortably small as possible to keep security risks to a minimum.
 
+## Deflation Limit
+
+To protect against decompression bombs (a form of DoS attack), SAML messages are limited to 250,000 bytes by default.
+Sometimes legitimate SAML messages will exceed this limit,
+for example due to custom claims like including groups a user is a member of.
+If you want to customize this limit, you need to provide a different setting when initializing the response object.
+Example:
+
+```ruby
+def consume
+  response = OneLogin::RubySaml::Response.new(params[:SAMLResponse], { settings: saml_settings })
+  ...
+end
+
+private
+
+def saml_settings
+  OneLogin::RubySaml::Settings.new(message_max_bytesize: 500_000)
+end
+```
+
 ## Attribute Service
 
-To request attributes from the IdP the SP needs to provide an attribute service within it's metadata and reference the index in the assertion.
+To request attributes from the IdP the SP must provide an attribute service within its metadata and reference the index in the assertion.
 
 ```ruby
 settings = OneLogin::RubySaml::Settings.new
-
 settings.attributes_index = 5
 settings.attribute_consuming_service.configure do
   service_name "Service"
@@ -815,3 +983,27 @@ end
 ```
 
 The `attribute_value` option additionally accepts an array of possible values.
+
+## Custom Metadata Fields
+
+Some IdPs may require SPs to add additional fields (Organization, ContactPerson, etc.)
+into the SP metadata. This can be achieved by extending the `OneLogin::RubySaml::Metadata`
+class and overriding the `#add_extras` method as per the following example:
+
+```ruby
+class MyMetadata < OneLogin::RubySaml::Metadata
+  def add_extras(root, _settings)
+    org = root.add_element("md:Organization")
+    org.add_element("md:OrganizationName", 'xml:lang' => "en-US").text = 'ACME Inc.'
+    org.add_element("md:OrganizationDisplayName", 'xml:lang' => "en-US").text = 'ACME'
+    org.add_element("md:OrganizationURL", 'xml:lang' => "en-US").text = 'https://www.acme.com'
+
+    cp = root.add_element("md:ContactPerson", 'contactType' => 'technical')
+    cp.add_element("md:GivenName").text = 'ACME SAML Team'
+    cp.add_element("md:EmailAddress").text = 'saml@acme.com'
+  end
+end
+
+# Output XML with custom metadata
+MyMetadata.new.generate(settings)
+```