Alias/deprecate more params:

- certificate --> sp_cert - private_key --> sp_private_key - assertion_consumer_service_url --> sp_assertion_consumer_service_url - assertion_consumer_service_binding --> sp_assertion_consumer_service_binding - single_logout_service_url --> sp_slo_service_url - single_logout_service_binding --> sp_slo_service_binding
SAML-Toolkits · Jul 10, 2024 · 000ed7a · 000ed7a
1 parent 3229214
commit 000ed7a
Show file tree

Hide file tree

Showing 20 changed files with 321 additions and 191 deletions.
diff --git a/README.md b/README.md
@@ -191,7 +191,7 @@ If you don't know what expect, always use the former (set the settings on initia
 def saml_settings
   settings = RubySaml::Settings.new
 
-  settings.assertion_consumer_service_url = "http://#{request.host}/saml/consume"
+  settings.sp_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}"
@@ -211,8 +211,8 @@ def saml_settings
   ]
 
   # 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.sp_slo_service_binding = "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" # or :post, :redirect
+  settings.sp_assertion_consumer_service_binding = "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" # or :post, :redirect
 
   settings
 end
@@ -263,11 +263,11 @@ class SamlController < ApplicationController
   def saml_settings
     settings = RubySaml::Settings.new
 
-    settings.assertion_consumer_service_url = "http://#{request.host}/saml/consume"
-    settings.sp_entity_id                   = "http://#{request.host}/saml/metadata"
-    settings.idp_sso_service_url             = "https://app.onelogin.com/saml/signon/#{OneLoginAppId}"
-    settings.idp_cert_fingerprint           = OneLoginAppCertFingerPrint
-    settings.name_identifier_format         = "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"
+    settings.sp_assertion_consumer_service_url = "http://#{request.host}/saml/consume"
+    settings.sp_entity_id           = "http://#{request.host}/saml/metadata"
+    settings.idp_sso_service_url    = "https://app.onelogin.com/saml/signon/#{OneLoginAppId}"
+    settings.idp_cert_fingerprint   = OneLoginAppCertFingerPrint
+    settings.name_identifier_format = "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"
 
     # Optional for most SAML IdPs
     settings.authn_context = "urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport"
@@ -338,9 +338,9 @@ def saml_settings
   # Returns 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"
-  settings.sp_entity_id                   = "http://#{request.host}/saml/metadata"
-  settings.name_identifier_format         = "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"
+  settings.sp_assertion_consumer_service_url = "http://#{request.host}/saml/consume"
+  settings.sp_entity_id = "http://#{request.host}/saml/metadata"
+  settings.name_identifier_format = "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"
   # Optional for most SAML IdPs
   settings.authn_context = "urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport"
 
@@ -622,8 +622,8 @@ Ruby SAML supports the following functionality:
 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"
+  settings.sp_cert = "CERTIFICATE TEXT WITH BEGIN/END HEADER AND FOOTER"
+  settings.sp_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
@@ -642,8 +642,8 @@ You may also globally set the SP signature and digest method, to be used in SP s
 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"
+  settings.sp_cert = "CERTIFICATE TEXT WITH BEGIN/END HEADER AND FOOTER"
+  settings.sp_private_key = "PRIVATE KEY TEXT WITH BEGIN/END HEADER AND FOOTER"
 
   settings.security[:metadata_signed] = true # Enable signature on Metadata
 ```
@@ -658,8 +658,8 @@ To enable, please first set your certificate and private key. This will add `<md
 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"
+  settings.sp_cert = "CERTIFICATE TEXT WITH BEGIN/END HEADER AND FOOTER"
+  settings.sp_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:
@@ -684,8 +684,8 @@ You may enable EncryptedAssertion as follows. This will add `<md:KeyDescriptor u
 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"
+  settings.sp_cert = "CERTIFICATE TEXT WITH BEGIN/END HEADER AND FOOTER"
+  settings.sp_private_key = "PRIVATE KEY TEXT WITH BEGIN/END HEADER AND FOOTER"
 
   settings.security[:want_assertions_encrypted] = true # Invalidate SAML messages without an EncryptedAssertion
 ```

diff --git a/UPGRADING.md b/UPGRADING.md
@@ -50,7 +50,7 @@ settings.security[:digest_method] = RubySaml::XML::Document::SHA1
 settings.security[:signature_method] = RubySaml::XML::Document::RSA_SHA1
 ```
 
-### Removal of embed_sign Setting
+### Removal of security[: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.
@@ -68,10 +68,10 @@ settings.idp_slo_service_binding = :redirect
 
 For clarity, the default value of both parameters is `:redirect` if they are not set.
 
-### Deprecation of Compression Settings
+### Deprecation of compression settings
 
 The `settings.compress_request` and `settings.compress_response` parameters have been deprecated
-and are no longer functional. They will be removed in RubySaml 2.1.0. Please remove `compress_request`
+and are no longer functional. **They will be removed in RubySaml 2.1.0.** Please remove `compress_request`
 and `compress_response` everywhere within your project code.
 
 The SAML SP request/response message compression behavior is now controlled automatically by the
@@ -80,17 +80,47 @@ The SAML SP request/response message compression behavior is now controlled auto
 "compression" is used to make redirect URLs which contain SAML messages be shorter. For POST messages,
 compression may be achieved by enabling `Content-Encoding: gzip` on your webserver.
 
-## Settings deprecations
+### Deprecation of certificate_new setting
 
-The following parameters in `RubySaml::Settings` are deprecated and will be removed in RubySaml 2.1.0:
+The `settings.certificate_new` parameter has been deprecated in favor of `settings.sp_cert_multi`,
+and **will be removed in RubySaml 2.1.0.** If you are using `certificate_new` you
+will need to replace **all** of the `certificate`, `certificate_new`, and `private_key` params
+with `sp_cert_multi` as shown below:
 
-- `#issuer` is deprecated and replaced 1:1 by `#sp_entity_id`
-- `#idp_sso_target_url` is deprecated and replaced 1:1 by `#idp_sso_service_url`
-- `#idp_slo_target_url` is deprecated and replaced 1:1 by `#idp_slo_service_url`
-- `#assertion_consumer_logout_service_url` is deprecated and replaced 1:1 by `#single_logout_service_url`
-- `#assertion_consumer_logout_service_binding` is deprecated and replaced 1:1 by `#single_logout_service_binding`
-- `#certificate_new` is deprecated and replaced by `#sp_cert_multi`. Refer to documentation as `#sp_cert_multi`
-  has a different value type than `#certificate_new`.
+```ruby
+settings.sp_cert_multi = {
+  signing: [
+    { certificate: (certificate), private_key: (private_key) },
+    { certificate: (certificate_new), private_key: (private_key) }
+  ],
+  encryption: [
+    { certificate: (certificate), private_key: (private_key) },
+    { certificate: (certificate_new), private_key: (private_key) }
+  ],
+}
+```
+
+## Settings parameter deprecations
+
+The following parameters in `RubySaml::Settings` are deprecated and replaced 1-for-1 with new parameters.
+The new names clarify which parameters belong to the SP and which to the IdP.
+Until RubySaml 3.0.0, using the old method will raise a deprecation warning but otherwise function as an alias
+to the new parameter. Beginning in **RubySaml 3.0.0**, using the old method will raise a `NotImplemented` error.
+Aside from the name change, there are no changes to the usage or functionality of these parameters.
+
+| Old Parameter                               | New Parameter                           |
+|---------------------------------------------|-----------------------------------------|
+| `issuer`                                    | `sp_entity_id`                          |
+| `certificate`                               | `sp_cert`                               |
+| `private_key`                               | `sp_private_key`                        |
+| `assertion_consumer_service_url`            | `sp_assertion_consumer_service_url`     |
+| `assertion_consumer_service_binding`        | `sp_assertion_consumer_service_binding` |
+| `assertion_consumer_logout_service_url`     | `sp_slo_service_url`                    |
+| `single_logout_service_url`                 | `sp_slo_service_url`                    |
+| `assertion_consumer_logout_service_binding` | `sp_slo_service_binding`                |
+| `single_logout_service_binding`             | `sp_slo_service_binding`                |
+| `idp_sso_target_url`                        | `idp_sso_service_url`                   |
+| `idp_slo_target_url`                        | `idp_slo_service_url`                   |
 
 ## Updating from 1.12.x to 1.13.0
 
@@ -189,7 +219,7 @@ 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
+The 'Recipient' value is compared with the settings.sp_assertion_consumer_service_url
 value.
 
 If you want to skip that validation, add the :skip_recipient_check option to the

diff --git a/lib/ruby_saml/authrequest.rb b/lib/ruby_saml/authrequest.rb
@@ -123,8 +123,8 @@ def create_xml_document(settings)
       root.attributes['ForceAuthn'] = settings.force_authn unless settings.force_authn.nil?
 
       # Conditionally defined elements based on settings
-      unless settings.assertion_consumer_service_url.nil?
-        root.attributes["AssertionConsumerServiceURL"] = settings.assertion_consumer_service_url
+      unless settings.sp_assertion_consumer_service_url.nil?
+        root.attributes["AssertionConsumerServiceURL"] = settings.sp_assertion_consumer_service_url
       end
 
       unless settings.sp_entity_id.nil?

diff --git a/lib/ruby_saml/logging.rb b/lib/ruby_saml/logging.rb
@@ -24,7 +24,7 @@ def logger
     end
 
     def deprecate(message)
-      warn("[DEPRECATION] RubySaml: #{message}")
+      warn("[RubySaml] DEPRECATION: #{message}")
     end
 
     def enabled?

diff --git a/lib/ruby_saml/metadata.rb b/lib/ruby_saml/metadata.rb
@@ -77,11 +77,11 @@ def add_sp_certificates(sp_sso, settings)
     end
 
     def add_sp_service_elements(sp_sso, settings)
-      if settings.single_logout_service_url
+      if settings.sp_slo_service_url
         sp_sso.add_element "md:SingleLogoutService", {
-            "Binding" => settings.single_logout_service_binding,
-            "Location" => settings.single_logout_service_url,
-            "ResponseLocation" => settings.single_logout_service_url
+            "Binding" => settings.sp_slo_service_binding,
+            "Location" => settings.sp_slo_service_url,
+            "ResponseLocation" => settings.sp_slo_service_url
         }
       end
 
@@ -90,10 +90,10 @@ def add_sp_service_elements(sp_sso, settings)
         nameid.text = settings.name_identifier_format
       end
 
-      if settings.assertion_consumer_service_url
+      if settings.sp_assertion_consumer_service_url
         sp_sso.add_element "md:AssertionConsumerService", {
-            "Binding" => settings.assertion_consumer_service_binding,
-            "Location" => settings.assertion_consumer_service_url,
+            "Binding" => settings.sp_assertion_consumer_service_binding,
+            "Location" => settings.sp_assertion_consumer_service_url,
             "isDefault" => true,
             "index" => 0
         }

diff --git a/lib/ruby_saml/response.rb b/lib/ruby_saml/response.rb
@@ -636,10 +636,10 @@ def validate_destination
         return append_error(error_msg)
       end
 
-      return true if settings.assertion_consumer_service_url.nil? || settings.assertion_consumer_service_url.empty?
+      return true if settings.sp_assertion_consumer_service_url.nil? || settings.sp_assertion_consumer_service_url.empty?
 
-      unless RubySaml::Utils.uri_match?(destination, settings.assertion_consumer_service_url)
-        error_msg = "The response was received at #{destination} instead of #{settings.assertion_consumer_service_url}"
+      unless RubySaml::Utils.uri_match?(destination, settings.sp_assertion_consumer_service_url)
+        error_msg = "The response was received at #{destination} instead of #{settings.sp_assertion_consumer_service_url}"
         return append_error(error_msg)
       end
 
@@ -778,7 +778,7 @@ def validate_subject_confirmation
         next if (attrs.include? "InResponseTo" and attrs['InResponseTo'] != in_response_to) ||
                 (attrs.include? "NotBefore" and now < (parse_time(confirmation_data_node, "NotBefore") - allowed_clock_drift)) ||
                 (attrs.include? "NotOnOrAfter" and now >= (parse_time(confirmation_data_node, "NotOnOrAfter") + allowed_clock_drift)) ||
-                (attrs.include? "Recipient" and !options[:skip_recipient_check] and settings and attrs['Recipient'] != settings.assertion_consumer_service_url)
+                (attrs.include? "Recipient" and !options[:skip_recipient_check] and settings and attrs['Recipient'] != settings.sp_assertion_consumer_service_url)
 
         valid_subject_confirmation = true
         break