ruby-saml 0.9.4 → 1.0.0

data/lib/onelogin/ruby-saml/http_error.rb

@@ -0,0 +1,7 @@
+module OneLogin
+  module RubySaml
+    class HttpError < StandardError
+    end
+  end
+end
+

data/lib/onelogin/ruby-saml/idp_metadata_parser.rb

@@ -7,22 +7,35 @@ require "net/https"
 require "rexml/document"
 require "rexml/xpath"
 
+# Only supports SAML 2.0
 module OneLogin
   module RubySaml
     include REXML
 
+    # Auxiliary class to retrieve and parse the Identity Provider Metadata
+    #
     class IdpMetadataParser
 
       METADATA = "urn:oasis:names:tc:SAML:2.0:metadata"
       DSIG     = "http://www.w3.org/2000/09/xmldsig#"
 
       attr_reader :document
-
+      attr_reader :response
+
+      # Parse the Identity Provider metadata and update the settings with the
+      # IdP values
+      #
+      # @param (see IdpMetadataParser#get_idp_metadata)
+      # @return (see IdpMetadataParser#get_idp_metadata)
+      # @raise (see IdpMetadataParser#get_idp_metadata)
       def parse_remote(url, validate_cert = true)
         idp_metadata = get_idp_metadata(url, validate_cert)
         parse(idp_metadata)
       end
 
+      # Parse the Identity Provider metadata and update the settings with the IdP values
+      # @param idp_metadata [String] 
+      #
       def parse(idp_metadata)
         @document = REXML::Document.new(idp_metadata)
 
@@ -37,8 +50,11 @@ module OneLogin
 
       private
 
-      # Retrieve the remote IdP metadata from the URL or a cached copy
-      # # returns a REXML document of the metadata
+      # Retrieve the remote IdP metadata from the URL or a cached copy.
+      # @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.
+      # @return [REXML::document] Parsed XML IdP metadata
+      # @raise [HttpError] Failure to fetch remote IdP metadata
       def get_idp_metadata(url, validate_cert)
         uri = URI.parse(url)
         if uri.scheme == "http"
@@ -62,37 +78,76 @@ module OneLogin
           get = Net::HTTP::Get.new(uri.request_uri)
           response = http.request(get)
           meta_text = response.body
+        else
+          raise ArgumentError.new("url must begin with http or https")
+        end
+
+        unless response.is_a? Net::HTTPSuccess
+          raise OneLogin::RubySaml::HttpError.new("Failed to fetch idp metadata")
         end
+
         meta_text
       end
 
+      # @return [String|nil] IdP Entity ID value if exists
+      #
       def idp_entity_id
-        node = REXML::XPath.first(document, "/md:EntityDescriptor/@entityID", { "md" => METADATA })
+        node = REXML::XPath.first(
+          document,
+          "/md:EntityDescriptor/@entityID",
+          { "md" => METADATA }
+        )
         node.value if node
       end
 
+      # @return [String|nil] IdP Name ID Format value if exists
+      #
       def idp_name_id_format
-        node = REXML::XPath.first(document, "/md:EntityDescriptor/md:IDPSSODescriptor/md:NameIDFormat", { "md" => METADATA })
-        Utils.element_text(node)
+        node = REXML::XPath.first(
+          document,
+          "/md:EntityDescriptor/md:IDPSSODescriptor/md:NameIDFormat",
+          { "md" => METADATA }
+        )
+        node.text if node
       end
 
+      # @return [String|nil] SingleSignOnService endpoint if exists
+      #
       def single_signon_service_url
-        node = REXML::XPath.first(document, "/md:EntityDescriptor/md:IDPSSODescriptor/md:SingleSignOnService/@Location", { "md" => METADATA })
+        node = REXML::XPath.first(
+          document,
+          "/md:EntityDescriptor/md:IDPSSODescriptor/md:SingleSignOnService/@Location",
+          { "md" => METADATA }
+        )
         node.value if node
       end
 
+      # @return [String|nil] SingleLogoutService endpoint if exists
+      #
       def single_logout_service_url
-        node = REXML::XPath.first(document, "/md:EntityDescriptor/md:IDPSSODescriptor/md:SingleLogoutService/@Location", { "md" => METADATA })
+        node = REXML::XPath.first(
+          document,
+          "/md:EntityDescriptor/md:IDPSSODescriptor/md:SingleLogoutService/@Location",
+          { "md" => METADATA }
+        )
         node.value if node
       end
 
+      # @return [String|nil] X509Certificate if exists
+      #
       def certificate
         @certificate ||= begin
-          node = REXML::XPath.first(document, "/md:EntityDescriptor/md:IDPSSODescriptor/md:KeyDescriptor[@use='signing']/ds:KeyInfo/ds:X509Data/ds:X509Certificate", { "md" => METADATA, "ds" => DSIG })
-          Base64.decode64(Utils.element_text(node)) if node
+          node = REXML::XPath.first(
+            document,
+            "/md:EntityDescriptor/md:IDPSSODescriptor/md:KeyDescriptor[@use='signing']/ds:KeyInfo/ds:X509Data/ds:X509Certificate",
+            { "md" => METADATA, "ds" => DSIG }
+          )
+          Base64.decode64(node.text) if node
         end
       end
 
+      # @return [String|nil] the SHA-1 fingerpint of the X509Certificate if it exists
+      #
       def fingerprint
         @fingerprint ||= begin
           if certificate

data/lib/onelogin/ruby-saml/logging.rb

@@ -1,25 +1,29 @@
+require 'logger'
+
 # Simplistic log class when we're running in Rails
 module OneLogin
   module RubySaml
     class Logging
+      DEFAULT_LOGGER = ::Logger.new(STDOUT)
+
+      def self.logger
+        @logger || (defined?(::Rails) && Rails.logger) || DEFAULT_LOGGER
+      end
+
+      def self.logger=(logger)
+        @logger = logger
+      end
+
       def self.debug(message)
         return if !!ENV["ruby-saml/testing"]
 
-        if defined? Rails
-          Rails.logger.debug message
-        else
-          puts message
-        end
+        logger.debug message
       end
 
       def self.info(message)
         return if !!ENV["ruby-saml/testing"]
 
-        if defined? Rails
-          Rails.logger.info message
-        else
-          puts message
-        end
+        logger.info message
       end
     end
   end

data/lib/onelogin/ruby-saml/logoutrequest.rb

@@ -3,16 +3,29 @@ require "uuid"
 require "onelogin/ruby-saml/logging"
 require "onelogin/ruby-saml/saml_message"
 
+# Only supports SAML 2.0
 module OneLogin
   module RubySaml
+
+    # SAML2 Logout Request (SLO SP initiated, Builder)
+    #
     class Logoutrequest < SamlMessage
 
-      attr_reader :uuid # Can be obtained if neccessary
+      # Logout Request ID
+      attr_reader :uuid
 
+      # Initializes the Logout Request. A Logoutrequest Object that is an extension of the SamlMessage class.
+      # Asigns an ID, a random uuid.
+      #
       def initialize
         @uuid = "_" + UUID.new.generate
       end
 
+      # Creates the Logout Request string.
+      # @param settings [OneLogin::RubySaml::Settings|nil] Toolkit settings
+      # @param params [Hash] Some extra parameters to be added in the GET for example the RelayState
+      # @return [String] Logout Request string that includes the SAMLRequest
+      #
       def create(settings, params={})
         params = create_params(settings, params)
         params_prefix = (settings.idp_slo_target_url =~ /\?/) ? '&' : '?'
@@ -24,6 +37,11 @@ module OneLogin
         @logout_url = settings.idp_slo_target_url + request_params
       end
 
+      # Creates the Get parameters for the logout request.
+      # @param settings [OneLogin::RubySaml::Settings|nil] Toolkit settings
+      # @param params [Hash] Some extra parameters to be added in the GET for example the RelayState
+      # @return [Hash] Parameters
+      #
       def create_params(settings, params={})
         # The method expects :RelayState but sometimes we get 'RelayState' instead.
         # Based on the HashWithIndifferentAccess value in Rails we could experience
@@ -44,11 +62,14 @@ module OneLogin
 
         if settings.security[:logout_requests_signed] && !settings.security[:embed_sign] && settings.private_key
           params['SigAlg']    = settings.security[:signature_method]
-          url_string          = "SAMLRequest=#{CGI.escape(base64_request)}"
-          url_string         << "&RelayState=#{CGI.escape(relay_state)}" if relay_state
-          url_string         << "&SigAlg=#{CGI.escape(params['SigAlg'])}"
-          private_key         = settings.get_sp_key()
-          signature           = private_key.sign(XMLSecurity::BaseDocument.new.algorithm(settings.security[:signature_method]).new, url_string)
+          url_string = OneLogin::RubySaml::Utils.build_query(
+            :type => 'SAMLRequest',
+            :data => base64_request,
+            :relay_state => relay_state,
+            :sig_alg => params['SigAlg']
+          )
+          sign_algorithm = XMLSecurity::BaseDocument.new.algorithm(settings.security[:signature_method])
+          signature = settings.get_sp_key.sign(sign_algorithm.new, url_string)
           params['Signature'] = encode(signature)
         end
 
@@ -59,6 +80,10 @@ module OneLogin
         request_params
       end
 
+      # Creates the SAMLRequest String.
+      # @param settings [OneLogin::RubySaml::Settings|nil] Toolkit settings
+      # @return [String] The SAMLRequest String.
+      #
       def create_logout_request_xml_doc(settings)
         time = Time.now.utc.strftime("%Y-%m-%dT%H:%M:%SZ")
 
@@ -76,15 +101,15 @@ module OneLogin
           issuer.text = settings.issuer
         end
 
-        name_id = root.add_element "saml:NameID"
+        nameid = root.add_element "saml:NameID"
         if settings.name_identifier_value
-          name_id.attributes['NameQualifier'] = settings.sp_name_qualifier if settings.sp_name_qualifier
-          name_id.attributes['Format'] = settings.name_identifier_format if settings.name_identifier_format
-          name_id.text = settings.name_identifier_value
+          nameid.attributes['NameQualifier'] = settings.sp_name_qualifier if settings.sp_name_qualifier
+          nameid.attributes['Format'] = settings.name_identifier_format if settings.name_identifier_format
+          nameid.text = settings.name_identifier_value
         else
           # If no NameID is present in the settings we generate one
-          name_id.text = "_" + UUID.new.generate
-          name_id.attributes['Format'] = 'urn:oasis:names:tc:SAML:2.0:nameid-format:transient'
+          nameid.text = "_" + UUID.new.generate
+          nameid.attributes['Format'] = 'urn:oasis:names:tc:SAML:2.0:nameid-format:transient'
         end
 
         if settings.sessionindex
@@ -94,8 +119,8 @@ module OneLogin
 
         # embed signature
         if settings.security[:logout_requests_signed] && settings.private_key && settings.certificate && settings.security[:embed_sign]
-          private_key = settings.get_sp_key()
-          cert = settings.get_sp_cert()
+          private_key = settings.get_sp_key
+          cert = settings.get_sp_cert
           request_doc.sign_document(private_key, cert, settings.security[:signature_method], settings.security[:digest_method])
         end
 

data/lib/onelogin/ruby-saml/logoutresponse.rb

@@ -3,65 +3,101 @@ require "onelogin/ruby-saml/saml_message"
 
 require "time"
 
+# Only supports SAML 2.0
 module OneLogin
   module RubySaml
+
+    # SAML2 Logout Response (SLO IdP initiated, Parser)
+    #
     class Logoutresponse < SamlMessage
-      # For API compability, this is mutable.
+
+      # OneLogin::RubySaml::Settings Toolkit settings
       attr_accessor :settings
 
+      # Array with the causes
+      attr_accessor :errors
+
       attr_reader :document
       attr_reader :response
       attr_reader :options
 
-      #
-      # In order to validate that the response matches a given request, append
-      # the option:
-      #   :matches_request_id => REQUEST_ID
-      #
-      # It will validate that the logout response matches the ID of the request.
-      # You can also do this yourself through the in_response_to accessor.
+      attr_accessor :soft
+
+      # Constructs the Logout Response. A Logout Response Object that is an extension of the SamlMessage class.
+      # @param response  [String] A UUEncoded logout response from the IdP.
+      # @param settings  [OneLogin::RubySaml::Settings|nil] Toolkit settings
+      # @param options   [Hash] Extra parameters. 
+      #                    :matches_request_id It will validate that the logout response matches the ID of the request.
+      #                    :get_params GET Parameters, including the SAMLResponse
+      # @raise [ArgumentError] if response is nil
       #
       def initialize(response, settings = nil, options = {})
+        @errors = []
         raise ArgumentError.new("Logoutresponse cannot be nil") if response.nil?
-        self.settings = settings
+        @settings = settings
+
+        if settings.nil? || settings.soft.nil?
+          @soft = true
+        else
+          @soft = settings.soft
+        end
 
         @options = options
         @response = decode_raw_saml(response)
         @document = XMLSecurity::SignedDocument.new(@response)
       end
 
-      def validate!
-        validate(false)
+      # Append the cause to the errors array, and based on the value of soft, return false or raise
+      # an exception
+      def append_error(error_msg)
+        @errors << error_msg
+        return soft ? false : validation_error(error_msg)
       end
 
-      def validate(soft = true)
-        return false unless valid_saml?(document, soft) && valid_state?(soft)
-
-        valid_in_response_to?(soft) && valid_issuer?(soft) && success?(soft)
+      # Reset the errors array
+      def reset_errors!
+        @errors = []
       end
 
-      def success?(soft = true)
+      # Checks if the Status has the "Success" code
+      # @return [Boolean] True if the StatusCode is Sucess
+      # @raise [ValidationError] if soft == false and validation fails
+      # 
+      def success?
         unless status_code == "urn:oasis:names:tc:SAML:2.0:status:Success"
-          return soft ? false : validation_error("Bad status code. Expected <urn:oasis:names:tc:SAML:2.0:status:Success>, but was: <#@status_code> ")
+          return append_error("Bad status code. Expected <urn:oasis:names:tc:SAML:2.0:status:Success>, but was: <#@status_code>")
         end
         true
       end
 
+      # @return [String|nil] Gets the InResponseTo attribute from the Logout Response if exists.
+      #
       def in_response_to
         @in_response_to ||= begin
-          node = REXML::XPath.first(document, "/p:LogoutResponse", { "p" => PROTOCOL, "a" => ASSERTION })
+          node = REXML::XPath.first(
+            document,
+            "/p:LogoutResponse",
+            { "p" => PROTOCOL, "a" => ASSERTION }
+          )
           node.nil? ? nil : node.attributes['InResponseTo']
         end
       end
 
+      # @return [String] Gets the Issuer from the Logout Response.
+      #
       def issuer
         @issuer ||= begin
-          node = REXML::XPath.first(document, "/p:LogoutResponse/a:Issuer", { "p" => PROTOCOL, "a" => ASSERTION })
-          node ||= REXML::XPath.first(document, "/p:LogoutResponse/a:Assertion/a:Issuer", { "p" => PROTOCOL, "a" => ASSERTION })
-          Utils.element_text(node)
+          node = REXML::XPath.first(
+            document,
+            "/p:LogoutResponse/a:Issuer",
+            { "p" => PROTOCOL, "a" => ASSERTION }
+          )
+          node.nil? ? nil : node.text
         end
       end
 
+      # @return [String] Gets the StatusCode from a Logout Response.
+      #
       def status_code
         @status_code ||= begin
           node = REXML::XPath.first(document, "/p:LogoutResponse/p:Status/p:StatusCode", { "p" => PROTOCOL, "a" => ASSERTION })
@@ -69,46 +105,137 @@ module OneLogin
         end
       end
 
+      def status_message
+        @status_message ||= begin
+          node = REXML::XPath.first(
+            document,
+            "/p:LogoutResponse/p:Status/p:StatusMessage",
+            { "p" => PROTOCOL, "a" => ASSERTION }
+          )
+          node.text if node
+        end
+      end
+
+      # Aux function to validate the Logout Response
+      # @return [Boolean] TRUE if the SAML Response is valid
+      # @raise [ValidationError] if soft == false and validation fails
+      #
+      def validate
+        reset_errors!
+
+        valid_state? &&
+        validate_success_status &&
+        validate_structure &&
+        valid_in_response_to? &&
+        valid_issuer? &&
+        validate_signature
+      end
+
       private
 
-      def valid_state?(soft = true)
-        if response.empty?
-          return soft ? false : validation_error("Blank response")
-        end
+      # Validates the Status of the Logout Response
+      # If fails, the error is added to the errors array, including the StatusCode returned and the Status Message.
+      # @return [Boolean] True if the Logout Response contains a Success code, otherwise False if soft=True
+      # @raise [ValidationError] if soft == false and validation fails
+      #
+      def validate_success_status
+        return true if success?
 
-        if settings.nil?
-          return soft ? false : validation_error("No settings on response")
-        end
+        error_msg = 'The status code of the Logout Response was not Success'
+        status_error_msg = OneLogin::RubySaml::Utils.status_error_msg(error_msg, status_code, status_message)
+        append_error(status_error_msg)
+      end
 
-        if settings.issuer.nil?
-          return soft ? false : validation_error("No issuer in settings")
+      # Validates the Logout Response against the specified schema.
+      # @return [Boolean] True if the XML is valid, otherwise False if soft=True
+      # @raise [ValidationError] if soft == false and validation fails 
+      #
+      def validate_structure
+        unless valid_saml?(document, soft)
+          return append_error("Invalid SAML Logout Response. Not match the saml-schema-protocol-2.0.xsd")
         end
 
+        true
+      end
+
+       # Validates that the Logout Response provided in the initialization is not empty,
+       # also check that the setting and the IdP cert were also provided
+       # @return [Boolean] True if the required info is found, otherwise False if soft=True
+       # @raise [ValidationError] if soft == false and validation fails
+       #
+      def valid_state?
+        return append_error("Blank logout response") if response.empty?
+
+        return append_error("No settings on logout response") if settings.nil?
+
+        return append_error("No issuer in settings of the logout response") if settings.issuer.nil?
+
         if settings.idp_cert_fingerprint.nil? && settings.idp_cert.nil?
-          return soft ? false : validation_error("No fingerprint or certificate on settings")
+          return append_error("No fingerprint or certificate on settings of the logout response")
         end
 
         true
       end
 
-      def valid_in_response_to?(soft = true)
-        return true unless self.options.has_key? :matches_request_id
+      # Validates if a provided :matches_request_id matchs the inResponseTo value.
+      # @param soft [String|nil] request_id The ID of the Logout Request sent by this SP to the IdP (if was sent any)
+      # @return [Boolean] True if there is no request_id or it match, otherwise False if soft=True
+      # @raise [ValidationError] if soft == false and validation fails
+      #
+      def valid_in_response_to?
+        return true unless options.has_key? :matches_request_id
 
-        unless self.options[:matches_request_id] == in_response_to
-          return soft ? false : validation_error("Response does not match the request ID, expected: <#{self.options[:matches_request_id]}>, but was: <#{in_response_to}>")
+        unless options[:matches_request_id] == in_response_to
+          return append_error("Response does not match the request ID, expected: <#{options[:matches_request_id]}>, but was: <#{in_response_to}>")
         end
 
         true
       end
 
-      def valid_issuer?(soft = true)
-        return true if self.settings.idp_entity_id.nil? or self.issuer.nil?
+      # Validates the Issuer of the Logout Response
+      # @return [Boolean] True if the Issuer matchs the IdP entityId, otherwise False if soft=True
+      # @raise [ValidationError] if soft == false and validation fails
+      #
+      def valid_issuer?
+        return true if settings.idp_entity_id.nil? || issuer.nil?
 
-        unless URI.parse(self.issuer) == URI.parse(self.settings.idp_entity_id)
-          return soft ? false : validation_error("Doesn't match the issuer, expected: <#{self.settings.issuer}>, but was: <#{issuer}>")
+        unless URI.parse(issuer) == URI.parse(settings.idp_entity_id)
+          return append_error("Doesn't match the issuer, expected: <#{settings.idp_entity_id}>, but was: <#{issuer}>")
         end
         true
       end
+
+      # Validates the Signature if it exists and the GET parameters are provided
+      # @return [Boolean] True if not contains a Signature or if the Signature is valid, otherwise False if soft=True
+      # @raise [ValidationError] if soft == false and validation fails
+      #      
+      def validate_signature
+        return true unless !options.nil?
+        return true unless options.has_key? :get_params
+        return true unless options[:get_params].has_key? 'Signature'
+        return true if settings.nil? || settings.get_idp_cert.nil?
+        
+        query_string = OneLogin::RubySaml::Utils.build_query(
+          :type        => 'SAMLResponse',
+          :data        => options[:get_params]['SAMLResponse'],
+          :relay_state => options[:get_params]['RelayState'],
+          :sig_alg     => options[:get_params]['SigAlg']
+        )
+
+        valid = OneLogin::RubySaml::Utils.verify_signature(
+          :cert         => settings.get_idp_cert,
+          :sig_alg      => options[:get_params]['SigAlg'],
+          :signature    => options[:get_params]['Signature'],
+          :query_string => query_string
+        )
+
+        unless valid
+          error_msg = "Invalid Signature on Logout Response"
+          return append_error(error_msg)
+        end
+        true        
+      end
+
     end
   end
 end