Merge pull request SAML-Toolkits#393 from tosch/Parse_idp_metadata_into_an_hash

pitbulk · web-flow · commit 58dedaf8709c · 2017-05-11T12:27:44.000+02:00
Implement IdpMetadataParser#parse_to_hash
diff --git a/README.md b/README.md
@@ -281,7 +281,7 @@ And on 'signing' and 'encryption' arrays, add the different IdP x509 public cert
 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.
 
-Using ```idp_metadata_parser.parse_remote``` IdP metadata will be added to the settings withouth further ado.
+Using ```idp_metadata_parser.parse_remote``` IdP metadata will be added to the settings without further ado.
 
 ```ruby
 def saml_settings
@@ -300,9 +300,14 @@ def saml_settings
 end
 ```
 The following attributes are set:
+  * idp_entity_id
+  * name_identifier_format
   * idp_sso_target_url
   * idp_slo_target_url
-  * idp_cert_fingerprint
+  * idp_attribute_names
+  * idp_cert 
+  * idp_cert_fingerprint 
+  * idp_cert_multi
 
 ### Retrieve one Entity Descriptor when many exist in Metadata
 
@@ -319,6 +324,12 @@ IdpMetadataParser by its Entity Id value:
               )
 ```
 
+### Parsing Metadata into an Hash
+
+The `OneLogin::RubySaml::IdpMetadataParser` also provides the methods `#parse_to_hash` and `#parse_remote_to_hash`.
+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.
+
 ## 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
diff --git a/lib/onelogin/ruby-saml/idp_metadata_parser.rb b/lib/onelogin/ruby-saml/idp_metadata_parser.rb
@@ -22,57 +22,98 @@ class IdpMetadataParser
 
       attr_reader :document
       attr_reader :response
-      attr_reader :parse_options
+      attr_reader :options
 
       # Parse the Identity Provider metadata and update the settings with the
       # IdP values
       #
-      # @param (see IdpMetadataParser#get_idp_metadata)
-      # @param options  [Hash]   :settings to provide the OneLogin::RubySaml::Settings object or an hash for Settings overrides
-      # @return (see IdpMetadataParser#get_idp_metadata)
-      # @raise (see IdpMetadataParser#get_idp_metadata)
+      # @param url [String] Url where the XML of the Identity Provider Metadata is published.
+      # @param validate_cert [Boolean] If true and the URL is HTTPs, the cert of the domain is checked.
+      #
+      # @param options [Hash] options used for parsing the metadata and the returned Settings instance
+      # @option options [OneLogin::RubySaml::Settings, Hash] :settings the OneLogin::RubySaml::Settings object which gets the parsed metadata merged into or an hash for Settings overrides.
+      # @option options [Array<String>, nil] :sso_binding an ordered list of bindings to detect the single signon URL. The first binding in the list that is included in the metadata will be used.
+      # @option options [Array<String>, nil] :slo_binding an ordered list of bindings to detect the single logout URL. The first binding in the list that is included in the metadata will be used.
+      # @option options [String, nil] :entity_id when this is given, the entity descriptor for this ID is used. When ommitted, the first entity descriptor is used.
+      #
+      # @return [OneLogin::RubySaml::Settings]
+      #
+      # @raise [HttpError] Failure to fetch remote IdP metadata
       def parse_remote(url, validate_cert = true, options = {})
         idp_metadata = get_idp_metadata(url, validate_cert)
         parse(idp_metadata, options)
       end
 
+      # Parse the Identity Provider metadata and return the results as Hash
+      #
+      # @param url [String] Url where the XML of the Identity Provider Metadata is published.
+      # @param validate_cert [Boolean] If true and the URL is HTTPs, the cert of the domain is checked.
+      #
+      # @param options [Hash] options used for parsing the metadata
+      # @option options [Array<String>, nil] :sso_binding an ordered list of bindings to detect the single signon URL. The first binding in the list that is included in the metadata will be used.
+      # @option options [Array<String>, nil] :slo_binding an ordered list of bindings to detect the single logout URL. The first binding in the list that is included in the metadata will be used.
+      # @option options [String, nil] :entity_id when this is given, the entity descriptor for this ID is used. When ommitted, the first entity descriptor is used.
+      #
+      # @return [Hash]
+      #
+      # @raise [HttpError] Failure to fetch remote IdP metadata
+      def parse_remote_to_hash(url, validate_cert = true, options = {})
+        idp_metadata = get_idp_metadata(url, validate_cert)
+        parse_to_hash(idp_metadata, options)
+      end
+
       # Parse the Identity Provider metadata and update the settings with the IdP values
+      #
       # @param idp_metadata [String]
-      # @param options  [Hash]   :settings to provide the OneLogin::RubySaml::Settings object or an hash for Settings overrides
       #
-      def parse(idp_metadata, parse_options = {})
-        @document = REXML::Document.new(idp_metadata)
-        @parse_options = parse_options
-        @entity_descriptor = nil
+      # @param options [Hash] :settings to provide the OneLogin::RubySaml::Settings object or an hash for Settings overrides
+      # @option options [OneLogin::RubySaml::Settings, Hash] :settings the OneLogin::RubySaml::Settings object which gets the parsed metadata merged into or an hash for Settings overrides.
+      # @option options [Array<String>, nil] :sso_binding an ordered list of bindings to detect the single signon URL. The first binding in the list that is included in the metadata will be used.
+      # @option options [Array<String>, nil] :slo_binding an ordered list of bindings to detect the single logout URL. The first binding in the list that is included in the metadata will be used.
+      # @option options [String, nil] :entity_id when this is given, the entity descriptor for this ID is used. When ommitted, the first entity descriptor is used.
+      #
+      # @return [OneLogin::RubySaml::Settings]
+      def parse(idp_metadata, options = {})
+        parsed_metadata = parse_to_hash(idp_metadata, options)
+
+        settings = options[:settings]
 
-        settings = parse_options[:settings]
-        if settings.nil? || settings.is_a?(Hash)
-          settings = OneLogin::RubySaml::Settings.new(settings || {})
+        if settings.nil?
+          OneLogin::RubySaml::Settings.new(parsed_metadata)
+        elsif settings.is_a?(Hash)
+          OneLogin::RubySaml::Settings.new(settings.merge(parsed_metadata))
+        else
+          merge_parsed_metadata_into(settings, parsed_metadata)
         end
+      end
 
-        settings.idp_entity_id = idp_entity_id
-        settings.name_identifier_format = idp_name_id_format
-        settings.idp_sso_target_url = single_signon_service_url(parse_options)
-        settings.idp_slo_target_url = single_logout_service_url(parse_options)
-        settings.idp_attribute_names = attribute_names
-
-        settings.idp_cert = nil
-        settings.idp_cert_fingerprint = nil
-        settings.idp_cert_multi = nil
-        unless certificates.nil?
-          if certificates.size == 1 || ((certificates.key?("signing") && certificates["signing"].size == 1) && (certificates.key?("encryption") && certificates["encryption"].size == 1) && certificates["signing"][0] == certificates["encryption"][0])
-            if certificates.key?("signing")
-              settings.idp_cert = certificates["signing"][0]
-              settings.idp_cert_fingerprint = fingerprint(settings.idp_cert, settings.idp_cert_fingerprint_algorithm)
-            else
-              settings.idp_cert = certificates["encryption"][0]
-              settings.idp_cert_fingerprint = fingerprint(settings.idp_cert, settings.idp_cert_fingerprint_algorithm)
-            end
-          else
-            settings.idp_cert_multi = certificates
-          end
+      # Parse the Identity Provider metadata and return the results as Hash
+      #
+      # @param idp_metadata [String]
+      #
+      # @param options [Hash] options used for parsing the metadata and the returned Settings instance
+      # @option options [Array<String>, nil] :sso_binding an ordered list of bindings to detect the single signon URL. The first binding in the list that is included in the metadata will be used.
+      # @option options [Array<String>, nil] :slo_binding an ordered list of bindings to detect the single logout URL. The first binding in the list that is included in the metadata will be used.
+      # @option options [String, nil] :entity_id when this is given, the entity descriptor for this ID is used. When ommitted, the first entity descriptor is used.
+      #
+      # @return [Hash]
+      def parse_to_hash(idp_metadata, options = {})
+        @document = REXML::Document.new(idp_metadata)
+        @options = options
+        @entity_descriptor = nil
+
+        {
+          :idp_entity_id => idp_entity_id,
+          :name_identifier_format => idp_name_id_format,
+          :idp_sso_target_url => single_signon_service_url(options),
+          :idp_slo_target_url => single_logout_service_url(options),
+          :idp_attribute_names => attribute_names,
+          :idp_cert => nil,
+          :idp_cert_fingerprint => nil,
+          :idp_cert_multi => nil
+        }.tap do |response_hash|
+          merge_certificates_into(response_hash) unless certificates.nil?
         end
-        settings
       end
 
       private
@@ -118,7 +159,7 @@ def entity_descriptor
 
       def entity_descriptor_path
         path = "//md:EntityDescriptor"
-        entity_id = parse_options[:entity_id]
+        entity_id = options[:entity_id]
         return path unless entity_id
         path << "[@entityID=\"#{entity_id}\"]"
       end
@@ -162,7 +203,7 @@ def single_signon_service_binding(binding_priority = nil)
       #
       def single_signon_service_url(options = {})
         binding = single_signon_service_binding(options[:sso_binding])
-        unless binding.nil? 
+        unless binding.nil?
           node = REXML::XPath.first(
             entity_descriptor,
             "md:IDPSSODescriptor/md:SingleSignOnService[@Binding=\"#{binding}\"]/@Location",
@@ -222,7 +263,7 @@ def certificates
 
           certs = nil
           unless signing_nodes.empty? && encryption_nodes.empty?
-            certs = {}            
+            certs = {}
             unless signing_nodes.empty?
               certs['signing'] = []
               signing_nodes.each do |cert_node|
@@ -273,6 +314,38 @@ def namespace
           "ds" => DSIG
         }
       end
+
+      def merge_certificates_into(parsed_metadata)
+        if certificates.size == 1 ||
+          ((certificates.key?("signing") && certificates["signing"].size == 1) &&
+            (certificates.key?("encryption") && certificates["encryption"].size == 1) &&
+            certificates["signing"][0] == certificates["encryption"][0])
+
+          if certificates.key?("signing")
+            parsed_metadata[:idp_cert] = certificates["signing"][0]
+            parsed_metadata[:idp_cert_fingerprint] = fingerprint(
+              parsed_metadata[:idp_cert],
+              parsed_metadata[:idp_cert_fingerprint_algorithm]
+            )
+          else
+            parsed_metadata[:idp_cert] = certificates["encryption"][0]
+            parsed_metadata[:idp_cert_fingerprint] = fingerprint(
+              parsed_metadata[:idp_cert],
+              parsed_metadata[:idp_cert_fingerprint_algorithm]
+            )
+          end
+        else
+          parsed_metadata[:idp_cert_multi] = certificates
+        end
+      end
+
+      def merge_parsed_metadata_into(settings, parsed_metadata)
+        parsed_metadata.each do |key, value|
+          settings.send("#{key}=".to_sym, value)
+        end
+
+        settings
+      end
     end
   end
 end
diff --git a/test/idp_metadata_parser_test.rb b/test/idp_metadata_parser_test.rb
@@ -95,6 +95,96 @@ def initialize; end
       assert_equal XMLSecurity::Document::RSA_SHA256, settings.security[:signature_method]
     end
 
+    it "merges results into given settings object" do
+      settings = OneLogin::RubySaml::Settings.new(:security => {
+        :digest_method => XMLSecurity::Document::SHA256,
+        :signature_method => XMLSecurity::Document::RSA_SHA256
+      })
+
+      OneLogin::RubySaml::IdpMetadataParser.new.parse(idp_metadata_descriptor, :settings => settings)
+
+      assert_equal "F1:3C:6B:80:90:5A:03:0E:6C:91:3E:5D:15:FA:DD:B0:16:45:48:72", settings.idp_cert_fingerprint
+      assert_equal XMLSecurity::Document::SHA256, settings.security[:digest_method]
+      assert_equal XMLSecurity::Document::RSA_SHA256, settings.security[:signature_method]
+    end
+  end
+
+  describe "parsing an IdP descriptor file into an Hash" do
+    it "extract settings details from xml" do
+      idp_metadata_parser = OneLogin::RubySaml::IdpMetadataParser.new
+
+      metadata = idp_metadata_parser.parse_to_hash(idp_metadata_descriptor)
+
+      assert_equal "https://hello.example.com/access/saml/idp.xml", metadata[:idp_entity_id]
+      assert_equal "https://hello.example.com/access/saml/login", metadata[:idp_sso_target_url]
+      assert_equal "F1:3C:6B:80:90:5A:03:0E:6C:91:3E:5D:15:FA:DD:B0:16:45:48:72", metadata[:idp_cert_fingerprint]
+      assert_equal "https://hello.example.com/access/saml/logout", metadata[:idp_slo_target_url]
+      assert_equal "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified", metadata[:name_identifier_format]
+      assert_equal ["AuthToken", "SSOStartPage"], metadata[:idp_attribute_names]
+    end
+
+    it "extract certificate from md:KeyDescriptor[@use='signing']" do
+      idp_metadata_parser = OneLogin::RubySaml::IdpMetadataParser.new
+      idp_metadata = idp_metadata_descriptor
+      metadata = idp_metadata_parser.parse_to_hash(idp_metadata)
+      assert_equal "F1:3C:6B:80:90:5A:03:0E:6C:91:3E:5D:15:FA:DD:B0:16:45:48:72", metadata[:idp_cert_fingerprint]
+    end
+
+    it "extract certificate from md:KeyDescriptor[@use='encryption']" do
+      idp_metadata_parser = OneLogin::RubySaml::IdpMetadataParser.new
+      idp_metadata = idp_metadata_descriptor
+      idp_metadata = idp_metadata.sub(/<md:KeyDescriptor use="signing">(.*?)<\/md:KeyDescriptor>/m, "")
+      parsed_metadata = idp_metadata_parser.parse_to_hash(idp_metadata)
+      assert_equal "F1:3C:6B:80:90:5A:03:0E:6C:91:3E:5D:15:FA:DD:B0:16:45:48:72", parsed_metadata[:idp_cert_fingerprint]
+    end
+
+    it "extract certificate from md:KeyDescriptor" do
+      idp_metadata_parser = OneLogin::RubySaml::IdpMetadataParser.new
+      idp_metadata = idp_metadata_descriptor
+      idp_metadata = idp_metadata.sub(/<md:KeyDescriptor use="signing">(.*?)<\/md:KeyDescriptor>/m, "")
+      idp_metadata = idp_metadata.sub('<md:KeyDescriptor use="encryption">', '<md:KeyDescriptor>')
+      parsed_metadata = idp_metadata_parser.parse_to_hash(idp_metadata)
+      assert_equal "F1:3C:6B:80:90:5A:03:0E:6C:91:3E:5D:15:FA:DD:B0:16:45:48:72", parsed_metadata[:idp_cert_fingerprint]
+    end
+
+    it "extract SSO endpoint with no specific binding, it takes the first" do
+      idp_metadata_parser = OneLogin::RubySaml::IdpMetadataParser.new
+      idp_metadata = idp_metadata_descriptor3
+      metadata = idp_metadata_parser.parse_to_hash(idp_metadata)
+      assert_equal "https://idp.example.com/idp/profile/Shibboleth/SSO", metadata[:idp_sso_target_url]
+    end
+
+    it "extract SSO endpoint with specific binding" do
+      idp_metadata_parser = OneLogin::RubySaml::IdpMetadataParser.new
+      idp_metadata = idp_metadata_descriptor3
+      options = {}
+      options[:sso_binding] = ['urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST']
+      parsed_metadata = idp_metadata_parser.parse_to_hash(idp_metadata, options)
+      assert_equal "https://idp.example.com/idp/profile/SAML2/POST/SSO", parsed_metadata[:idp_sso_target_url]
+
+      options[:sso_binding] = ['urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect']
+      parsed_metadata = idp_metadata_parser.parse_to_hash(idp_metadata, options)
+      assert_equal "https://idp.example.com/idp/profile/SAML2/Redirect/SSO", parsed_metadata[:idp_sso_target_url]
+
+      options[:sso_binding] = ['invalid_binding', 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect']
+      parsed_metadata = idp_metadata_parser.parse_to_hash(idp_metadata, options)
+      assert_equal "https://idp.example.com/idp/profile/SAML2/Redirect/SSO", parsed_metadata[:idp_sso_target_url]
+    end
+
+    it "ignores a given :settings hash" do
+      idp_metadata_parser = OneLogin::RubySaml::IdpMetadataParser.new
+      idp_metadata = idp_metadata_descriptor
+      parsed_metadata = idp_metadata_parser.parse_to_hash(idp_metadata, {
+        :settings => {
+          :security => {
+            :digest_method => XMLSecurity::Document::SHA256,
+            :signature_method => XMLSecurity::Document::RSA_SHA256
+          }
+        }
+      })
+      assert_equal "F1:3C:6B:80:90:5A:03:0E:6C:91:3E:5D:15:FA:DD:B0:16:45:48:72", parsed_metadata[:idp_cert_fingerprint]
+      assert_nil parsed_metadata[:security]
+    end
   end
 
   describe "parsing an IdP descriptor file with multiple signing certs" do
@@ -152,6 +242,39 @@ def initialize; end
     end
   end
 
+  describe "download and parse IdP descriptor file into an Hash" do
+    before do
+      mock_response = MockSuccessResponse.new
+      mock_response.body = idp_metadata_descriptor
+      @url = "https://example.com"
+      uri = URI(@url)
+
+      @http = Net::HTTP.new(uri.host, uri.port)
+      Net::HTTP.expects(:new).returns(@http)
+      @http.expects(:request).returns(mock_response)
+    end
+
+    it "extract settings from remote xml" do
+      idp_metadata_parser = OneLogin::RubySaml::IdpMetadataParser.new
+      parsed_metadata = idp_metadata_parser.parse_remote_to_hash(@url)
+
+      assert_equal "https://hello.example.com/access/saml/idp.xml", parsed_metadata[:idp_entity_id]
+      assert_equal "https://hello.example.com/access/saml/login", parsed_metadata[:idp_sso_target_url]
+      assert_equal "F1:3C:6B:80:90:5A:03:0E:6C:91:3E:5D:15:FA:DD:B0:16:45:48:72", parsed_metadata[:idp_cert_fingerprint]
+      assert_equal "https://hello.example.com/access/saml/logout", parsed_metadata[:idp_slo_target_url]
+      assert_equal "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified", parsed_metadata[:name_identifier_format]
+      assert_equal ["AuthToken", "SSOStartPage"], parsed_metadata[:idp_attribute_names]
+      assert_equal OpenSSL::SSL::VERIFY_PEER, @http.verify_mode
+    end
+
+    it "accept self signed certificate if insturcted" do
+      idp_metadata_parser = OneLogin::RubySaml::IdpMetadataParser.new
+      idp_metadata_parser.parse_remote_to_hash(@url, false)
+
+      assert_equal OpenSSL::SSL::VERIFY_NONE, @http.verify_mode
+    end
+  end
+
   describe "download failure cases" do
     it "raises an exception when the url has no scheme" do
       idp_metadata_parser = OneLogin::RubySaml::IdpMetadataParser.new
