has_global_session 0.8.0 → 0.8.1

data/{README → README.rdoc}

@@ -5,104 +5,121 @@ session state in a cryptographically secure way, facilitating single sign-on
 and enabling easier development of large-scale distributed applications that
 make use of architectural strategies such as sharding or separation of concerns.
 
-This plugin does not provide a complete solution for authentication. In
-particular, it does *not* provide any of the following:
+In other words: it lets semi-related Web apps share selected bits of session
+state.
+
+This plugin does not provide a complete solution for identity management. In
+particular, it does not provide any of the following:
 
 * <b>federation</b> -- aka cross-domain single sign-on -- use OpenID for that.
 
-* <b>authentication</b> -- the application's controllers must authenticate the user.
+* <b>authentication</b> -- the application must authenticate the user.
+
+* <b>authorization</b> -- the application is responsible for using the contents
+  of the global session to make authorization decisions.
 
 * <b>secrecy</b> -- global session attributes can be signed but never encrypted;
-  protect against third-party snooping using SSL, and if you don't want your
-  users to see their session state, put it in a database.
+  protect against third-party snooping using SSL. Group secrecy is expensive;
+  if you don't want your users to see their session state, put it in a database,
+  or in an encrypted local session cookie.
 
 * <b>replication</b> -- the authentication authorities must have some way to
-  share information about the database of users, their passwords, etc.
+  share information about the database of users in order to authenticate
+  them and place identifying information into the global session.
 
 * <b>single sign-out</b> -- the authorities must have some way to broadcast a
   notification when sessions are invalidated; they can override the default
   Directory implementation to do realtime revocation checking.
 
-== Global Session Contents
+= Example
+
+1) Create a basic config file and edit it to suit your needs:
+    $ script/generate global_session_config mycoolapp.com
+
+2) Create an authentication authority:
+    $ script/generate global_session_authority mycoolapp
+
+3) Declare that some or all of your controllers will use the global session:
+    class ApplicationController < ActionController::Base
+      has_global_session
+    end
+
+4) Make use of the global session hash in your controllers:
+    global_session['user'] = @user.id
+    ...
+    @current_user = User.find(global_session['user'])
+
+5) For easier programming, enable seamless integration with the local session:
+   (in global_session.yml)
+   common:
+     integrated: true
+   
+   (in your controllers)
+   session['user'] = @user.id #goes to the global session
+   session['local_thingie'] = @thingie.id #goes to the local session
+
+= Global Session Contents
 
 Global session state is stored as a cookie in the user's browser. The cookie
 is a Zlib-compressed JSON dictionary containing the following stuff:
-* session metadata (UUID, created-at, expires-at, certifying-authority)
+* session metadata (UUID, created-at, expires-at, signing-authority)
 * signed session attributes (e.g. the authenticated user ID)
 * insecure session attributes (e.g. the last-visited URL)
 * a cryptographic signature of the metadata and signed attributes
 
 The global session is unserialized and its signature is verified whenever
-a controller asks for the global session. The cookie's value is updated
-whenever its attributes change. As an optimization, the signature is only
+a controller asks for one of its attributes. The cookie's value is updated
+whenever attributes change. As an optimization, the signature is only
 recomputed when the metadata or signed attributes have changed; insecure
 attributes can change "for free."
 
 Because the security properties of attributes can vary, HasGlobalSession
 requires all _possible_ attributes to be declared up-front in the config
 file. The 'attributes' section of the config file defines the _schema_
-for the global session: which attributes can be used, and which must be
-cryptographically signed in order to be used.
+for the global session: which attributes can be used, which can be trusted
+to make authorization decisions (because they are signed), and are insecure
+and therefore act only as "hints" about the session.
 
 Since the session is serialized as JSON, only a limited range of object
 types can be stored in it: strings, numbers, lists, hashes and other Ruby
 primitives. Ruby booleans (true/false) do not translate well into JSON
 and should be avoided.
 
-= Example
-
-1) Create a basic config file and edit it to suit your needs:
-      $ script/generate global_session_config mycoolapp.com
-
-2) Create an authentication authority:
-      $ script/generate global_session_authority mycoolapp
-
-3) Declare that some or all of your application's controllers will have access
-   to the global session:
-      class ApplicationController < ActionController::Base
-        has_global_session
-      end
-
-4) Make use of the global session hash in your controllers:
-      global_session['user'] = @user.id
-      ...
-      @current_user = User.find(global_session['user'])
-
 = Detailed Information
 
 == Global Session Domain
 
 We refer to collection of _all_ Web application instances capable of using the
 global session as the "domain." The global session domain may consist of any
-number of distinct servers, possibly hidden behind load balancers or proxies.
-The servers within the domain may all be running the same Rails application,
+number of distinct nodes, possibly hidden behind load balancers or proxies.
+The nodes within the domain may all be running the same Rails application,
 or they may be running different codebases that represent different parts of
 a distributed application. (They may also be using app frameworks other than
 Rails.)
 
-The only constraint imposed by HasGlobalSession is that all servers within the
+The only constraint imposed by HasGlobalSession is that all nodes within the
 domain must have end-user-facing URLs within the same second-level DNS domain.
 This is due to limitations imposed by the HTTP cookie mechanism: for privacy
-reasons, cookies will only be sent to servers within the same domain as the
-server that first created them.
+reasons, cookies will only be sent to nodes within the same domain as the
+node that first created them.
 
 For example, in my HasGlobalSession configuration file I might specify that my
-cookie's domain is "example.com". My app servers at app1.example.com and
+cookie's domain is "example.com". My app nodes at app1.example.com and
 app2.example.com would be part of the global session domain, but my business
-partner's application at www.partner.com could not participate.
+partner's application at app3.partner.com could not participate.
 
 == Authorities and Relying Parties
 
-A Web application that can create or update the global session is said to
-be an "authority" (because it's trusted by other parties to make assertions
-about global session state). An application that can read the global session
-is said to be a "relying party." In practice, every application is a relying
-party but not all of them need to be authorities.
+A node that can create or update the global session is said to be an "authority"
+(because it's trusted by other parties to make assertions about global session
+state). An application that can read the global session is said to be a "relying
+party." In practice, every application is a relying party, but not all of them
+need to be authorities.
 
 There is an RSA key pair associated with each authority. The authority's
 public key is distribued to all relying parties, but the private key must
 remain a secret to that authority (which may consist of many individual
-servers).
+nodes).
 
 This system allows for significant flexibility when configuring a distributed
 app's global session. There must be at least one authority, but for many apps
@@ -117,7 +134,7 @@ Here are some reasons you might consider dividing your systems into different
 authorities:
 * beta/staging system vs. production system
 * system hosted by a third party vs. system hosted internally
-* e-commerce server vs. storefront server
+* e-commerce node vs. storefront node
 
 == The Directory
 
@@ -131,21 +148,41 @@ signing session attributes.
 
 The Directory implementation included with HasGlobalSession uses the filesystem
 as the backing store for its key pairs. Its #initialize method accepts a
-filesystem path that will be searched for *.pub and *.key files containing PEM-
-encoded public and private keys (the same format used by OpenSSH).
+filesystem path that will be searched for files containing PEM-encoded public
+and private keys (the same format used by OpenSSH). This simple Directory
+implementation relies on the following conventions:
+* Public keys have a *.pub extension.
+* Private keys have a *.key extension.
+* If a node is an authority, then one (and *only* one) *.key file should exist.
+* The local node's authority name is inferred from the name of the private key
+  file.
 
 When used with a Rails app, HasGlobalSession expects to find its keystore in
 config/authorities. You can use the global_session generator to create new key
-pairs. Remember never to check a *.key file into a public repository!! (In
-contrast, *.pub files can be distributed freely.) 
+pairs. Remember never to check a *.key file into a public repository!! (*.pub
+files can be checked into source control and distributed freely.) 
 
 If you wish all of the systems to stop trusting an authority, simply delete
-its public key from config/authorities.
+its public key from config/authorities and re-deploy your app.
+
+=== Implementing Your Own Directory Provider
+
+To replace or enhance the built-in Directory, simply create a new class that
+extends Directory and put the class somewhere in your app (the lib directory
+is a good choice). In the HasGlobalSession configuration file, specify the
+class name of the directory under the 'common' section, like so:
+  common:
+    integrated: true
+    directory: MyCoolDirectory
 
 = To-Do
 
 * Configurable session expiry
+
 * Option to auto-renew session
-* Option for non-sticky global session (cookie expires at close of browser session, not at global session expiration!)
+
+* Option for non-sticky global session
+  (e.g. cookie expires at close of browser session, not at global session
+  expiration!)
 
 Copyright (c) 2010 Tony Spataro <code@tracker.xeger.net>, released under the MIT license

data/has_global_session.gemspec

@@ -7,7 +7,7 @@ spec = Gem::Specification.new do |s|
   s.required_ruby_version = Gem::Requirement.new(">= 1.8.7")
 
   s.name    = 'has_global_session'
-  s.version = '0.8.0'
+  s.version = '0.8.1'
   s.date    = '2010-06-01'
 
   s.authors = ['Tony Spataro']
@@ -17,10 +17,10 @@ spec = Gem::Specification.new do |s|
   s.summary = %q{Secure single-domain session sharing plugin for Rails.}
   s.description = %q{This Rails plugin allows several Rails web apps that share the same back-end user database to share session state in a cryptographically secure way, facilitating single sign-on in a distributed web app. It only provides session sharing and does not concern itself with authentication or replication of the user database.}
 
-  s.add_runtime_dependency('uuidtools', [">= 2.1.1"])
+  s.add_runtime_dependency('uuidtools', [">= 1.0.7"])
 
   basedir = File.dirname(__FILE__)
-  candidates = ['has_global_session.gemspec', 'init.rb', 'MIT-LICENSE', 'README'] +
+  candidates = ['has_global_session.gemspec', 'init.rb', 'MIT-LICENSE', 'README.rdoc'] +
             Dir['lib/**/*'] +
             Dir['rails/**/*']
   s.files = candidates.sort

data/lib/generators/global_session_authority/global_session_authority_generator.rb

@@ -0,0 +1,32 @@
+class GlobalSessionAuthorityGenerator < Rails::Generator::Base
+  def initialize(runtime_args, runtime_options = {})
+    super
+
+    @app_name  = File.basename(RAILS_ROOT)
+    @auth_name = args.shift
+    raise ArgumentError, "Must specify name for global session authority, e.g. 'mycoolapp'" unless @auth_name
+  end
+
+  def manifest
+    record do |m|
+      new_key     = OpenSSL::PKey::RSA.generate( 1024 )
+      new_public  = new_key.public_key.to_pem
+      new_private = new_key.to_pem
+
+      dest_dir = File.join(RAILS_ROOT, 'config', 'authorities')
+      FileUtils.mkdir_p(dest_dir)
+
+      File.open(File.join(dest_dir, @auth_name + ".pub"), 'w') do |f|
+        f.puts new_public
+      end
+
+      File.open(File.join(dest_dir, @auth_name + ".key"), 'w') do |f|
+        f.puts new_private
+      end
+
+      puts "***"
+      puts "*** Don't forget to delete config/authorities/#{@auth_name}.key"
+      puts "***"
+    end
+  end
+end

data/lib/generators/global_session_config/global_session_config_generator.rb

@@ -10,7 +10,7 @@ class GlobalSessionConfigGenerator < Rails::Generator::Base
   def manifest
     record do |m|
       
-      m.template 'templates/global_session.yml.erb',
+      m.template 'global_session.yml.erb',
                  'config/global_session.yml',
                  :assigns=>{:app_name=>@app_name,
                             :app_domain=>@app_domain}

data/lib/generators/global_session_config/templates/global_session.yml.erb

@@ -1,6 +1,5 @@
 # Common settings of the global session (that apply to all Rails environments)
-# are listed here. These may be overidden in the environment-specific section,
-# but it seldom makes sense to do so.
+# are listed here. These may be overidden in the environment-specific section.
 common:
   attributes:
     # Signed attributes of the global session
@@ -14,17 +13,30 @@ common:
   # global attributes always taking precedence over local attributes.
   integrated: true
 
-development:
+# Test/spec runs
+test:
+  timeout: 900
   cookie:
-    name: __<%= app_name %>_development
+    name: __<%= app_name %>_test
     domain: localhost
+  trust:
+  - test
 
-test:
+# Development mode
+development:
+  timeout: 3600
   cookie:
-    name: __<%= app_name %>_test
+    name: __<%= app_name %>_development
     domain: localhost
+  trust:
+  - development
+  - production
 
+# Production mode
 production:
+  timeout: 3600
   cookie:
     name: __<%= app_name %>_global
     domain: <%= app_domain %>
+  trust:
+  - production

data/lib/has_global_session/configuration.rb

@@ -4,23 +4,13 @@ module HasGlobalSession
     mattr_accessor :environment
     
     def self.[](key)
-      unless @config
-        raise MissingConfiguration, "config_file is nil; cannot read configuration" unless config_file
-        raise MissingConfiguration, "environment is nil; must be specified" unless environment
-        @config = YAML.load(File.read(config_file))
-        validate
-      end
-      if @config.has_key?(environment) && @config[environment].has_key?(key)
-        return @config[environment][key]
-      else
-        @config['common'][key]
-      end
+      get(key, true)
     end
 
     def self.validate
       ['attributes/signed', 'integrated', 'cookie/name', 'cookie/domain'].each do |path|
         elements = path.split '/'
-        object = self[elements.shift]
+        object = get(elements.shift, false)
         elements.each do |element|
           object = object[element]
           if object.nil?
@@ -30,5 +20,23 @@ module HasGlobalSession
         end
       end
     end
+
+    private
+    def self.get(key, validated)
+      unless @config
+        raise MissingConfiguration, "config_file is nil; cannot read configuration" unless config_file
+        raise MissingConfiguration, "environment is nil; must be specified" unless environment
+        @config = YAML.load(File.read(config_file))
+        raise TypeError, "#{config_file} must contain a Hash!" unless Hash === @config
+        validate if validated
+      end
+      if @config.has_key?(environment) &&
+         @config[environment].respond_to?(:has_key?) &&
+         @config[environment].has_key?(key)
+        return @config[environment][key]
+      else
+        @config['common'][key]
+      end
+    end
   end  
 end

data/lib/has_global_session/global_session.rb

@@ -36,6 +36,12 @@ module HasGlobalSession
           raise SecurityError, "Signature mismatch on global session cookie; tampering suspected"
         end
 
+        unless Configuration['trust'].blank? ||
+               @authority = @directory.my_authority_name ||
+               Configuration['trust'].include?(@authority)
+          raise SecurityError, "Global sessions created by #{@authority} are not trusted"
+        end
+
         if expired? || @directory.invalidated_session?(@id)
           raise ExpiredSession, "Global session cookie has expired"
         end
@@ -43,25 +49,25 @@ module HasGlobalSession
       else
         @signed          = {}
         @insecure        = {}
-        @id              = UUIDTools::UUID.timestamp_create.to_s
+        @id              = UUID.timestamp_create.to_s
         @created_at      = Time.now.utc
-        @expires_at      = 2.hours.from_now.utc #TODO configurable
         @authority       = @directory.my_authority_name
-        @dirty_secure    = true
+        renew!
       end
     end
 
-    def supports_key?(key)
-      @schema_signed.include?(key) || @schema_insecure.include?(key)
-    end
-
     def expired?
       (@expires_at <= Time.now)
     end
 
     def expire!
       @expires_at = Time.at(0)
-      @dirty_secure = true
+      @dirty = true
+    end
+
+    def renew!
+      @expires_at = Configuration['timeout'].to_i.minutes.from_now.utc || 1.hours.from_now.utc        
+      @dirty = true
     end
 
     def to_s
@@ -69,7 +75,7 @@ module HasGlobalSession
               'tc'=>@created_at.to_i, 'te'=>@expires_at.to_i,
               'ds'=>@signed, 'dx'=>@insecure}
 
-      if @signature && !@dirty_secure
+      if @signature && !@dirty
         #use cached signature unless we've changed secure state
         authority = @authority
         signature = @signature
@@ -82,23 +88,34 @@ module HasGlobalSession
 
       hash['s'] = signature
       hash['a'] = authority
-      json = ActiveSupport::JSON.encode(hash)
+      json = hash.to_json #ActiveSupport::JSON.encode(hash) -- why does this expect Data sometimes?!
       zbin = Zlib::Deflate.deflate(json, Zlib::BEST_COMPRESSION)
       return Base64.encode64(zbin)
     end
 
+    def supports_key?(key)
+      @schema_signed.include?(key) || @schema_insecure.include?(key)
+    end
+
     def [](key)
       @signed[key] || @insecure[key]
     end
 
     def []=(key, value)
+      case value
+        when String, Numeric, Array
+          #no-op
+        else
+          raise TypeError, "Cannot store values of type #{value.class.name} reliably"
+      end
+
       if @schema_signed.include?(key)
         unless @directory.my_private_key && @directory.my_authority_name
           raise StandardError, 'Cannot change secure session attributes; we are not an authority'
         end
 
         @signed[key]  = value
-        @dirty_secure = true
+        @dirty = true
       elsif @schema_insecure.include?(key)
         @insecure[key] = value
       else
@@ -109,7 +126,7 @@ module HasGlobalSession
     def has_key?(key)
       @signed.has_key(key) || @insecure.has_key?(key)
     end
-    
+
     def keys
       @signed.keys + @insecure.keys
     end

data/lib/has_global_session/integrated_session.rb

@@ -6,6 +6,7 @@ module HasGlobalSession
     end
 
     def [](key)
+      key = key.to_s
       if @global_session.supports_key?(key)
         @global_session[key]
       else
@@ -14,6 +15,7 @@ module HasGlobalSession
     end
 
     def []=(key, value)
+      key = key.to_s
       if @global_session.supports_key?(key)
         @global_session[key] = value
       else
@@ -22,6 +24,7 @@ module HasGlobalSession
     end
 
     def has_key?(key)
+      key = key.to_s
       @global_session.has_key(key) || @local_session.has_key?(key)
     end
 

data/rails/action_controller_instance_methods.rb

@@ -4,8 +4,14 @@ module HasGlobalSession
       return @global_session if @global_session
 
       begin
+        if (klass = Configuration['directory'])
+          klass = klass.constantize
+        else
+          klass = Directory
+        end
+
+        directory = klass.new(File.join(RAILS_ROOT, 'config', 'authorities'))
         cookie = cookies[Configuration['cookie']['name']]
-        directory = Directory.new(File.join(RAILS_ROOT, 'config', 'authorities'))
 
         begin
           #unserialize the global session from the cookie, or
@@ -44,5 +50,36 @@ module HasGlobalSession
         cookies[Configuration['cookie']['name']] = options
       end
     end
+
+    def log_processing
+      if logger && logger.info?
+        log_processing_for_request_id
+        log_processing_for_parameters
+      end
+    end
+
+    def log_processing_for_request_id()
+      if global_session && global_session.id
+        session_id = global_session.id + " (#{session[:session_id]})"
+      elsif session[:session_id]
+        session_id = session[:session_id]
+      elsif request.session_options[:id]
+        session_id = request.session_options[:id]
+      end
+
+      request_id = "\n\nProcessing #{self.class.name}\##{action_name} "
+      request_id << "to #{params[:format]} " if params[:format]
+      request_id << "(for #{request_origin.split[0]}) [#{request.method.to_s.upcase}]"
+      request_id << "\n  Session ID: #{session_id}" if session_id
+
+      logger.info(request_id)
+    end
+
+    def log_processing_for_parameters
+      parameters = respond_to?(:filter_parameters) ? filter_parameters(params) : params.dup
+      parameters = parameters.except!(:controller, :action, :format, :_method)
+
+      logger.info "  Parameters: #{parameters.inspect}" unless parameters.empty?
+    end
   end
 end

data/rails/init.rb

@@ -1,18 +1,21 @@
 basedir = File.expand_path(File.join(File.dirname(__FILE__), '..'))
 require File.join(basedir, 'lib', 'has_global_session')
 
-# Tie the Configuration module to Rails' filesystem structure
-# and operating environment.
-HasGlobalSession::Configuration.config_file =
-  File.join(RAILS_ROOT, 'config', 'global_session.yml')
-HasGlobalSession::Configuration.environment = RAILS_ENV
+config_file = File.join(RAILS_ROOT, 'config', 'global_session.yml')
 
-require File.join(basedir, 'rails', 'action_controller_instance_methods')
+if File.exist?(config_file)
+  # Tie the Configuration module to Rails' filesystem structure
+  # and operating environment.
+  HasGlobalSession::Configuration.config_file = config_file
+  HasGlobalSession::Configuration.environment = RAILS_ENV
 
-# Enable ActionController integration.
-class ActionController::Base
-  def self.has_global_session
-    include HasGlobalSession::ActionControllerInstanceMethods
-    after_filter  :global_session_update_cookie
+  require File.join(basedir, 'rails', 'action_controller_instance_methods')
+
+  # Enable ActionController integration.
+  class ActionController::Base
+    def self.has_global_session
+      include HasGlobalSession::ActionControllerInstanceMethods
+      after_filter  :global_session_update_cookie
+    end
   end
-end
+end

metadata

@@ -1,7 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: has_global_session
 version: !ruby/object:Gem::Version 
-  version: 0.8.0
+  hash: 61
+  prerelease: false
+  segments: 
+  - 0
+  - 8
+  - 1
+  version: 0.8.1
 platform: ruby
 authors: 
 - Tony Spataro
@@ -14,14 +20,20 @@ default_executable:
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: uuidtools
-  type: :runtime
-  version_requirement: 
-  version_requirements: !ruby/object:Gem::Requirement 
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        version: 2.1.1
-    version: 
+        hash: 25
+        segments: 
+        - 1
+        - 0
+        - 7
+        version: 1.0.7
+  type: :runtime
+  version_requirements: *id001
 description: This Rails plugin allows several Rails web apps that share the same back-end user database to share session state in a cryptographically secure way, facilitating single sign-on in a distributed web app. It only provides session sharing and does not concern itself with authentication or replication of the user database.
 email: code@tracker.xeger.net
 executables: []
@@ -32,9 +44,10 @@ extra_rdoc_files: []
 
 files: 
 - MIT-LICENSE
-- README
+- README.rdoc
 - has_global_session.gemspec
 - init.rb
+- lib/generators/global_session_authority/global_session_authority_generator.rb
 - lib/generators/global_session_config/USAGE
 - lib/generators/global_session_config/global_session_config_generator.rb
 - lib/generators/global_session_config/templates/global_session.yml.erb
@@ -55,21 +68,29 @@ rdoc_options: []
 require_paths: 
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      hash: 57
+      segments: 
+      - 1
+      - 8
+      - 7
       version: 1.8.7
-  version: 
 required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
       version: "0"
-  version: 
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.3.5
+rubygems_version: 1.3.7
 signing_key: 
 specification_version: 3
 summary: Secure single-domain session sharing plugin for Rails.