merge v1.0.0

Author: dnroot

.gitignore

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

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

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,28 +114,37 @@ 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
   end
 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
 

changelog.md

@@ -1,4 +1,21 @@
 # RubySaml Changelog
+
+### 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
 * [#218](https://github.com/onelogin/ruby-saml/pull/218) Update README.md
@@ -15,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

lib/onelogin/ruby-saml.rb

@@ -9,6 +9,7 @@
 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'

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 @@ def configure(&block)
         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