carpool 0.2.1 → 0.2.2

data/README.md

@@ -0,0 +1,118 @@
+# carpool
+
+Carpool is a single-sign-on (sso) solution for rack based applications. It is designed to allow you to designate one application as a "driver" which powers authentication, and sends session information to "passengers". It has been tested with both Rails 2.3 and Rails 3 (as rack middleware).
+
+Carpool handles securely transferring user information across domains (using AES encryption), as well as redirection so that already-signed-in users will have a seamless experience. It is designed to be as unobtrusive as possible, allowing you to handle the actual login and session maintenance in any manner you would like.
+
+# Installation
+
+Install the gem
+	gem install carpool
+	
+# Configuration
+
+Configure the application you wish to designate as your driver. In Rails based applications, add Carpool::Driver to your middleware stack. The configuration takes three options.
+
+- One or more passengers. This takes two options, first, the domain name of the passenger application (the referrer), second a 'secret' designated to the passenger application. This secret can be anything, but must match in both the driver and passenger sites.
+- unauthorized_uri. If there isn't an existing session within the driver application, redirect to this location to handle logins etc
+- revoke_uri. This url is used to "logout" passengers from the driver
+
+In environment.rb:
+
+	Rails.configuration.middleware.use Carpool::Driver do |config|
+	  config.passenger 'apasengerdomain.com', :secret => 'secret_key'
+	  config.unauthorized_uri = 'urlforunauthoried.passengers'
+	  config.revoke_uri       = 'signout'
+	end
+
+Then configure the application that you would like to function as your passenger, adding Carpool::Passenger to your middleware stack. This takes two options.
+
+- driver_uri. This is the url/location of the 'driver' site. (ie: http://yourdriver.com)
+- secret. This is a shared secret between both the driver and the passenger to verify the passenger has permission to authenticate itself here.
+
+In environment.rb:
+
+	Rails.configuration.middleware.use Carpool::Passenger do |config|
+	  config.driver_uri = 'http://yourdriver.com'
+	  config.secret = "secret_key"
+	end
+
+# Authenticating
+
+### Driver Application
+
+Authentication in your driver application can be handled however you would like. When sessions are created, simply check to see if authentication was requested by a passenger website, or the actual application itself. To check this, use Carpool.auth_attempt?  When authentication is initiated by a passenger, Carpool creates a 'seatbelt' object which represents the session details to be passed back after successful login/session.
+
+	# Create user session (authlogic format used as an example)	
+	user_session.save
+	
+	if Carpool.auth_attempt?
+	
+	  # This login request was generated from a passenger.
+	  # current_user represents our now logged in user.
+	  # env is the rack environment.
+	
+	  # Fasten yer seatbelt to be taken back to the requesting app.
+	  seatbelt = Carpool::SeatBelt.new(env).fasten!(current_user)
+	  redirect_to seatbelt	# Redirect back to the passenger site (to /sso/authorize)
+	
+	else
+	  # Handle local logins here
+	end
+
+Seatbelt.fasten! generates a url representing a url back to the Passenger application, including a session payload that Carpool::Passenger uses to generate a session within itself.	
+
+### Passenger Application
+
+Passengers only need to be able to handle two aspects of the process, redirecting `/login` and handing the resulting seatbelt from your Driver application.
+
+**Redirecting login:** To use the Driver application for logins, redirect users to Carpool.driver_uri
+
+**Processing the Seatbelt:** On successful login the Drier will redirect the user back to `/sso/authorize` within the passenger application. On redirect, the header `X-CARPOOL-PAYLOAD`, and the parameters `seatbelt` and `driver` will be set. To be sure authentication has taken place, check for the `X-CARPOOL-PAYLOAD` header, then process the seatbelt.
+
+	# Remove our seatbelt because we've arrived! (ok really just process the result)
+	seatbelt = Carpool::SeatBelt.new(request.env).remove!
+	
+	# User will contain any parameters encrypted via the Driver (see above).
+	user = seatbelt.user     
+	
+	# Handle your session however using the user hash.
+	# Call the redirect_uri from our seatbelt to return users back to their original requesting url.
+	redirect_to seatbelt.redirect_uri
+
+**Rails users:** make sure you setup a route to respond to `/sso/authorize`.
+
+## User Data
+
+To make Carpool actually useful in your passenger applications, you would likely need to pass data from the Driver to the Passenger. The `Carpool::Seatbelt.fasten!` method takes one parameter, which can be any Ruby class that responds to the method `encrypted_credentials`. This method should return a hash containing any information you would like to access in your Passengers. This hash is then encrypted via AES using 
+Nate Wiger's [FastAES](https://github.com/nateware/fast-aes) gem. Although this data is encrypted, it is not recommended that the user data hash include sensitive data such as credit card numbers, social security numbers etc. 
+
+	class User
+	  def encrypted_credentials
+	    {
+		 :first_name => 'My', 
+	     :last_name => 'Name', 
+	     :id => id_for_database_use 
+ 		}
+	  end
+	end
+
+### Caveats
+
+To properly ensure the proper domains are being accessed/used, Carpool relies on the `SERVER_NAME` http header. Make sure that this header is properly set via your nginx/apache configuration. If using Passenger standalone, it seems like this variable will be `_` so make sure that you properly handle that.
+
+If you choose to, you can set `SERVER_NAME` to `HTTP_HOST`, but note that the `HTTP_HOST` variable can be spoofed by end users.
+
+### Note on Patches/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.
+
+### Copyright
+
+Copyright (c) 2010 Brent Kirby / Kurb Media LLC. See LICENSE for details.

data/VERSION

@@ -1 +1 @@
-0.2.1
+0.2.2

data/carpool.gemspec

@@ -5,30 +5,33 @@
 
 Gem::Specification.new do |s|
   s.name = %q{carpool}
-  s.version = "0.2.1"
+  s.version = "0.2.2"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Brent Kirby"]
-  s.date = %q{2010-09-12}
+  s.date = %q{2010-11-14}
   s.description = %q{Carpool is a single sign on solution for Rack-based applications allowing you to persist sessions across domains.}
   s.email = %q{dev@kurbmedia.com}
   s.extra_rdoc_files = [
     "LICENSE",
-     "README.rdoc"
+     "README.md"
   ]
   s.files = [
     ".document",
      ".gitignore",
      "LICENSE",
-     "README.rdoc",
+     "README.md",
      "Rakefile",
      "VERSION",
      "carpool.gemspec",
      "init.rb",
      "lib/carpool.rb",
      "lib/carpool/driver.rb",
-     "lib/carpool/mixins.rb",
+     "lib/carpool/mixins/action_controller.rb",
+     "lib/carpool/mixins/action_view.rb",
+     "lib/carpool/mixins/core.rb",
      "lib/carpool/passenger.rb",
+     "lib/carpool/rails/railtie.rb",
      "lib/carpool/seatbelt.rb",
      "test/helper.rb",
      "test/test_carpool.rb"

data/lib/carpool.rb

@@ -1,9 +1,11 @@
-require 'carpool/mixins'
+require 'carpool/mixins/core'
 require 'carpool/driver'
 require 'carpool/passenger'
 require 'carpool/seatbelt'
 require 'base64'
 
+require 'carpool/rails/railtie' if defined?(Rails) && defined?(Rails::Railtie)
+
 module Carpool
   
   class << self
@@ -30,6 +32,15 @@ module Carpool
       @acts_as == type.to_sym
     end
     
+    def redirect_request(loc, message = "Redirecting")
+      [302,
+        { 'Content-Type'   => 'text/plain', 
+          'Location'       => loc,
+          'Cache-Control'  => 'private, no-cache, max-age=0, must-revalidate',
+          'Content-Length' => "#{message.to_s.length}"
+        }, message]
+    end
+    
   end
   
   def self.generate_site_key(url)

data/lib/carpool/driver.rb

@@ -38,7 +38,12 @@ module Carpool
     def call(env)
       
       @env = env
-      cookies[:scope]    = "driver"
+      carpool_cookies['scope'] = "driver"
+      
+      # TODO: See if this is even necessary? Basically make sure auth_attempt
+      # is set to true if current_passenger is set. This value shouldn't be set if we've already
+      # processed a passenger.
+      Carpool.auth_attempt = true if carpool_cookies['current_passenger']
 
       # Unless we are trying to authenticate a passenger, just continue through the stack.
       return @app.call(env) unless valid_request? && valid_referrer? 
@@ -49,15 +54,17 @@ module Carpool
       # Unless this domain is listed as a potential passenger, issue a 500.
       current_passenger = Carpool::Driver.passengers.reject{ |p| !p.keys.first.downcase.include?(referrer.host) }
       if current_passenger.nil? or current_passenger.empty?
-        return [500, {}, 'Unauthorized request.']
+        return [500, {'Content-Type'=>'text/plain'}, 'Unauthorized request.']
       end
       
+      # We are logging out this user, clear out our cookies and reset the session, then pass the request to the normal revoke path.
       if is_revoking?
-        response = [302, {'Location' => Carpool::Driver.revoke_uri}, 'Redirecting logged out session...']
-        return response
+        destroy_session!
+        set_new_path(Carpool::Driver.revoke_uri)
+        return @app.call(env)
       end
       
-      cookies[:current_passenger] = current_passenger.first[referrer.host.to_s]
+      carpool_cookies['current_passenger'] = current_passenger.first[referrer.host.to_s]
       
       # Attempt to find an existing driver session.
       # If one is found, redirect back to the passenger site and include our seatbelt
@@ -66,34 +73,26 @@ module Carpool
       #   2) The session payload. This is an AES encrypted hash of whatever attributes you've made available. The encrypted hash is
       #      keyed with the site_key and secret of the referring site for extra security.
       #
-      unless cookies[:passenger_token]
-        
-        puts "Carpool::Driver: Redirecting to authentication path.."
-        Carpool.auth_attempt = true
-        cookies[:redirect_to] = referrer        
-        response = [302, {'Location' => Carpool::Driver.unauthorized_uri}, 'Redirecting unauthorized user...']        
-        
-      else
-        
-        puts "Carpool::Driver: Redirecting to passenger site.."
-        cookies[:redirect_to] = referrer
-        seatbelt = SeatBelt.new(env).create_payload!
-
-        response = [302, {'Location' => seatbelt}, 'Approved!']
+      if carpool_passenger_token
+        seatbelt = SeatBelt.new(env)
+        seatbelt.set_referrer(referrer)
+        seatbelt = seatbelt.create_payload!
         Carpool.auth_attempt  = false
-        cookies[:redirect_to] = false
-        cookies[:current_passenger] = nil
-                
+        cleanup_session!
+        return Carpool.redirect_request(seatbelt, 'Approved!')
       end
       
-      response
+      Carpool.auth_attempt = true
+      carpool_cookies['redirect_to'] = referrer
+      
+      set_new_path(Carpool::Driver.unauthorized_uri)
+      return @app.call(env)
       
     end
     
     private
     
     def valid_referrer?
-      puts "Referrer?: #{@env['HTTP_REFERER']}"
       !(@env['HTTP_REFERER'].nil? or @env['HTTP_REFERER'].blank?)
     end
     

data/lib/carpool/mixins/action_controller.rb

@@ -0,0 +1,51 @@
+module Carpool
+  module Mixins
+    module ActionController
+      
+      def carpool_login_url
+        Carpool.driver_uri
+      end
+      
+      def carpool_logout_url
+        Carpool.revoke_uri
+      end
+      
+      def carpool_can_authenticate?
+        !([carpool_rack_env['X-CARPOOL-PAYLOAD']].flatten.empty?)
+      end
+      
+      def carpool_user
+        @_carpool_user
+      end
+      
+      def fasten_seatbelt(user)
+        Carpool::SeatBelt.new(carpool_rack_env).fasten!(user)
+      end
+      
+      def fasten_seatbelt!(user)
+        redirect_to fasten_seatbelt(user)
+      end
+      
+      def remove_seatbelt!
+        seatbelt = Carpool::SeatBelt.new(carpool_rack_env).remove!
+        @_carpool_user = seatbelt.user
+        seatbelt
+      end
+      
+      def revoke_authentication!
+        if Carpool.acts_as?(:driver)
+          carpool_rack_env.delete('carpool.cookies')
+        else
+          redirect_to carpool_logout_url
+        end
+      end
+      
+      private
+      
+      def carpool_rack_env
+        (defined?(env) ? env : request.env)
+      end
+      
+    end
+  end
+end

data/lib/carpool/mixins/action_view.rb

@@ -0,0 +1,15 @@
+module Carpool
+  module Mixins
+    module ActionView
+      
+      def carpool_login_url
+        Carpool.driver_uri
+      end
+      
+      def carpool_logout_url
+        Carpool.revoke_uri
+      end
+      
+    end
+  end
+end

data/lib/carpool/mixins/core.rb

@@ -0,0 +1,47 @@
+module Carpool
+  module Mixins
+    
+    module Core
+      def self.included(base)
+        base.send :include, InstanceMethods
+      end
+      
+      module InstanceMethods
+        
+        def carpool_cookies
+          session['carpool.cookies'] ||= {}
+        end
+        
+        def carpool_passenger_token
+          carpool_cookies['passenger_token']
+        end
+        
+        def carpool_passenger_token=(token)
+          carpool_cookies['passenger_token'] = token
+        end
+        
+        def cleanup_session!
+          ['redirect_to', 'current_passenger'].each{ |k| carpool_cookies.delete(k) }
+        end
+        
+        def destroy_session!
+          session.clear
+        end
+        
+        def request
+          @request ||= Rack::Request.new(@env)
+        end
+        
+        def session
+          @env['rack.session']
+        end
+        
+        def set_new_path(p)
+          @env['PATH_INFO'] = p
+        end
+        
+      end
+    end
+    
+  end
+end

data/lib/carpool/passenger.rb

@@ -22,16 +22,18 @@ module Carpool
     def call(env)
       @env = env
       @params = CGI.parse(env['QUERY_STRING'])
-      cookies[:scope] = "passenger"
+      
+      carpool_cookies['scope'] ||= "passenger"
       
       # If this isn't an authorize request from the driver, just ignore it.
       return @app.call(env) unless valid_request? && valid_referrer?
       
-      # If we can't find our payload, then we need to abort.      
+      # If we can't find our payload, then we need to abort.
       return [500, {}, 'Invalid seatbelt.'] if @params['seatbelt'].nil? or @params['seatbelt'].blank?
       
       # Set a custom HTTP header for our payload and send the request to the user's /sso/authorize handler.
       env['X-CARPOOL-PAYLOAD'] = @params['seatbelt']
+      
       return @app.call(env)
       
     end
@@ -39,7 +41,7 @@ module Carpool
     private
     
     def valid_request?
-      @env['PATH_INFO'] == "/sso/authorize"
+      @env['PATH_INFO'] == "/sso/authorize" || @env['PATH_INFO'] == "/sso/remote_authentication"
     end
     
     def valid_referrer?
@@ -51,11 +53,12 @@ module Carpool
       secret_match  = secret_match.update(Carpool::Passenger.secret).to_s
       referring_uri = referring_uri.to_s.gsub(/(\[|\]|\")/,'') # TODO: Figure out why ruby 1.9.2 has extra chars.
       secret_match  = secret_match.to_s
-      puts "Referring URI: #{referring_uri.class}"
-      puts "Secret: #{secret_match.class}"
-      puts "Trying to match #{referring_uri} to #{secret_match} : #{referring_uri == secret_match}"
       referring_uri == secret_match
     end
     
+    def authenticate_from_remote!
+      
+    end
+    
   end
 end

data/lib/carpool/rails/railtie.rb

@@ -0,0 +1,22 @@
+require 'carpool/mixins/action_controller'
+require 'carpool/mixins/action_view'
+
+module Carpool
+  module Rails
+    
+    class Railtie < ::Rails::Railtie
+
+      initializer :carpool do      
+        ActionController::Base.class_eval do 
+          include Carpool::Mixins::ActionController
+        end
+      end
+      
+      config.after_initialize do
+        ActionView::Base.send :include, Carpool::Mixins::ActionView
+      end
+      
+    end
+    
+  end
+end

data/lib/carpool/seatbelt.rb

@@ -22,10 +22,10 @@ module Carpool
     # on the other end.
     #
     def fasten!(user)
-      cookies[:passenger_token] = generate_token(user)
+      carpool_cookies['passenger_token'] = generate_token(user)
       Carpool.auth_attempt = false
       payload = create_payload!
-      cookies[:redirect_to] = nil
+      cleanup_session!
       payload
     end
     
@@ -34,15 +34,15 @@ module Carpool
       payload  = @env['X-CARPOOL-PAYLOAD']
       payload  = payload.flatten.first if payload.is_a?(Array) # TODO: Figure out why our header is an array?
       seatbelt = YAML.load(Base64.decode64(CGI.unescape(payload))).to_hash
-      puts "Seatbelt: #{seatbelt.inspect}"
-      user     = Base64.decode64(seatbelt[:user])
+      seatbelt = stringify_keys(seatbelt)
+      user     = Base64.decode64(seatbelt['user'])
       key      = Carpool.generate_site_key(@env['SERVER_NAME'])
       secret   = Carpool::Passenger.secret
       digest   = Digest::SHA256.new
       digest.update("#{key}--#{secret}")
       aes  = FastAES.new(digest.digest)
       data = aes.decrypt(user)
-      @redirect_uri = seatbelt[:redirect_uri].to_s
+      @redirect_uri = seatbelt['redirect_uri'].to_s
       @user         = YAML.load(data).to_hash
       self
     end
@@ -50,9 +50,9 @@ module Carpool
     # Create a redirection payload to be sent back to our passenger
     def create_payload!
       seatbelt = self.to_s
-      referrer = cookies[:redirect_to]
+      referrer = carpool_cookies['redirect_to']
       driver   = Digest::SHA256.new
-      driver   = driver.update(cookies[:current_passenger][:secret]).to_s
+      driver   = driver.update(carpool_cookies['current_passenger'][:secret]).to_s
       new_uri  = "#{referrer.scheme}://"
       new_uri << referrer.host
       new_uri << ((referrer.port != 80 && referrer.port != 443) ? ":#{referrer.port}" : "")
@@ -60,21 +60,36 @@ module Carpool
     end
     
     def to_s
-      CGI.escape(Base64.encode64({:redirect_uri => cookies[:redirect_to].to_s, :user => cookies[:passenger_token] }.to_yaml.to_s).gsub( /\s/, ''))
+      CGI.escape(Base64.encode64({ 'redirect_uri' => carpool_cookies['redirect_to'].to_s, 'user' => carpool_cookies['passenger_token'] }.to_yaml.to_s).gsub( /\s/, ''))
+    end
+    
+    def set_referrer(ref)
+      carpool_cookies['redirect_to'] = ref
     end
     
     private
     
     def generate_token(user)
-      referrer  = cookies[:redirect_to]
+      referrer  = carpool_cookies['redirect_to']
       passenger = Carpool::Driver.passengers.reject{ |p| p.keys.first.downcase != referrer.host }.first.values.first
             
       digest    = Digest::SHA256.new
       digest.update("#{passenger[:site_key]}--#{passenger[:secret]}")
       aes = FastAES.new(digest.digest)
-      Base64.encode64(aes.encrypt(user.encrypted_credentials.to_yaml.to_s)).gsub( /\s/, '')
+      Base64.encode64(aes.encrypt(gather_credentials(user).to_yaml.to_s)).gsub( /\s/, '')
       
     end
+    
+    def gather_credentials(user)
+      user.encrypted_credentials
+    end
+    
+    def stringify_keys(hash)
+      hash.inject({}) do |options, (key, value)|
+        options[key.to_s] = value
+        options
+      end
+    end
         
   end
 end

metadata

@@ -1,13 +1,12 @@
 --- !ruby/object:Gem::Specification 
 name: carpool
 version: !ruby/object:Gem::Version 
-  hash: 21
   prerelease: false
   segments: 
   - 0
   - 2
-  - 1
-  version: 0.2.1
+  - 2
+  version: 0.2.2
 platform: ruby
 authors: 
 - Brent Kirby
@@ -15,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-09-12 00:00:00 -04:00
+date: 2010-11-14 00:00:00 -05:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -26,7 +25,6 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        hash: 3
         segments: 
         - 0
         version: "0"
@@ -40,7 +38,6 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        hash: 3
         segments: 
         - 0
         version: "0"
@@ -54,20 +51,23 @@ extensions: []
 
 extra_rdoc_files: 
 - LICENSE
-- README.rdoc
+- README.md
 files: 
 - .document
 - .gitignore
 - LICENSE
-- README.rdoc
+- README.md
 - Rakefile
 - VERSION
 - carpool.gemspec
 - init.rb
 - lib/carpool.rb
 - lib/carpool/driver.rb
-- lib/carpool/mixins.rb
+- lib/carpool/mixins/action_controller.rb
+- lib/carpool/mixins/action_view.rb
+- lib/carpool/mixins/core.rb
 - lib/carpool/passenger.rb
+- lib/carpool/rails/railtie.rb
 - lib/carpool/seatbelt.rb
 - test/helper.rb
 - test/test_carpool.rb
@@ -85,7 +85,6 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: 3
       segments: 
       - 0
       version: "0"
@@ -94,7 +93,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: 3
       segments: 
       - 0
       version: "0"

data/README.rdoc

@@ -1,17 +0,0 @@
-= carpool
-
-Description goes here.
-
-== Note on Patches/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.
-
-== Copyright
-
-Copyright (c) 2010 Brent Kirby. See LICENSE for details.

data/lib/carpool/mixins.rb

@@ -1,21 +0,0 @@
-module Carpool
-  module Mixins
-    
-    module Core
-      def self.included(base)
-        base.send :include, InstanceMethods
-      end
-      
-      module InstanceMethods
-        def session
-          @env['rack.session']
-        end
-
-        def cookies
-          session['carpool.cookies'] ||= {}
-        end
-      end
-    end
-    
-  end
-end