global_session 0.9.0

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Tony Spataro <code@tracker.xeger.net>
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,179 @@
+= Introduction
+
+HasGlobalSession enables multiple heterogeneous Web applications to share
+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.
+
+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 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. 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 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.
+
+= 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, 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 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, 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.
+
+= 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 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 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 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 nodes at app1.example.com and
+app2.example.com would be part of the global session domain, but my business
+partner's application at app3.partner.com could not participate.
+
+== Authorities and Relying Parties
+
+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
+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
+one authority (plus an arbitrary number of relying parties, which do not need
+a key pair) will be sufficient.
+
+In general, two systems should be part of the same authority if there is no
+trust boundary between them -- that is to say, trust between the two systems
+is unlimited in both directions.
+
+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 node vs. storefront node vs. admin node
+
+== The Directory
+
+The Directory is a Ruby object instantiated by HasGlobalSession in order to
+perform lookups of public and private keys. Given an authority name (as found
+in a session cookie), the Directory can find the corresponding public key.
+
+If the local system is an authority itself, #local_authority_name will
+return non-nil and #private_key will return a private key suitable for
+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 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!! (*.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 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
+
+Copyright (c) 2010 Tony Spataro <code@tracker.xeger.net>, released under the MIT license

data/global_session.gemspec

@@ -0,0 +1,37 @@
+# -*- mode: ruby; encoding: utf-8 -*-
+
+require 'rubygems'
+
+spec = Gem::Specification.new do |s|
+  s.required_rubygems_version = nil if s.respond_to? :required_rubygems_version=
+  s.required_ruby_version = Gem::Requirement.new(">= 1.8.7")
+
+  s.name    = 'global_session'
+  s.version = '0.9.0'
+  s.date    = '2010-12-07'
+
+  s.authors = ['Tony Spataro']
+  s.email   = 'code@tracker.xeger.net'
+  s.homepage= 'http://github.com/xeger/global_session'
+
+  s.summary = %q{Secure single-domain session sharing plugin for Rails.}
+  s.description = %q{This plugin for Rails allows several web apps in an authentication domain to share session state, 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', [">= 1.0.7"])
+  s.add_runtime_dependency('json', [">= 1.1.7"])
+  s.add_runtime_dependency('rack-contrib', [">= 1.0"])
+
+  s.add_development_dependency('rake', ["~> 0.8.7"])
+  s.add_development_dependency('ruby-debug', ["~> 0.10.3"])
+  s.add_development_dependency('rspec', [">= 1.3.0"])
+  s.add_development_dependency('flexmock', [">= 0.8.6"])
+  s.add_development_dependency('actionpack', [">= 2.1.2"])
+
+  basedir = File.dirname(__FILE__)
+  candidates = ['global_session.gemspec', 'init.rb', 'MIT-LICENSE', 'README.rdoc'] +
+            Dir['lib/**/*'] +
+            Dir['rails/**/*'] +
+            Dir['rails/**/*'] +
+            Dir['rails_generators/**/*']
+  s.files = candidates.sort
+end

data/init.rb

@@ -0,0 +1,4 @@
+# Stub to invoke real init.rb when GlobalSession is installed as a vendored
+# Rails plugin.
+basedir = File.dirname(__FILE__)
+require File.join(basedir, 'rails', 'init')

data/lib/global_session/configuration.rb

@@ -0,0 +1,126 @@
+module GlobalSession
+  # Central point of access for GlobalSession configuration information. This is
+  # mostly a very thin wrapper around the serialized hash written to the YAML config
+  # file.
+  #
+  # The configuration is stored as a set of nested hashes and accessed by the code
+  # using hash lookup; for example, we might ask for +Configuration['cookie']['domain']+
+  # if we wanted to know which domain the cookie should be set for.
+  #
+  # The following settings are supported:
+  # * attributes
+  #    * signed
+  #    * insecure
+  # * integrated
+  # * ephemeral
+  # * timeout
+  # * renew
+  # * authority
+  # * trust
+  # * directory
+  # * cookie
+  #     * name
+  #     * domain
+  #
+  # === Config Environments
+  # The operational environment of global_session defines which section
+  # of the configuration file it gets its settings from. When used with
+  # a web app, the environment should be set to the same environment as
+  # the web app. (If using Rails integration, this happens for you
+  # automatically.)
+  #
+  # === Environment-Specific Settings
+  # The top level of keys in the configuration hash are special; they provide different
+  # sections of settings that apply in different environments. For instance, a Rails
+  # application might have one set of settings that apply in the development environment;
+  # these would appear under +Configuration['development']+. Another set of settings would
+  # apply in the production environment and would appear under +Configuration['production']+.
+  #
+  # === Common Settings
+  # In addition to having one section for each operating environment, the configuration
+  # file can specify a 'common' section for settings that apply
+  #
+  # === Lookup Mechanism
+  # When the code asks for +Configuration['foo']+, we first check whether the current
+  # environment's config section has a value for foo. If one is found, we return that.
+  #
+  # If no environment-specific setting is found, we check the 'common' section and return
+  # the value found there.
+  #
+  # === Config File Location
+  # The name and location of the config file depend on the Web framework with which
+  # you are integrating; see GlobalSession::Rails for more information.
+  #
+  class Configuration
+    # Create a new Configuration objectt
+    #
+    # === Parameters
+    # config_File(String):: Absolute filesystem path to the configuration file
+    # environment(String):: Config file section from which to read settings
+    #
+    # === Raise
+    # MissingConfiguration:: if config file is missing or unreadable
+    # TypeError:: if config file does not contain a YAML-serialized Hash
+    def initialize(config_file, environment)
+      @config_file = config_file
+      @environment = environment
+      raise MissingConfiguration, "Missing or unreadable configuration file" unless File.readable?(@config_file)
+      @config      = YAML.load(File.read(@config_file))
+      raise TypeError, "#{config_file} must contain a Hash!" unless Hash === @config
+      validate
+    end
+
+    # Reader for configuration elements. The reader first checks
+    # the current environment's settings section for the named
+    # value; if not found, it checks the common settings section.
+    #
+    # === Parameters
+    # key(String):: Name of configuration element to retrieve
+    #
+    # === Return
+    # value(String):: the value of the configuration element
+    def [](key)
+      get(key, true)
+    end
+
+    def validate # :nodoc
+      ['attributes/signed', 'integrated', 'cookie/name',
+       'timeout'].each {|k| validate_presence_of k}
+    end
+
+    protected
+
+    # Helper method to check the presence of a key.  Used in #validate.
+    #
+    # === Parameters
+    # key(String):: key name; for nested hashes, separate keys with /
+    #
+    # === Return
+    # true always
+    def validate_presence_of(key)
+      elements = key.split '/'
+      object = get(elements.shift, false)
+      elements.each do |element|
+        object = object[element] if object
+        if object.nil?
+          msg = "#{File.basename(@config_file)} does not specify required element #{elements.map { |x| "['#{x}']"}.join('')}"
+          raise MissingConfiguration, msg
+        end
+      end
+      true
+    end
+
+    private
+
+    def get(key, validated) # :nodoc
+      if @config.has_key?(@environment) &&
+         @config[@environment].has_key?(key)
+        return @config[@environment][key]
+      else
+        @config['common'][key]
+      end
+    rescue NoMethodError
+      raise MissingConfiguration, "Configuration key '#{key}' not found"
+    end
+  end
+end

data/lib/global_session/directory.rb

@@ -0,0 +1,103 @@
+module GlobalSession
+  # The global session directory, which provides some lookup and decision services
+  # to instances of Session.
+  #
+  # The default implementation is simplistic, but should be suitable for most applications.
+  # Directory is designed to be specialized via subclassing. To override the behavior to
+  # suit your needs, simply create a subclass of Directory and add a configuration file
+  # setting to specify the class name of your implementation:  
+  #
+  #     common:
+  #       directory: MyCoolDirectory
+  #
+  #
+  # === The Authority Keystore
+  # Directory uses a filesystem directory as a backing store for RSA
+  # public keys of global session authorities. The directory should
+  # contain one or more +*.pub+ files containing OpenSSH-format public
+  # RSA keys. The name of the pub file determines the name of the
+  # authority it represents.
+  #
+  # === The Local Authority
+  # Directory will infer the name of the local authority (if any) by
+  # looking for a private-key file in the keystore. If a +*.key+ file
+  # is found, then its name is taken to be the name of the local
+  # authority and all GlobalSessions created will be signed by that
+  # authority's private key.
+  #
+  # If more than one key file is found, Directory will raise an error
+  # at initialization time.
+  #
+  class Directory
+    attr_reader :configuration, :authorities, :private_key, :local_authority_name
+
+    # Create a new Directory.
+    #
+    # === Parameters
+    # keystore_directory(String):: Absolute path to authority keystore
+    #
+    # ===Raise
+    # ConfigurationError:: if too many or too few keys are found, or if *.key/*.pub files are malformatted
+    def initialize(configuration, keystore_directory)
+      @configuration = configuration
+      certs = Dir[File.join(keystore_directory, '*.pub')]
+      keys  = Dir[File.join(keystore_directory, '*.key')]
+      raise ConfigurationError, "Excepted 0 or 1 key files, found #{keys.size}" unless [0, 1].include?(keys.size)
+
+      @authorities = {}
+      certs.each do |cert_file|
+        basename = File.basename(cert_file)
+        authority = basename[0...(basename.rindex('.'))] #chop trailing .ext
+        @authorities[authority] = OpenSSL::PKey::RSA.new(File.read(cert_file))
+        raise ConfigurationError, "Expected #{basename} to contain an RSA public key" unless @authorities[authority].public?
+      end
+
+      if (authority_name = @configuration['authority'])
+        key_file = keys.detect { |kf| kf =~ /#{authority_name}.key$/ }
+        raise ConfigurationError, "Key file #{authority_name}.key not found" unless key_file        
+        @private_key  = OpenSSL::PKey::RSA.new(File.read(key_file))
+        raise ConfigurationError, "Expected #{key_file} to contain an RSA private key" unless @private_key.private?
+        @local_authority_name = authority_name
+      end
+    end
+
+    # Determine whether this system trusts a particular authority based on
+    # the trust settings specified in Configuration.
+    #
+    # === Parameters
+    # authority(String):: The name of the authority
+    #
+    # === Return
+    # trusted(true|false):: whether the local system trusts sessions signed by the specified authority
+    def trusted_authority?(authority)
+      @configuration['trust'].include?(authority)
+    end
+
+    # Determine whether the given session UUID is valid. The default implementation only considers
+    # a session to be invalid if its expired_at timestamp is in the past. Custom implementations
+    # might want to consider other factors, such as whether the user has signed out of this node
+    # or another node (perhaps using some sort of centralized lookup or single sign-out mechanism).
+    #
+    # === Parameters
+    # uuid(String):: Global session UUID
+    # expired_at(Time):: When the session expired (or will expire)
+    #
+    # === Return
+    # valid(true|false):: whether the specified session is valid
+    def valid_session?(uuid, expired_at)
+      expired_at > Time.now
+    end
+
+    # Callback used by Session objects to report when the application code calls
+    # #invalidate! on them. The default implementation of this method does nothing.
+    #
+    # uuid(String):: Global session UUID
+    # expired_at(Time):: When the session expired
+    #
+    # === Return
+    # true:: Always returns true
+    def report_invalid_session(uuid, expired_at)
+      true
+    end
+  end  
+end

data/lib/global_session/encoding.rb

@@ -0,0 +1,70 @@
+module GlobalSession
+  # Various encoding (not encryption!) techniques used by the global session plugin.
+  #
+  module Encoding
+    # JSON serializer, used to serialize Hash objects in a form suitable
+    # for stuffing into a cookie.
+    #
+    class JSON
+      # Unserialize JSON to Hash.
+      #
+      # === Parameters
+      # json(String):: A well-formed JSON document
+      #
+      # === Return
+      # value(Hash):: An unserialized Ruby Hash
+      def self.load(json)
+        ::JSON.load(json)
+      end
+
+      # Serialize Hash to JSON document.
+      #
+      # === Parameters
+      # value(Hash):: The hash to be serialized
+      #
+      # === Return
+      # json(String):: A JSON-serialized representation of +value+
+      def self.dump(object)
+        return object.to_json
+      end
+    end
+
+    # Implements URL encoding, but without newlines, and using '-' and '_' as
+    # the 62nd and 63rd symbol instead of '+' and '/'. This makes for encoded
+    # values that can be easily stored in a cookie; however, they cannot
+    # be used in a URL query string without URL-escaping them since they
+    # will contain '=' characters.
+    #
+    # This scheme is almost identical to the scheme "Base 64 Encoding with URL
+    # and Filename Safe Alphabet," described in RFC4648, with the exception that
+    # this scheme preserves the '=' padding characters due to limitations of
+    # Ruby's built-in base64 encoding routines.
+    class Base64Cookie
+      # Decode a B64cookie-encoded string.
+      #
+      # === Parameters
+      # encoded(String):: The encoded string
+      #
+      # === Return
+      # decoded(String):: The decoded result, which may contain nonprintable bytes
+      def self.load(string)
+        tr = string.tr('-_', '+/')
+        return tr.unpack('m')[0]
+      end
+      
+      # Encode a Ruby (ASCII or binary) string.
+      #
+      # === Parameters
+      # decoded(String):: The raw string to be encoded
+      #
+      # === Return
+      # encoded(String):: The B64cookie-encoded result.
+      def self.dump(object)
+        raw = [object].pack('m')
+        raw.tr!('+/', '-_')
+        raw.gsub!("\n", '')
+        return raw
+      end
+    end
+  end
+end

data/lib/global_session/integrated_session.rb

@@ -0,0 +1,123 @@
+module GlobalSession
+  # Helper class that enables the end user to treat the global and local session as if
+  # they were the same object. This is accomplished by implementing approximately the
+  # same interface as a Hash, and dispatching to one or the other session object depending
+  # on various factors.
+  #
+  # This class isn't intended to be used directly by the end user. Instead, set integrated: true
+  # in the configuration file and the Web framework integration code will manage an integrated
+  # session object for you, as well as overriding the framework's default session accessor to
+  # return an integrated session instead.
+  #
+  # When using an integrated session, you can always get to the underlying objects by
+  # using the #local and #global readers of this class.
+  #
+  class IntegratedSession
+    # Return the local-session objects, whose type may vary depending on the Web framework.
+    attr_reader :local
+
+    # Return the global-session object.
+    attr_reader :global
+    
+    # Construct a new integrated session.
+    #
+    # === Parameters
+    # local(Object):: Local session that acts like a Hash
+    # global(Session):: Session
+    def initialize(local, global)
+      @local = local
+      @global = global
+    end
+
+    # Retrieve a value from the global session if the supplied key is supported by
+    # the global session, else retrieve it from the local session.
+    #
+    # === Parameters
+    # key(String):: the key
+    #
+    # === Return
+    # value(Object):: The value associated with +key+, or nil if +key+ is not present
+    def [](key)
+      key = key.to_s
+      if @global.supports_key?(key)
+        @global[key]
+      else
+        @local[key]
+      end
+    end
+
+    # Set a value in the global session (if the supplied key is supported) or the local
+    # session otherwise.
+    #
+    # === Parameters
+    # key(String):: The key to set
+    # value(Object):: The value to set
+    #
+    # === Return
+    # value(Object):: Always returns the value that was set
+    def []=(key, value)
+      key = key.to_s
+      if @global.supports_key?(key)
+        @global[key] = value
+      else
+        @local[key] = value
+      end
+
+      return value
+    end
+
+    # Determine whether the global or local session contains a value with the specified key.
+    #
+    # === Parameters
+    # key(String):: The name of the key
+    #
+    # === Return
+    # contained(true|false):: Whether the session currently has a value for the specified key.
+    def has_key?(key)
+      key = key.to_s
+      @global.has_key?(key) || @local.has_key?(key)
+    end
+
+    # Return the keys that are currently present in either the global or local session.
+    #
+    # === Return
+    # keys(Array):: List of keys contained in the global or local session.
+    def keys
+      @global.keys + @local.keys
+    end
+
+    # Return the values that are currently present in the global or local session.
+    #
+    # === Return
+    # values(Array):: List of values contained in the global or local session.
+    def values
+      @global.values + @local.values
+    end
+
+    # Iterate over each key/value pair in both the global and local session.
+    #
+    # === Block
+    # An iterator which will be called with each key/value pair
+    #
+    # === Return
+    # Returns the value of the last expression evaluated by the block
+    def each_pair(&block)
+      @global.each_pair(&block)
+      @local.each_pair(&block)
+    end
+
+    def respond_to?(meth) # :nodoc:
+      return @global.respond_to?(meth) || @local.respond_to?(meth) || super
+    end
+    
+    def method_missing(meth, *args) # :nodoc:
+      if @global.respond_to?(meth)
+        @global.__send__(meth, *args)
+      elsif @local.respond_to?(meth)
+        @local.__send__(meth, *args)
+      else
+        super
+      end
+    end
+  end
+end