ruby-saml 0.9.4 → 1.0.0

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

@@ -6,8 +6,12 @@ require 'rexml/document'
 require 'rexml/xpath'
 require 'thread'
 
+# Only supports SAML 2.0
 module OneLogin
   module RubySaml
+
+    # SAML2 Message
+    #
     class SamlMessage
       include REXML
 
@@ -16,6 +20,8 @@ module OneLogin
 
       BASE64_FORMAT = %r(\A[A-Za-z0-9+/]{4}*[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=?\Z)
 
+      # @return [Nokogiri::XML::Schema] Gets the schema object of the SAML 2.0 Protocol schema
+      #
       def self.schema
         @schema ||= Mutex.new.synchronize do
           Dir.chdir(File.expand_path("../../../schemas", __FILE__)) do
@@ -24,29 +30,68 @@ module OneLogin
         end
       end
 
+      # @return [String|nil] Gets the Version attribute from the SAML Message if exists.
+      #
+      def version(document)
+        @version ||= begin
+          node = REXML::XPath.first(
+            document,
+            "/p:AuthnRequest | /p:Response | /p:LogoutResponse | /p:LogoutRequest",
+            { "p" => PROTOCOL }
+          )
+          node.nil? ? nil : node.attributes['Version']
+        end
+      end
+
+      # @return [String|nil] Gets the ID attribute from the SAML Message if exists.
+      #
+      def id(document)
+        @id ||= begin
+          node = REXML::XPath.first(
+            document,
+            "/p:AuthnRequest | /p:Response | /p:LogoutResponse | /p:LogoutRequest",
+            { "p" => PROTOCOL }
+          )
+          node.nil? ? nil : node.attributes['ID']
+        end
+      end
+
+      # Validates the SAML Message against the specified schema.
+      # @param document [REXML::Document] The message that will be validated
+      # @param soft [Boolean] soft Enable or Disable the soft mode (In order to raise exceptions when the message is invalid or not)
+      # @return [Boolean] True if the XML is valid, otherwise False, if soft=True
+      # @raise [ValidationError] if soft == false and validation fails 
+      #
       def valid_saml?(document, soft = true)
-        xml = Nokogiri::XML(document.to_s)
+        begin
+          xml = Nokogiri::XML(document.to_s) do |config|
+            config.options = XMLSecurity::BaseDocument::NOKOGIRI_OPTIONS
+          end
+        rescue Exception => error
+          return false if soft
+          validation_error("XML load failed: #{error.message}")
+        end
 
         SamlMessage.schema.validate(xml).map do |error|
-          break false if soft
+          return false if soft
           validation_error("#{error.message}\n\n#{xml.to_s}")
         end
       end
 
+      # Raise a ValidationError with the provided message
+      # @param message [String] Message of the exception
+      # @raise [ValidationError]
+      #
       def validation_error(message)
         raise ValidationError.new(message)
       end
 
       private
 
-      ##
-      # Take a SAML object provided by +saml+, determine its status and return
-      # a decoded XML as a String.
+      # Base64 decode and try also to inflate a SAML Message
+      # @param saml [String] The deflated and encoded SAML Message
+      # @return [String] The plain SAML Message
       #
-      # Since SAML decided to use the RFC1951 and therefor has no zlib markers,
-      # the only reliable method of deciding whether we have a zlib stream or not
-      # is to try and inflate it and fall back to the base64 decoded string if
-      # the stream contains errors.
       def decode_raw_saml(saml)
         return saml unless base64_encoded?(saml)
 
@@ -58,32 +103,53 @@ module OneLogin
         end
       end
 
+      # Deflate, base64 encode and url-encode a SAML Message (To be used in the HTTP-redirect binding)
+      # @param saml [String] The plain SAML Message
+      # @param settings [OneLogin::RubySaml::Settings|nil] Toolkit settings
+      # @return [String] The deflated and encoded SAML Message (encoded if the compression is requested)
+      #
       def encode_raw_saml(saml, settings)
         saml = deflate(saml) if settings.compress_request
 
         CGI.escape(Base64.encode64(saml))
       end
 
-      def decode(encoded)
-        Base64.decode64(encoded)
+      # Base 64 decode method
+      # @param string [String] The string message
+      # @return [String] The decoded string
+      #
+      def decode(string)
+        Base64.decode64(string)
       end
 
-      def encode(encoded)
-        Base64.encode64(encoded).gsub(/\n/, "")
+      # Base 64 encode method
+      # @param string [String] The string
+      # @return [String] The encoded string
+      #
+      def encode(string)
+        Base64.encode64(string).gsub(/\n/, "")
       end
 
       # Check if a string is base64 encoded
-      #
       # @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(/[\r\n]|\\r|\\n/, "").match(BASE64_FORMAT)
       end
 
+      # Inflate method
+      # @param deflated [String] The string
+      # @return [String] The inflated string
+      #
       def inflate(deflated)
         Zlib::Inflate.new(-Zlib::MAX_WBITS).inflate(deflated)
       end
 
+      # Deflate method
+      # @param inflated [String] The string
+      # @return [String] The deflated string
+      #
       def deflate(inflated)
         Zlib::Deflate.deflate(inflated, 9)[2..-5]
       end

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

@@ -2,16 +2,20 @@ require "xml_security"
 require "onelogin/ruby-saml/attribute_service"
 require "onelogin/ruby-saml/utils"
 
+# Only supports SAML 2.0
 module OneLogin
   module RubySaml
+
+    # SAML2 Toolkit Settings
+    #
     class Settings
       def initialize(overrides = {})
         config = DEFAULTS.merge(overrides)
         config.each do |k,v|
           acc = "#{k.to_s}=".to_sym
-          if self.respond_to? acc
+          if respond_to? acc
             value = v.is_a?(Hash) ? v.dup : v
-            self.send(acc, value)
+            send(acc, value)
           end
         end
         @attribute_consuming_service = AttributeService.new
@@ -39,18 +43,22 @@ module OneLogin
       attr_accessor :protocol_binding
       attr_accessor :attributes_index
       attr_accessor :force_authn
-      attr_accessor :security
       attr_accessor :certificate
       attr_accessor :private_key
       attr_accessor :authn_context
       attr_accessor :authn_context_comparison
       attr_accessor :authn_context_decl_ref
       attr_reader :attribute_consuming_service
+      # Work-flow
+      attr_accessor :security
+      attr_accessor :soft
       # Compability
       attr_accessor :assertion_consumer_logout_service_url
       attr_accessor :assertion_consumer_logout_service_binding
 
-      def single_logout_service_url()
+      # @return [String] Single Logout Service URL.
+      #
+      def single_logout_service_url
         val = nil
         if @single_logout_service_url.nil?
           if @assertion_consumer_logout_service_url
@@ -62,12 +70,16 @@ module OneLogin
         val
       end
 
-      # setter
-      def single_logout_service_url=(val)
-        @single_logout_service_url = val
+      # Setter for the Single Logout Service URL.
+      # @param url [String].
+      #
+      def single_logout_service_url=(url)
+        @single_logout_service_url = url
       end
 
-      def single_logout_service_binding()
+      # @return [String] Single Logout Service Binding.
+      #
+      def single_logout_service_binding
         val = nil
         if @single_logout_service_binding.nil?
           if @assertion_consumer_logout_service_binding
@@ -79,27 +91,53 @@ module OneLogin
         val
       end
 
-      # setter
-      def single_logout_service_binding=(val)
-        @single_logout_service_binding = val
+      # Setter for Single Logout Service Binding.
+      # 
+      # (Currently we only support "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect")
+      # @param url [String]
+      #
+      def single_logout_service_binding=(url)
+        @single_logout_service_binding = url
       end
 
-      def get_sp_cert
-        cert = nil
-        if self.certificate
-          formated_cert = OneLogin::RubySaml::Utils.format_cert(self.certificate)
-          cert = OpenSSL::X509::Certificate.new(formated_cert)
+      # Calculates the fingerprint of the IdP x509 certificate.
+      # @return [String] The fingerprint
+      #
+      def get_fingerprint
+        idp_cert_fingerprint || begin
+          idp_cert = get_idp_cert
+          if idp_cert
+            fingerprint_alg = XMLSecurity::BaseDocument.new.algorithm(idp_cert_fingerprint_algorithm).new
+            fingerprint_alg.hexdigest(idp_cert.to_der).upcase.scan(/../).join(":")
+          end
         end
-        cert
       end
 
+      # @return [OpenSSL::X509::Certificate|nil] Build the IdP certificate from the settings (previously format it)
+      #
+      def get_idp_cert
+        return nil if idp_cert.nil? || idp_cert.empty?
+
+        formated_cert = OneLogin::RubySaml::Utils.format_cert(idp_cert)
+        OpenSSL::X509::Certificate.new(formated_cert)
+      end
+
+      # @return [OpenSSL::X509::Certificate|nil] Build the SP certificate from the settings (previously format it)
+      #
+      def get_sp_cert
+        return nil if certificate.nil? || certificate.empty?
+
+        formated_cert = OneLogin::RubySaml::Utils.format_cert(certificate)
+        OpenSSL::X509::Certificate.new(formated_cert)
+      end
+
+      # @return [OpenSSL::PKey::RSA] Build the SP private from the settings (previously format it)
+      #
       def get_sp_key
-        private_key = nil
-        if self.private_key
-          formated_private_key = OneLogin::RubySaml::Utils.format_private_key(self.private_key)
-          private_key = OpenSSL::PKey::RSA.new(formated_private_key)
-        end
-        private_key
+        return nil if private_key.nil? || private_key.empty?
+        
+        formated_private_key = OneLogin::RubySaml::Utils.format_private_key(private_key)
+        OpenSSL::PKey::RSA.new(formated_private_key)
       end
 
       private
@@ -110,6 +148,7 @@ module OneLogin
         :idp_cert_fingerprint_algorithm            => XMLSecurity::Document::SHA1,
         :compress_request                          => true,
         :compress_response                         => true,
+        :soft                                      => true,
         :security                                  => {
           :authn_requests_signed    => false,
           :logout_requests_signed   => false,

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

@@ -7,59 +7,249 @@ require "onelogin/ruby-saml/saml_message"
 # Only supports SAML 2.0
 module OneLogin
   module RubySaml
+
+    # SAML2 Logout Request (SLO IdP initiated, Parser)
+    #
     class SloLogoutrequest < SamlMessage
-      attr_reader :options
-      attr_reader :request
+
+      # OneLogin::RubySaml::Settings Toolkit settings
+      attr_accessor :settings
+
+      # Array with the causes [Array of strings]
+      attr_accessor :errors
+
       attr_reader :document
+      attr_reader :request
+      attr_reader :options
 
+      attr_accessor :soft
+
+      # Constructs the Logout Request. A Logout Request Object that is an extension of the SamlMessage class.
+      # @param request [String] A UUEncoded Logout Request from the IdP.
+      # @param options [Hash]  :settings to provide the OneLogin::RubySaml::Settings object 
+      #                        Or :allowed_clock_drift for the logout request validation process to allow a clock drift when checking dates with
+      #
+      # @raise [ArgumentError] If Request is nil
+      #
       def initialize(request, options = {})
+        @errors = []
         raise ArgumentError.new("Request cannot be nil") if request.nil?
         @options  = options
+
+        @soft = true
+        if !options.empty? && !options[:settings].nil?
+          @settings = options[:settings]
+          if !options[:settings].soft.nil? 
+            @soft = options[:settings].soft
+          end
+        end
+
         @request = decode_raw_saml(request)
         @document = REXML::Document.new(@request)
       end
 
-      def is_valid?
-        validate
+      # 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!
-        validate(false)
+      # Reset the errors array
+      def reset_errors!
+        @errors = []
       end
 
-      # The value of the user identifier as designated by the initialization request response
+      # Validates the Logout Request with the default values (soft = true)
+      # @return [Boolean] TRUE if the Logout Request is valid
+      #
+      def is_valid?
+        validate
+      end
+
+      # @return [String] Gets the NameID of the Logout Request.
+      #
       def name_id
         @name_id ||= begin
           node = REXML::XPath.first(document, "/p:LogoutRequest/a:NameID", { "p" => PROTOCOL, "a" => ASSERTION })
-          Utils.element_text(node)
+          node.nil? ? nil : node.text
         end
       end
 
+      alias_method :nameid, :name_id
+
+      # @return [String|nil] Gets the ID attribute from the Logout Request. if exists.
+      #
       def id
-        return @id if @id
-        element = REXML::XPath.first(document, "/p:LogoutRequest", {
-            "p" => PROTOCOL} )
-        return nil if element.nil?
-        return element.attributes["ID"]
+        super(document)
       end
 
+      # @return [String] Gets the Issuer from the Logout Request.
+      #
       def issuer
         @issuer ||= begin
-          node = REXML::XPath.first(document, "/p:LogoutRequest/a:Issuer", { "p" => PROTOCOL, "a" => ASSERTION })
-          Utils.element_text(node)
+          node = REXML::XPath.first(
+            document,
+            "/p:LogoutRequest/a:Issuer",
+            { "p" => PROTOCOL, "a" => ASSERTION }
+          )
+          node.nil? ? nil : node.text
+        end
+      end
+
+      # @return [Time|nil] Gets the NotOnOrAfter Attribute value if exists.
+      #
+      def not_on_or_after
+        @not_on_or_after ||= begin
+          node = REXML::XPath.first(
+            document,
+            "/p:LogoutRequest",
+            { "p" => PROTOCOL }
+          )
+          if node && node.attributes["NotOnOrAfter"]
+            Time.parse(node.attributes["NotOnOrAfter"])
+          end
         end
       end
 
+      # @return [Array] Gets the SessionIndex if exists (Supported multiple values). Empty Array if none found
+      #
+      def session_indexes
+        s_indexes = []
+        nodes = REXML::XPath.match(
+          document,
+          "/p:LogoutRequest/p:SessionIndex",
+          { "p" => PROTOCOL }
+        )
+
+        nodes.each do |node|
+          s_indexes << node.text
+        end
+
+        s_indexes
+      end
+
       private
 
-      def validate(soft = true)
-        valid_saml?(document, soft)  && validate_request_state(soft)
+      # Hard aux function to validate the Logout Request
+      # @return [Boolean] TRUE if the Logout Request is valid
+      # @raise [ValidationError] if soft == false and validation fails
+      #
+      def validate
+        reset_errors!
+
+        validate_request_state &&
+        validate_id &&
+        validate_version &&        
+        validate_structure &&
+        validate_not_on_or_after &&
+        validate_issuer &&
+        validate_signature
+      end
+
+      # Validates that the Logout Request contains an ID
+      # If fails, the error is added to the errors array.
+      # @return [Boolean] True if the Logout Request contains an ID, otherwise returns False
+      #
+      def validate_id
+        unless id
+          return append_error("Missing ID attribute on Logout Request")
+        end
+
+        true
+      end
+
+      # Validates the SAML version (2.0)
+      # If fails, the error is added to the errors array.
+      # @return [Boolean] True if the Logout Request is 2.0, otherwise returns False
+      #
+      def validate_version
+        unless version(document) == "2.0"
+          return append_error("Unsupported SAML version")
+        end
+
+        true
+      end
+
+      # Validates the time. (If the logout request was initialized with the :allowed_clock_drift option, the timing validations are relaxed by the allowed_clock_drift value)
+      # If fails, the error is added to the errors array
+      # @return [Boolean] True if satisfies the conditions, otherwise False if soft=True
+      # @raise [ValidationError] if soft == false and validation fails
+      #
+      def validate_not_on_or_after
+        now = Time.now.utc
+        if not_on_or_after && now >= (not_on_or_after + (options[:allowed_clock_drift] || 0))
+          return append_error("Current time is on or after NotOnOrAfter (#{now} >= #{not_on_or_after})")
+        end
+
+        true
       end
 
-      def validate_request_state(soft = true)
-        if request.empty?
-          return soft ? false : validation_error("Blank request")
+      # Validates the Logout Request 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 Request. Not match the saml-schema-protocol-2.0.xsd")
         end
+
+        true
+      end
+
+      # Validates that the Logout Request provided in the initialization is not empty, 
+      # @return [Boolean] True if the required info is found, otherwise False if soft=True
+      # @raise [ValidationError] if soft == false and validation fails
+      #
+      def validate_request_state
+        return append_error("Blank logout request") if request.nil? || request.empty?
+
+        true
+      end
+
+      # Validates the Issuer of the Logout Request
+      # If fails, the error is added to the errors array
+      # @return [Boolean] True if the Issuer matchs the IdP entityId, otherwise False if soft=True
+      # @raise [ValidationError] if soft == false and validation fails
+      #
+      def validate_issuer
+        return true if settings.idp_entity_id.nil? || issuer.nil?
+
+        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 exists and 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 if 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        => 'SAMLRequest',
+          :data        => options[:get_params]['SAMLRequest'],
+          :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
+          return append_error("Invalid Signature on Logout Request")
+        end
+
         true
       end