V2.x improvements

README.md

@@ -31,7 +31,7 @@ Response assertions from Identity Providers (IdPs).
 **Important:** This libary does not support the IdP-side of SAML authentication,
 such as creating SAML Response messages to assert a user's identity.
 
-A Rails 4 reference implemenation is avaiable at the
+A Rails 4 reference implementation is available at the
 [Ruby SAML Demo Project](https://github.com/saml-toolkits/ruby-saml-example).
 
 ### Vulnerability Reporting
@@ -46,9 +46,10 @@ it by email to the maintainer: [email protected]
   and from a trusted source. Ruby SAML does not perform any validation that the URL
   you entered is correct and/or safe.
 - **False-Positive Security Warnings:** Some tools may incorrectly report Ruby SAML as a
-  potential security vulnerability, due to it's dependency on Nokogiri. Such warnings can
+  potential security vulnerability, due to its dependency on Nokogiri. Such warnings can
   be ignored; Ruby SAML uses Nokogiri in a safe way, by always disabling its DTDLOAD option
   and enabling its NONET option.
+- **Prevent Replay attacks:** A replay attack is when an attacker intercepts a valid SAML assertion and "replays" it at a later time to gain unauthorized access. The `ruby-saml` library provides the tools to prevent this, but **you, the developer, must implement the core logic**, see an specific section later in the README.
 
 ### Supported Ruby Versions
 
@@ -179,7 +180,7 @@ def saml_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 `RubySaml::Response.new()`.
 For example, you can skip the `AuthnStatement`, `Conditions`, `Recipient`, or the `SubjectConfirmation`
@@ -255,13 +256,13 @@ Ruby SAML allows different ways to validate the signature of the SAML Response:
   `idp_cert_fingerprint` and `idp_cert_fingerprint_algorithm` parameters.
 
 In addition, you may pass the option `:relax_signature_validation` to `SloLogoutrequest` and
-`Logoutresponse` if want to skip signature validation on logout.
+`Logoutresponse` if you want to skip signature validation on logout.
 
 The `idp_cert_fingerprint` option is deprecated for the following reasons. It will be
 removed in Ruby SAML version 2.1.0.
 1. It only works with HTTP-POST binding, not HTTP-Redirect, since the full certificate
    is not sent in the Redirect URL parameters.
-2. It is theoretically be susceptible to collision attacks, by which a malicious
+2. It is theoretically susceptible to collision attacks, by which a malicious
    actor could impersonate the IdP. (However, as of January 2025, such attacks have not
    been publicly demonstrated for SHA-256.)
 3. It has been removed already from several other SAML libraries in other languages.
@@ -365,8 +366,7 @@ Those return an Hash instead of a `Settings` object, which may be useful for con
 
 ### 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:
+Right now there is no method at ruby_saml to validate the signature of the metadata that is going to 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
@@ -403,7 +403,7 @@ if valid
     entity_id: "<entity_id_of_the_entity_to_be_retrieved>"
   )
 else
-  print "Metadata Signarture failed to be verified with the cert provided"
+  print "Metadata Signature failed to be verified with the cert provided"
 end
 ```
 
@@ -632,7 +632,7 @@ settings.security[:logout_requests_signed]  = true  # Enable signature on Logout
 settings.security[:logout_responses_signed] = true  # Enable signature on Logout Response
 ```
 
-Signatures will be handled automatically for both `HTTP-Redirect` and `HTTP-Redirect` Binding.
+Signatures will be handled automatically for both `HTTP-POST` and `HTTP-Redirect` 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 IdP.
@@ -655,7 +655,7 @@ settings.security[:want_assertions_encrypted] = true # Invalidate SAML messages
 ### Verifying Signature on IdP Assertions
 
 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.
+This 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.
 
@@ -729,7 +729,7 @@ JRuby cannot support ECDSA due to a [known issue](https://github.com/jruby/jruby
 ### Audience Validation
 
 A service provider should only consider a SAML response valid if the IdP includes an <AudienceRestriction>
-element containting an <Audience> element that uniquely identifies the service provider. Unless you specify
+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`.
 
@@ -762,7 +762,7 @@ def sp_logout_request
   settings = saml_settings
 
   if settings.idp_slo_service_url.nil?
-    logger.info "SLO IdP Endpoint not found in settings, executing then a normal logout'"
+    logger.info "SLO IdP Endpoint not found in settings, then executing a normal logout'"
     delete_session
   else
 
@@ -936,7 +936,7 @@ or underscore, and can only contain letters, digits, underscores, hyphens, and p
 
 ### Custom Metadata Fields
 
-Some IdPs may require to add SPs to add additional fields (Organization, ContactPerson, etc.)
+Some IdPs may require SPs to add additional fields (Organization, ContactPerson, etc.)
 into the SP metadata. This can be done by extending the `RubySaml::Metadata` class and
 overriding the `#add_extras` method where the first arg is a
 [Nokogiri::XML::Builder](https://nokogiri.org/rdoc/Nokogiri/XML/Builder.html) object as per

UPGRADING.md

@@ -26,15 +26,23 @@ This issue is likely not critical for most IdPs, but since it is not tested, it
 
 ### Root "OneLogin" namespace changed to "RubySaml"
 
-RubySaml version `2.0.0` changes the root namespace from `RubySaml::` to just `RubySaml::`.
-Please remove `` and `onelogin/` everywhere in your codebase. Aside from this namespace change,
+RubySaml version `2.0.0` changes the root namespace from `OneLogin::RubySaml::` to just `RubySaml::`.
+Please remove `onelogin/` everywhere in your codebase. Aside from this namespace change,
 the class names themselves have intentionally been kept the same.
 
 Note that the project folder structure has also been updated accordingly. Notably, the directory
 `lib/onelogin/schemas` is now `lib/ruby_saml/schemas`.
 
-For backward compatibility, the alias `OneLogin = Object` has been set, so `RubySaml::` will still work
-as before. This alias will be removed in RubySaml version `3.0.0`.
+For backward compatibility, a module is defined at lib/ruby_saml.rb, so `RubySaml::` will still work
+as before. This module will be removed in RubySaml version `3.0.0`.
+```
+unless defined?(::OneLogin)
+    module OneLogin
+        RubySaml = ::RubySaml
+    end
+end
+```
+
 
 ### Deprecation and removal of "XMLSecurity" namespace
 
@@ -75,7 +83,7 @@ settings.security[:signature_method] = RubySaml::XML::RSA_SHA1
 
 RubySaml `1.x` used a combination of REXML and Nokogiri for XML parsing and generation.
 In `2.0.0`, REXML has been replaced with Nokogiri. As a result, there are minor differences
-in how XML is generated, ncluding SAML requests and SP Metadata: 
+in how XML is generated, including SAML requests and SP Metadata: 
 
 1. All XML namespace declarations will be on the root node of the XML. Previously,
    some declarations such as `xmlns:ds` were done on child nodes.
@@ -121,7 +129,7 @@ The reasons for this change are:
 ### Removal of embed_sign setting
 
 The deprecated `settings.security[:embed_sign]` parameter has been removed. If you were using it, please instead switch
-to using both the `settings.idp_sso_service_binding` and `settings.idp_slo_service_binding` parameters as show below.
+to using both the `settings.idp_sso_service_binding` and `settings.idp_slo_service_binding` parameters as shown below.
 (This new syntax is supported on version 1.13.0 and later.)
 
 ```ruby
@@ -231,7 +239,7 @@ when parsing a SAML Message (`settings.check_malformed_doc`).
 
 The SignedDocument class defined at xml_security.rb experienced several changes.
 We don't expect compatibilty issues if you use the main methods offered by ruby-saml, but if
-you use a fork or customized usage, is possible that you need to adapt your code.
+you use a fork or customized usage, it is possible that you will need to adapt your code.
 
 ## Upgrading from 1.12.x to 1.13.0
 
@@ -257,7 +265,7 @@ in favor of `idp_sso_service_url` and `idp_slo_service_url`. The `IdpMetadataPar
 
 ## 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`.
+Version `1.11.0` deprecates the use of `settings.issuer` in favor 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.
@@ -352,7 +360,7 @@ It adds security improvements in order to prevent Signature wrapping attacks.
 
 ## Upgrading from 1.1.x to 1.2.x
 
-Version `1.2` adds IDP metadata parsing improvements, uuid deprecation in favour of SecureRandom,
+Version `1.2` adds IDP metadata parsing improvements, uuid deprecation in favor of SecureRandom,
 refactor error handling and some minor improvements.
 
 There is no compatibility issue detected.
@@ -367,7 +375,7 @@ Version `1.1` adds some improvements on signature validation and solves some nam
 
 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.
+Version `1.0` adds security improvements like entity expansion limitation, more SAML message validations, and other important improvements like decryption support.
 
 ### Important Changes
 

lib/ruby_saml.rb

@@ -20,5 +20,17 @@
 require 'ruby_saml/utils'
 require 'ruby_saml/version'
 
-# @deprecated This alias adds compatibility with v1.x and will be removed in v3.0.0
-OneLogin = Object
+# @deprecated This module adds compatibility with v1.x and will be removed in v3.0.0
+unless defined?(::OneLogin)
+    module OneLogin
+        RubySaml = ::RubySaml
+    end
+end
+
+unless defined?(::OneLogin::RubySaml::Logging)
+    module OneLogin
+        module RubySaml
+            Logging = ::RubySaml::Logging
+        end
+    end
+end

lib/ruby_saml/xml/decoder.rb

@@ -61,7 +61,7 @@ def base64_encode(string)
       # @param string [String] string to check the encoding of
       # @return [true, false] whether or not the string is base64 encoded
       def base64_encoded?(string)
-        string.gsub(/[\s\r\n]|\\r|\\n/, '').match?(BASE64_FORMAT)
+        string.gsub(/\s|\\r|\\n/, '').match?(BASE64_FORMAT)
       end
 
       # Attempt inflating a string, if it fails, return the original string.

test/logging_test.rb

@@ -58,5 +58,56 @@ class LoggingTest < Minitest::Test
         RubySaml::Logging.info('sup?')
       end
     end
+
+    describe "OneLogin::RubySaml::Logging compatibility" do
+      it "defines OneLogin::RubySaml::Logging as an alias to RubySaml::Logging" do
+        assert defined?(OneLogin::RubySaml::Logging),
+               "Expected OneLogin::RubySaml::Logging to be defined"
+
+        assert_equal RubySaml::Logging.object_id,
+                     OneLogin::RubySaml::Logging.object_id,
+                     "Expected OneLogin::RubySaml::Logging to alias RubySaml::Logging"
+      end
+
+      it "shares the same logger instance when set via RubySaml::Logging" do
+        logger = mock('Logger')
+        RubySaml::Logging.logger = logger
+
+        assert_same logger, OneLogin::RubySaml::Logging.logger
+      end
+
+      it "shares the same logger instance when set via OneLogin::RubySaml::Logging" do
+        logger = mock('Logger')
+        OneLogin::RubySaml::Logging.logger = logger
+
+        assert_same logger, RubySaml::Logging.logger
+      end
+
+      it "delegates to the configured logger when using the legacy constant" do
+        logger = mock('Logger')
+        OneLogin::RubySaml::Logging.logger = logger
+
+        logger.expects(:debug).with('hi mom')
+        logger.expects(:info).with('sup?')
+
+        OneLogin::RubySaml::Logging.debug('hi mom')
+        OneLogin::RubySaml::Logging.info('sup?')
+      end
+
+      it "respects ENV['ruby-saml/testing'] and does not log when set (legacy constant)" do
+        logger = mock('Logger')
+        OneLogin::RubySaml::Logging.logger = logger
+
+        ENV["ruby-saml/testing"] = "1"
+
+        # No expectations on logger; any call would cause Mocha to fail the test.
+        OneLogin::RubySaml::Logging.debug('hi mom')
+        OneLogin::RubySaml::Logging.info('sup?')
+        OneLogin::RubySaml::Logging.warn('hey')
+        OneLogin::RubySaml::Logging.error('oops')
+
+        ENV.delete("ruby-saml/testing")
+      end
+    end
   end
 end

test/onelogin_alias_test.rb → test/onelogin_rubysaml_compat_test.rb

@@ -2,16 +2,34 @@
 
 require_relative 'test_helper'
 
-class OneloginAliasTest < Minitest::Test
+class OneLoginRubySamlCompatTest < Minitest::Test
 
-  describe 'legacy OneLogin namespace alias' do
+  describe 'legacy OneLogin namespace compatibility' do
 
-    describe 'equality with Object' do
-      it "should be equal" do
-        assert_equal OneLogin, Object
-        assert_equal ::OneLogin, Object
-        assert_equal OneLogin::RubySaml, OneLogin::RubySaml
+    describe 'namespace equality' do
+      it "defines OneLogin::RubySaml as an alias to the RubySaml module" do
+        assert defined?(OneLogin::RubySaml), "Expected OneLogin::RubySaml to be defined"
         assert_equal ::OneLogin::RubySaml, ::RubySaml
+        assert_equal RubySaml.object_id, OneLogin::RubySaml.object_id, "Expected OneLogin::RubySaml to alias RubySaml"
+      end
+
+      it "exposes Logging under OneLogin::RubySaml::Logging as an alias to RubySaml::Logging" do
+        assert defined?(OneLogin::RubySaml::Logging), "Expected OneLogin::RubySaml::Logging to be defined"
+        assert_equal ::OneLogin::RubySaml::Logging, ::RubySaml::Logging
+        assert_equal RubySaml::Logging.object_id, OneLogin::RubySaml::Logging.object_id, "Expected OneLogin::RubySaml::Logging to alias RubySaml::Logging"
+      end
+
+      it "shares the same logger instance between RubySaml::Logging and OneLogin::RubySaml::Logging" do
+        logger = mock("Logger")
+
+        RubySaml::Logging.logger = logger
+        assert_same logger, OneLogin::RubySaml::Logging.logger
+
+        other_logger = mock("OtherLogger")
+        OneLogin::RubySaml::Logging.logger = other_logger
+        assert_same other_logger, RubySaml::Logging.logger
+      ensure
+        RubySaml::Logging.logger = ::TEST_LOGGER
       end
     end