Update branch

Author: pitbulk

README.md

@@ -9,7 +9,37 @@ The Ruby SAML library is for implementing the client side of a SAML authorizatio
 
 SAML authorization is a two step process and you are expected to implement support for both.
 
-## The initialization phase
+## Getting Started
+In order to use the toolkit you will need to install the gem (either manually or using Bundler), and require the library in your Ruby application:
+
+Using `Gemfile`
+
+```ruby
+# latest stable
+gem 'ruby-saml', '~> 0.8.1'
+
+# or track master for bleeding-edge
+gem 'ruby-saml', :github => 'onelogin/ruby-saml'
+```
+
+Using Bundler
+
+```sh
+gem install ruby-saml
+```
+
+When requiring the gem, you can add the whole toolkit
+```ruby
+require 'onelogin/ruby-saml'
+```
+
+or just the required components individually:
+
+```ruby
+require 'onelogin/ruby-saml/authrequest'
+```
+
+## The Initialization Phase
 
 This is the first request you will get from the identity provider. It will hit your application at a specific URL (that you've announced as being your SAML initialization point). The response to this initialization, is a redirect back to the identity provider, which can look something like this (ignore the saml_settings method call for now):
 
@@ -46,6 +76,7 @@ def saml_settings
   settings.idp_sso_target_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"
 
@@ -84,8 +115,10 @@ class SamlController < ApplicationController
     settings.idp_sso_target_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"
+
     # Optional. Describe according to IdP specification (if supported) which attributes the SP desires to receive in SAMLResponse.
     settings.attributes_index = 30
 
@@ -94,8 +127,8 @@ class SamlController < ApplicationController
 end
 ```
 
-If are using saml:AttributeStatement to transfare metadata, like the user name, you can access all the attributes through `response.attributes`. It
-contains all the saml:AttributeStatement with its 'Name' as a indifferent key and the one saml:AttributeValue as value.
+
+If are using saml:AttributeStatement to transfare metadata, like the user name, you can access all the attributes through `response.attributes`. It contains all the saml:AttributeStatement with its 'Name' as a indifferent key and the one saml:AttributeValue as value.
 
 ```ruby
 response          = OneLogin::RubySaml::Response.new(params[:SAMLResponse])
@@ -113,8 +146,8 @@ If we want to add a saml:AuthnContextDeclRef, define a `settings.authn_context_d
 To form a trusted pair relationship with the IdP, the SP (you) need to provide metadata XML
 to the IdP for various good reasons.  (Caching, certificate lookups, relaying party permissions, etc)
 
-The class OneLogin::RubySaml::Metadata takes care of this by reading the Settings and returning XML.  All
-you have to do is add a controller to return the data, then give this URL to the IdP administrator.
+The class `OneLogin::RubySaml::Metadata` takes care of this by reading the Settings and returning XML.  All you have to do is add a controller to return the data, then give this URL to the IdP administrator.
+
 The metdata will be polled by the IdP every few minutes, so updating your settings should propagate
 to the IdP settings.
 
@@ -143,11 +176,11 @@ response = OneLogin::RubySaml::Response.new(params[:SAMLResponse], :allowed_cloc
 
 Make sure to keep the value as comfortably small as possible to keep security risks to a minimum.
 
-## Note on Patches/Pull Requests
+## Adding Features, Pull Requests
 
-* Fork the project.
-* Make your feature addition or bug fix.
-* Add tests for it. This is important so I don't break it in a
-  future version unintentionally.
-* Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
-* Send me a pull request. Bonus points for topic branches.
+* Fork the repository
+* Make your feature addition or bug fix
+* Add tests for your new features. This is important so we don't break any features in a future version unintentionally.
+* Ensure all tests pass.
+* Do not change rakefile, version, or history.
+* Open a pull request, following [this template](https://gist.github.com/Lordnibbler/11002759).

lib/onelogin/ruby-saml/authrequest.rb

@@ -5,6 +5,8 @@
 require "rexml/document"
 require "rexml/xpath"
 
+require "onelogin/ruby-saml/logging"
+
 module OneLogin
   module RubySaml
   include REXML

lib/onelogin/ruby-saml/metadata.rb

@@ -2,6 +2,8 @@
 require "rexml/xpath"
 require "uri"
 
+require "onelogin/ruby-saml/logging"
+
 # Class to return SP metadata based on the settings requested.
 # Return this XML in a controller, then give that URL to the the
 # IdP administrator.  The IdP will poll the URL and your settings

lib/onelogin/ruby-saml/response.rb

@@ -13,16 +13,18 @@ class Response
 
       # TODO: This should probably be ctor initialized too... WDYT?
       attr_accessor :settings
+      attr_accessor :errors
 
       attr_reader :options
       attr_reader :response
       attr_reader :document
 
       def initialize(response, options = {})
+        @errors = []
         raise ArgumentError.new("Response cannot be nil") if response.nil?
         @options  = options
         @response = (response =~ /^</) ? response : Base64.decode64(response)
-        @document = XMLSecurity::SignedDocument.new(@response)
+        @document = XMLSecurity::SignedDocument.new(@response, @errors)
       end
 
       def is_valid?
@@ -33,6 +35,10 @@ def validate!
         validate(false)
       end
 
+      def errors
+        @errors
+      end
+
       # The value of the user identifier as designated by the initialization request response
       def name_id
         @name_id ||= begin
@@ -153,9 +159,14 @@ def validate_structure(soft = true)
           @xml = Nokogiri::XML(self.document.to_s)
         end
         if soft
-          @schema.validate(@xml).map{ return false }
+          @schema.validate(@xml).map{
+            @errors << "Schema validation failed";
+            return false 
+          }
         else
-          @schema.validate(@xml).map{ |error| validation_error("#{error.message}\n\n#{@xml.to_s}") }
+          @schema.validate(@xml).map{ |error| @errors << "#{error.message}\n\n#{@xml.to_s}";
+            validation_error("#{error.message}\n\n#{@xml.to_s}")
+          }
         end
       end
 
@@ -197,10 +208,12 @@ def validate_conditions(soft = true)
         now = Time.now.utc
 
         if not_before && (now + (options[:allowed_clock_drift] || 0)) < not_before
+          @errors << "Current time is earlier than NotBefore condition #{(now + (options[:allowed_clock_drift] || 0))} < #{not_before})"
           return soft ? false : validation_error("Current time is earlier than NotBefore condition")
         end
 
         if not_on_or_after && now >= not_on_or_after
+          @errors << "Current time is on or after NotOnOrAfter condition (#{now} >= #{not_on_or_after})"
           return soft ? false : validation_error("Current time is on or after NotOnOrAfter condition")
         end
 

lib/xml_security.rb

@@ -38,9 +38,11 @@ class SignedDocument < REXML::Document
     DSIG = "http://www.w3.org/2000/09/xmldsig#"
 
     attr_accessor :signed_element_id
+    attr_accessor :errors
 
-    def initialize(response)
+    def initialize(response, errors = [])
       super(response)
+      @errors = errors
       extract_signed_element_id
     end
 
@@ -62,6 +64,7 @@ def validate_document(idp_cert_fingerprint, soft = true)
       fingerprint = Digest::SHA1.hexdigest(cert.to_der)
 
       if fingerprint != idp_cert_fingerprint.gsub(/[^a-zA-Z0-9]/,"").downcase
+        @errors << "Fingerprint mismatch"
         return soft ? false : (raise OneLogin::RubySaml::ValidationError.new("Fingerprint mismatch"))
       end
 
@@ -108,6 +111,7 @@ def validate_signature(base64_cert, soft = true)
         digest_value                  = Base64.decode64(REXML::XPath.first(ref, "//ds:DigestValue", {"ds"=>DSIG}).text)
 
         unless digests_match?(hash, digest_value)
+          @errors << "Digest mismatch"
           return soft ? false : (raise OneLogin::RubySaml::ValidationError.new("Digest mismatch"))
         end
       end
@@ -123,6 +127,7 @@ def validate_signature(base64_cert, soft = true)
       signature_algorithm     = algorithm(REXML::XPath.first(signed_info_element, "//ds:SignatureMethod", {"ds"=>DSIG}))
 
       unless cert.public_key.verify(signature_algorithm.new, signature, canon_string)
+        @errors << "Key validation error"
         return soft ? false : (raise OneLogin::RubySaml::ValidationError.new("Key validation error"))
       end
 

test/response_test.rb

@@ -53,6 +53,14 @@ class RubySamlTest < Test::Unit::TestCase
       end
     end
 
+    context "#validate_structure" do
+      should "raise when encountering a condition that prevents the document from being valid" do
+        response = OneLogin::RubySaml::Response.new(response_document_2)
+        response.send(:validate_structure)
+        assert response.errors.include? "Schema validation failed"
+      end
+    end
+
     context "#is_valid?" do
       should "return false when response is initialized with blank data" do
         response = OneLogin::RubySaml::Response.new('')

test/xml_security_test.rb

@@ -40,13 +40,15 @@ class XmlSecurityTest < Test::Unit::TestCase
         @document.validate_document("no:fi:ng:er:pr:in:t", false)
       end
       assert_equal("Fingerprint mismatch", exception.message)
+      assert @document.errors.include? "Fingerprint mismatch"
     end
 
     should "should raise Digest mismatch" do
       exception = assert_raise(OneLogin::RubySaml::ValidationError) do
         @document.validate_signature(@base64cert, false)
       end
       assert_equal("Digest mismatch", exception.message)
+      assert @document.errors.include? "Digest mismatch"
     end
 
     should "should raise Key validation error" do
@@ -59,6 +61,7 @@ class XmlSecurityTest < Test::Unit::TestCase
         document.validate_signature(base64cert, false)
       end
       assert_equal("Key validation error", exception.message)
+      assert document.errors.include? "Key validation error"
     end
 
     should "correctly obtain the digest method with alternate namespace declaration" do