ruby-saml 0.9.4 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e6899da69ca7253760c8766c25579be80e078459
-  data.tar.gz: a38aa8ac9f56af0ecc11d2a41143570f3ba2c55f
+  metadata.gz: 381e8f35422cfa0bbb991272a777f7fdfcdd2081
+  data.tar.gz: 0371c2cbd05ee2b482fca1feda05a82162550295
 SHA512:
-  metadata.gz: 9bbe6c965d9d01e30e48e7378d98bfe0daae344f83e3a63349a51df674c9e59bf9f4d1304c01a3e040f1c1aabeb87040d2e1ee9a6866a7161c58fef251ecafcc
-  data.tar.gz: ee92e4423bedfb8889b56cb763754cdafd24e4f5ec42cd36e904169af827c14422412f0a5537899abab47a1a210bb9f960439b988f30ff343a1853954a85bafc
+  metadata.gz: a3553e3802bba3fe72375cf5865dfce58a5bf46efa335a43e49f020ee12691bd099ecc3496be389a2556808ad4428bd79d4c4a51171c582df8ac74d66187e2a0
+  data.tar.gz: 473180d499b2ffd2648438ce2c4fd103a8b314ccfa18145cb72215edeecc0864f53dbf016ccd66f6025cdb45aca241df14ca3e9f7ec36731ba4a4004ef0b3a6f

data/.gitignore

@@ -4,6 +4,7 @@ coverage
 rdoc
 pkg
 Gemfile.lock
+gemfiles/*.lock
 .idea/*
 lib/Lib.iml
 test/Test.iml

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2010 OneLogin, LLC
+Copyright (c) 2010-2015 OneLogin, LLC
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,7 +1,19 @@
 # Ruby SAML [![Build Status](https://secure.travis-ci.org/onelogin/ruby-saml.png)](http://travis-ci.org/onelogin/ruby-saml)
 
+
+## Updating from 0.9.x to 1.0.X
+
+Version `1.0` is a recommended update for all Ruby SAML users as it includes security fixes.
+
+Version `1.0` adds security improvements like entity expansion limitation, more SAML message validations, and other important improvements like decrypt support.
+
+For more details, please review [the changelog](changelog.md).
+
+### Important Changes
+Please note the `get_idp_metadata` method raises an exception when it is not able to fetch the idp metadata, so review your integration if you are using this functionality.
+
 ## Updating from 0.8.x to 0.9.x
-Version `0.9` adds many new features and improvements. It is a recommended update for all Ruby SAML users. For more details, please review [the changelog](changelog.md)
+Version `0.9` adds many new features and improvements.
 
 ## Updating from 0.7.x to 0.8.x
 Version `0.8.x` changes the namespace of the gem from `OneLogin::Saml` to `OneLogin::RubySaml`.  Please update your implementations of the gem accordingly.
@@ -18,7 +30,7 @@ We created a demo project for Rails4 that uses the latest version of this librar
 * 1.8.7
 * 1.9.x
 * 2.1.x
-* 2.2.0
+* 2.2.x
 
 ## Adding Features, Pull Requests
 * Fork the repository
@@ -35,7 +47,7 @@ Using `Gemfile`
 
 ```ruby
 # latest stable
-gem 'ruby-saml', '~> 0.9.1'
+gem 'ruby-saml', '~> 1.0.0'
 
 # or track master for bleeding-edge
 gem 'ruby-saml', :github => 'onelogin/ruby-saml'
@@ -74,6 +86,19 @@ Using RubyGems
 gem install nokogiri --version '~> 1.5.10'
 ````
 
+### Configuring Logging
+
+When troubleshooting SAML integration issues, you will find it extremely helpful to examine the
+output of this gem's business logic. By default, log messages are emitted to RAILS_DEFAULT_LOGGER
+when the gem is used in a Rails context, and to STDOUT when the gem is used outside of Rails.
+
+To override the default behavior and control the destination of log messages, provide
+a ruby Logger object to the gem's logging singleton:
+
+```ruby
+OneLogin::RubySaml::Logging.logger = Logger.new(File.open('/var/log/ruby-saml.log', 'w')
+```
+
 ## 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):
@@ -89,13 +114,12 @@ Once you've redirected back to the identity provider, it will ensure that the us
 
 ```ruby
 def consume
-  response          = OneLogin::RubySaml::Response.new(params[:SAMLResponse])
-  response.settings = saml_settings
+  response = OneLogin::RubySaml::Response.new(params[:SAMLResponse], :settings => saml_settings)
 
   # We validate the SAML Response and check if the user already exists in the system
   if response.is_valid?
      # authorize_success, log the user
-     session[:userid] = response.name_id
+     session[:userid] = response.nameid
      session[:attributes] = response.attributes
   else
     authorize_failure  # This method shows an error message
@@ -103,14 +127,24 @@ def consume
 end
 ```
 
-In the above there are a few assumptions in place, one being that the response.name_id is an email address. This is all handled with how you specify the settings that are in play via the saml_settings method. That could be implemented along the lines of this:
+In the above there are a few assumptions in place, one being that the response.nameid is an email address. This is all handled with how you specify the settings that are in play via the saml_settings method. That could be implemented along the lines of this:
+
+If the assertion of the SAMLResponse is not encrypted, you can initialize the Response without the :settings parameter and set it later,
+
+```
+response = OneLogin::RubySaml::Response.new(params[:SAMLResponse])
+response.settings = saml_settings
+```
+but if the SAMLResponse contains an encrypted assertion, you need to provide the settings in the
+initialize method in order to be able to obtain the decrypted assertion, using the service provider private key in order to decrypt.
+If you don't know what expect, use always the first proposed way (always set the settings on the initialize method).
 
 ```ruby
 def saml_settings
   settings = OneLogin::RubySaml::Settings.new
 
-  settings.assertion_consumer_service_url = "http://#{request.host}/saml/finalize"
-  settings.issuer                         = request.host
+  settings.assertion_consumer_service_url = "http://#{request.host}/saml/consume"
+  settings.issuer                         = "http://#{request.host}/saml/metadata"
   settings.idp_sso_target_url             = "https://app.onelogin.com/saml/metadata/#{OneLoginAppId}"
   settings.idp_entity_id                  = "https://app.onelogin.com/saml/metadata/#{OneLoginAppId}"
   settings.idp_sso_target_url             = "https://app.onelogin.com/trust/saml2/http-post/sso/#{OneLoginAppId}"
@@ -124,7 +158,7 @@ def saml_settings
 
   # Optional bindings (defaults to Redirect for logout POST for acs)
   settings.assertion_consumer_service_binding = "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
-  settings.single_logout_service_url_binding = "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
+  settings.assertion_consumer_logout_service_binding = "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
 
   settings
 end
@@ -147,7 +181,7 @@ class SamlController < ApplicationController
     # We validate the SAML Response and check if the user already exists in the system
     if response.is_valid?
        # authorize_success, log the user
-       session[:userid] = response.name_id
+       session[:userid] = response.nameid
        session[:attributes] = response.attributes
     else
       authorize_failure  # This method shows an error message
@@ -160,7 +194,7 @@ class SamlController < ApplicationController
     settings = OneLogin::RubySaml::Settings.new
 
     settings.assertion_consumer_service_url = "http://#{request.host}/saml/consume"
-    settings.issuer                         = request.host
+    settings.issuer                         = "http://#{request.host}/saml/metadata"
     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"
@@ -196,7 +230,7 @@ def saml_settings
   settings = idp_metadata_parser.parse_remote("https://example.com/auth/saml2/idp/metadata")
 
   settings.assertion_consumer_service_url = "http://#{request.host}/saml/consume"
-  settings.issuer                         = request.host
+  settings.issuer                         = "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"
@@ -330,8 +364,8 @@ The Ruby Toolkit supports 2 different kinds of signature: Embeded and as GET par
 In order to be able to sign we need first to define the private key and the public cert of the service provider
 
 ```ruby
-  settings.certificate = "CERTIFICATE TEXT WITH HEADS"
-  settings.private_key = "PRIVATE KEY TEXT WITH HEADS"
+  settings.certificate = "CERTIFICATE TEXT WITH HEAD AND FOOT"
+  settings.private_key = "PRIVATE KEY TEXT WITH HEAD AND FOOT"
 ```
 
 The settings related to sign are stored in the `security` attribute of the settings:
@@ -354,6 +388,28 @@ Notice that the RelayState parameter is used when creating the Signature on the
 remember to provide it to the Signature builder if you are sending a GET RelayState parameter or
 Signature validation process will fail at the Identity Provider.
 
+The Service Provider will sign the request/responses with its private key.
+The Identity Provider will validate the sign of the received request/responses with the public x500 cert of the
+Service Provider.
+
+Notice that this toolkit uses 'settings.certificate' and 'settings.private_key' for the sign and the decrypt process.
+
+
+## Decrypting
+
+The Ruby Toolkit supports EncryptedAssertion.
+
+In order to be able to decrypt a SAML Response that contains a EncryptedAssertion we need first to define the private key and the public cert of the service provider, and share this with the Identity Provider.
+
+```ruby
+  settings.certificate = "CERTIFICATE TEXT WITH HEAD AND FOOT"
+  settings.private_key = "PRIVATE KEY TEXT WITH HEAD AND FOOT"
+```
+
+The Identity Provider will encrypt the Assertion with the public cert of the Service Provider.
+The Service Provider will decrypt the EncryptedAssertion with its private key.
+
+Notice that this toolkit uses 'settings.certificate' and 'settings.private_key' for the sign and the decrypt process.
 
 ## Single Log Out
 

data/changelog.md

@@ -1,10 +1,20 @@
 # RubySaml Changelog
 
-### 0.9.4 (March 5, 2018)
-* Improve the fix for CVE-2017-11428 to parse CDATA properly
-
-### 0.9.3 (Feb 27, 2018)
-* Fix vulnerability CVE-2017-11428. Process text of nodes properly, ignoring comments
+### 1.0.0 (June 30, 2015)
+* [#247](https://github.com/onelogin/ruby-saml/pull/247) Avoid entity expansion (XEE attacks)
+* [#246](https://github.com/onelogin/ruby-saml/pull/246) Fix bug generating Logout Response (issuer was at wrong order)
+* [#243](https://github.com/onelogin/ruby-saml/issues/243) and [#244](https://github.com/onelogin/ruby-saml/issues/244) Fix metadata builder errors. Fix metadata xsd.
+* [#241](https://github.com/onelogin/ruby-saml/pull/241) Add decrypt support (EncryptID and EncryptedAssertion). Improve compatibility with namespaces. 
+* [#240](https://github.com/onelogin/ruby-saml/pull/240) and [#238](https://github.com/onelogin/ruby-saml/pull/238) Improve test coverage and refactor.
+* [#239](https://github.com/onelogin/ruby-saml/pull/239) Improve security: Add more validations to SAMLResponse, LogoutRequest and LogoutResponse. Refactor code and improve tests coverage.
+* [#237](https://github.com/onelogin/ruby-saml/pull/237) Don't pretty print metadata by default.
+* [#235](https://github.com/onelogin/ruby-saml/pull/235) Remove the soft parameter from validation methods. Now can be configured on the settings and each class read it and store as an attribute of the class. Adding some validations and refactor old ones.
+* [#232](https://github.com/onelogin/ruby-saml/pull/232) Improve validations: Store the causes in the errors array, code refactor
+* [#231](https://github.com/onelogin/ruby-saml/pull/231) Refactor HTTP-Redirect Sign method, Move test data to right folder
+* [#226](https://github.com/onelogin/ruby-saml/pull/226) Ensure IdP certificate is formatted properly
+* [#225](https://github.com/onelogin/ruby-saml/pull/225) Add documentation to several methods. Fix xpath injection on xml_security.rb
+* [#223](https://github.com/onelogin/ruby-saml/pull/223) Allow logging to be delegated to an arbitrary Logger
+* [#222](https://github.com/onelogin/ruby-saml/pull/222) No more silent failure fetching idp metadata (OneLogin::RubySaml::HttpError raised).
 
 ### 0.9.2 (Apr 28, 2015)
 * [#216](https://github.com/onelogin/ruby-saml/pull/216) Add fingerprint algorithm support
@@ -22,7 +32,6 @@
 * [#179](https://github.com/onelogin/ruby-saml/pull/179) Add support for setting the entity ID and name ID format when parsing metadata
 * [#175](https://github.com/onelogin/ruby-saml/pull/175) Introduce thread safety to SAML schema validation
 * [#171](https://github.com/onelogin/ruby-saml/pull/171) Fix inconsistent results with using regex matches in decode_raw_saml
-* 
 
 ### 0.9.1 (Feb 10, 2015)
 * [#194](https://github.com/onelogin/ruby-saml/pull/194) Relax nokogiri gem requirements

data/lib/onelogin/ruby-saml.rb

@@ -9,6 +9,7 @@ require 'onelogin/ruby-saml/slo_logoutresponse'
 require 'onelogin/ruby-saml/response'
 require 'onelogin/ruby-saml/settings'
 require 'onelogin/ruby-saml/attribute_service'
+require 'onelogin/ruby-saml/http_error'
 require 'onelogin/ruby-saml/validation_error'
 require 'onelogin/ruby-saml/metadata'
 require 'onelogin/ruby-saml/idp_metadata_parser'

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

@@ -1,10 +1,15 @@
 module OneLogin
   module RubySaml
+
+    # SAML2 AttributeService. Auxiliary class to build the AttributeService of the SP Metadata
+    #
     class AttributeService
       attr_reader :attributes
       attr_reader :name
       attr_reader :index
 
+      # Initializes the AttributeService, set the index value as 1 and an empty array as attributes
+      #
       def initialize
         @index = "1"
         @attributes = []
@@ -14,20 +19,38 @@ module OneLogin
         instance_eval &block
       end
 
+      # @return [Boolean] True if the AttributeService object has been initialized and set with the required values
+      #                   (has attributes and a name)
       def configured?
         @attributes.length > 0 && !@name.nil?
       end
 
+      # Set a name to the service
+      # @param name [String] The service name
+      #
       def service_name(name)
         @name = name
       end
 
+      # Set an index to the service
+      # @param index [Integer] An index
+      #
       def service_index(index)
         @index = index
       end
-      
+
+      # Add an AttributeService
+      # @param options [Hash] AttributeService option values
+      #   add_attribute(
+      #                 :name => "Name",
+      #                 :name_format => "Name Format",
+      #                 :index => 1,
+      #                 :friendly_name => "Friendly Name",
+      #                 :attribute_value => "Attribute Value"
+      #                )
+      #
       def add_attribute(options={})
-        attributes << options 
+        attributes << options
       end
     end
   end

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

@@ -1,91 +1,110 @@
 module OneLogin
   module RubySaml
-    # Wraps all attributes and provides means to query them for single or multiple values.
-    # 
-    # For backwards compatibility Attributes#[] returns *first* value for the attribute.
-    # Turn off compatibility to make it return all values as an array:
-    #    Attributes.single_value_compatibility = false
+
+    # SAML2 Attributes. Parse the Attributes from the AttributeStatement of the SAML Response. 
+    #
     class Attributes
       include Enumerable
 
+      attr_reader :attributes
+
       # By default Attributes#[] is backwards compatible and
       # returns only the first value for the attribute
       # Setting this to `false` returns all values for an attribute
       @@single_value_compatibility = true
 
-      # Get current status of backwards compatibility mode.
+      # @return [Boolean] Get current status of backwards compatibility mode.
+      #
       def self.single_value_compatibility
         @@single_value_compatibility
       end
 
       # Sets the backwards compatibility mode on/off.
+      # @param value [Boolean]
+      #
       def self.single_value_compatibility=(value)
         @@single_value_compatibility = value
       end
 
-      # Initialize Attributes collection, optionally taking a Hash of attribute names and values.
-      #
-      # The +attrs+ must be a Hash with attribute names as keys and **arrays** as values:
+      # @param attrs [Hash] The +attrs+ must be a Hash with attribute names as keys and **arrays** as values:
       #    Attributes.new({
       #      'name' => ['value1', 'value2'],
       #      'mail' => ['value1'],
       #    })
+      #
       def initialize(attrs = {})
         @attributes = attrs
       end
 
 
       # Iterate over all attributes
+      #
       def each
         attributes.each{|name, values| yield name, values}
       end
 
+      
       # Test attribute presence by name
+      # @param name [String] The attribute name to be checked
+      #
       def include?(name)
         attributes.has_key?(canonize_name(name))
       end
       
       # Return first value for an attribute
+      # @param name [String] The attribute name
+      # @return [String] The value (First occurrence)
+      #
       def single(name)
         attributes[canonize_name(name)].first if include?(name)
       end
 
       # Return all values for an attribute
+      # @param name [String] The attribute name
+      # @return [Array] Values of the attribute
+      #
       def multi(name)
         attributes[canonize_name(name)]
       end
 
-      # By default returns first value for an attribute.
-      #
-      # Depending on the single value compatibility status this returns first value
-      #    Attributes.single_value_compatibility = true # Default
-      #    response.attributes['mail']  # => 'user@example.com'
+      # Retrieve attribute value(s)
+      # @param name [String] The attribute name
+      # @return [String|Array] Depending on the single value compatibility status this returns:
+      #                        - First value if single_value_compatibility = true
+      #                          response.attributes['mail']  # => 'user@example.com'
+      #                        - All values if single_value_compatibility = false
+      #                          response.attributes['mail']  # => ['user@example.com','user@example.net']
       #
-      # Or all values:
-      #    Attributes.single_value_compatibility = false
-      #    response.attributes['mail']  # => ['user@example.com','user@example.net']
       def [](name)
         self.class.single_value_compatibility ? single(canonize_name(name)) : multi(canonize_name(name))
       end
 
-      # Return all attributes as an array
+      # @return [Array] Return all attributes as an array
+      #
       def all
         attributes
       end
 
-      # Set values for an attribute, overwriting all existing values
+      # @param name [String] The attribute name
+      # @param values [Array] The values
+      #
       def set(name, values)
         attributes[canonize_name(name)] = values
       end
       alias_method :[]=, :set
 
-      # Add new attribute or new value(s) to an existing attribute
+      # @param name [String] The attribute name
+      # @param values [Array] The values
+      #
       def add(name, values = [])
         attributes[canonize_name(name)] ||= []
         attributes[canonize_name(name)] += Array(values)
       end
 
       # Make comparable to another Attributes collection based on attributes
+      # @param other [Attributes] An Attributes object to compare with
+      # @return [Boolean] True if are contains the same attributes and values
+      #
       def ==(other)
         if other.is_a?(Attributes)
           all == other.all
@@ -97,13 +116,13 @@ module OneLogin
       protected
 
       # stringifies all names so both 'email' and :email return the same result
+      # @param name [String] The attribute name
+      # @return [String] stringified name
+      #
       def canonize_name(name)
         name.to_s
       end
 
-      def attributes
-        @attributes
-      end
     end
   end
 end

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

@@ -4,17 +4,30 @@ require "rexml/document"
 require "onelogin/ruby-saml/logging"
 require "onelogin/ruby-saml/saml_message"
 
+# Only supports SAML 2.0
 module OneLogin
   module RubySaml
   include REXML
+
+    # SAML2 Authentication. AuthNRequest (SSO SP initiated, Builder)
+    #
     class Authrequest < SamlMessage
 
-      attr_reader :uuid # Can be obtained if neccessary
+      # AuthNRequest ID
+      attr_reader :uuid
 
+      # Initializes the AuthNRequest. An Authrequest Object that is an extension of the SamlMessage class.
+      # Asigns an ID, a random uuid.
+      #
       def initialize
         @uuid = "_" + UUID.new.generate
       end
 
+      # Creates the AuthNRequest 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] AuthNRequest string that includes the SAMLRequest
+      #
       def create(settings, params = {})
         params = create_params(settings, params)
         params_prefix = (settings.idp_sso_target_url =~ /\?/) ? '&' : '?'
@@ -26,6 +39,11 @@ module OneLogin
         @login_url = settings.idp_sso_target_url + request_params
       end
 
+      # Creates the Get parameters for the 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
@@ -46,11 +64,14 @@ module OneLogin
 
         if settings.security[:authn_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
 
@@ -61,6 +82,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_authentication_xml_doc(settings)
         time = Time.now.utc.strftime("%Y-%m-%dT%H:%M:%SZ")
 
@@ -118,8 +143,8 @@ module OneLogin
 
         # embed signature
         if settings.security[:authn_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