aker 3.0.0.pre

data/lib/aker/modes.rb

@@ -0,0 +1,48 @@
+require 'aker'
+
+module Aker
+  ##
+  # Mode support code.
+  #
+  # A mode implements an authentication protocol, and is classified as a _UI
+  # mode_, an _API mode_, or both.  UI modes are intended for interactive use;
+  # API modes are intended for non-interactive use.
+  #
+  # Aker ships with five modes:
+  #
+  # - {Aker::Cas::ServiceMode :cas} is a UI mode that provides interactive login via
+  #   a CAS server.
+  # - {Aker::Cas::ProxyMode :cas_proxy} is an API mode that implements the
+  #   CAS proxying protocol.
+  # - {Aker::Form::Mode :form} is a UI mode that provides an HTML form that
+  #   prompts for username and password.
+  # - {Aker::Form::CustomViewsMode :custom_form} is a specialization
+  #   of `:form` for apps that wish to provide their own form views.
+  # - {Aker::Modes::HttpBasic :http_basic} is an API/UI mode that implements
+  #   the HTTP Basic authentication protocol.  (It's both an API and UI mode
+  #   because it can be used by automated Web clients and humans alike.)
+  #
+  # Aker permits applications to use as many API modes as they wish,
+  # but requires that applications have one and only one UI mode.  The
+  # default UI mode is `:form`.
+  #
+  # @see Aker::Configuration#ui_mode=
+  # @see Aker::Configuration#api_modes=
+  module Modes
+    autoload :Base,       'aker/modes/base'
+    autoload :HttpBasic,  'aker/modes/http_basic'
+    autoload :Support,    'aker/modes/support'
+
+    ##
+    # @private
+    class Slice < Aker::Configuration::Slice
+      def initialize
+        super do
+          register_mode Aker::Modes::HttpBasic
+        end
+      end
+    end
+  end
+end
+
+Aker::Configuration.add_default_slice(Aker::Modes::Slice.new)

data/lib/aker/rack/authenticate.rb

@@ -0,0 +1,37 @@
+require 'aker'
+
+module Aker::Rack
+  ##
+  # The middleware which actually performs authentication according to
+  # the mode that applies to the request (if any). Most of the heavy
+  # lifting is performed by Warden.
+  class Authenticate
+    include EnvironmentHelper
+
+    def initialize(app)
+      @app = app
+    end
+
+    ##
+    # Authenticates incoming requests using Warden.
+    #
+    # Additionally, this class exposes the `aker.check` environment
+    # variable to downstream middleware and the app.  It is an
+    # instance of {Aker::Rack::Facade} permitting authentication and
+    # authorization queries about the current user (if any).
+    def call(env)
+      configuration = configuration(env)
+      warden = env['warden']
+
+      if interactive?(env)
+        warden.authenticate(configuration.ui_mode)
+      else
+        warden.authenticate(*configuration.api_modes)
+      end
+
+      env['aker.check'] = Facade.new(configuration, warden.user)
+
+      @app.call(env)
+    end
+  end
+end

data/lib/aker/rack/configuration_helper.rb

@@ -0,0 +1,18 @@
+require 'aker'
+
+module Aker::Rack
+  ##
+  # Methods used by Rack middleware for reading configuration data out of the
+  # Rack environment.
+  module ConfigurationHelper
+    include EnvironmentHelper
+
+    def login_path(env)
+      configuration(env).parameters_for(:rack)[:login_path]
+    end
+
+    def logout_path(env)
+      configuration(env).parameters_for(:rack)[:logout_path]
+    end
+  end
+end

data/lib/aker/rack/default_logout_responder.rb

@@ -0,0 +1,36 @@
+require 'aker'
+
+module Aker::Rack
+  ##
+  # Provides a default response for `GET` of the application's
+  # configured logout path.
+  class DefaultLogoutResponder
+    include ConfigurationHelper
+
+    ##
+    # Instantiates the middleware.
+    #
+    # @param app [Rack app] the Rack application on which this middleware
+    #                       should be layered
+    def initialize(app)
+      @app = app
+    end
+
+    ##
+    # When the path is the configured logout path, renders a logout
+    # response.
+    #
+    # @param env [Hash] a Rack environment
+    def call(env)
+      result = @app.call(env)
+
+      if result.first == 404 &&
+          env['REQUEST_METHOD'] == 'GET' &&
+          env['PATH_INFO'] == logout_path(env)
+        ::Rack::Response.new('You have been logged out.', 200).finish
+      else
+        result
+      end
+    end
+  end
+end

data/lib/aker/rack/environment_helper.rb

@@ -0,0 +1,34 @@
+require 'aker'
+
+module Aker::Rack
+  ##
+  # Methods used by Rack middleware for reading Aker data out of the Rack
+  # environment.
+  module EnvironmentHelper
+    ##
+    # Returns the {Configuration} instance for the current request.
+    #
+    # @return [Aker::Configuration]
+    def configuration(env)
+      env['aker.configuration']
+    end
+
+    ##
+    # Whether the current request is interactive.
+    #
+    # @see Aker::Rack::Setup#call
+    # @see Aker::Rack::Setup#interactive?
+    # @return [Boolean]
+    def interactive?(env)
+      env['aker.interactive']
+    end
+
+    ##
+    # The authority to use for credential validation.
+    #
+    # @return [Object]
+    def authority(env)
+      env['aker.authority']
+    end
+  end
+end

data/lib/aker/rack/facade.rb

@@ -0,0 +1,102 @@
+require 'aker/rack'
+
+module Aker::Rack
+  ##
+  # Provides a simple interface which aker-using rack apps may use to
+  # indicate that authentication or authorization is required for a
+  # particular action.
+  #
+  # An instance of this class is available in the rack environment
+  # under the `"aker"` key.
+  class Facade
+    ##
+    # The current authenticated user.
+    #
+    # @return [Aker::User]
+    attr_accessor :user
+
+    ##
+    # The aker configuration in effect for this application.
+    #
+    # @return [Aker::Configuration]
+    attr_accessor :configuration
+
+    def initialize(config, user)
+      @configuration = config
+      @user = user
+    end
+
+    ##
+    # Indicates that authentication is required for a particular
+    # request.  If the user is not authenticated, any application code
+    # after this method is called will not be executed.  The user will
+    # be directed to authenticate according to their access style
+    # (ui vs. api) and the application configuration (i.e., the
+    # appropriate {Modes mode}).
+    #
+    # If the application has a {Aker::Configuration#portal portal}
+    # configured, aker will also check that the user has access to
+    # that portal.  If the user is authenticated but does not have
+    # access to the portal, she will get a `403 Forbidden` response.
+    #
+    # @see #authenticated?
+    # @return [void]
+    def authentication_required!
+      throw :warden, inauthentic_reason unless authenticated?
+    end
+
+    ##
+    # Returns true if there is an authenticated user, false otherwise.
+    # This check follows the same rules as
+    # {#authentication_required!}, including the portal check.
+    # However, it does not halt processing if the user is not
+    # authenticated.
+    #
+    # @return [Boolean]
+    def authenticated?
+      inauthentic_reason.nil?
+    end
+
+    ##
+    # A shortcut to invoking {Aker::User#permit?} on the {#user
+    # current user}.  As with that method, the block is optional.
+    #
+    # This method safely handles the case where there is no user
+    # logged in.
+    #
+    # @param [Array<#to_sym>] groups
+    # @return [Boolean, Object, nil] `nil` if there's no one logged in;
+    #   otherwise the same as {Aker::User#permit?}.
+    def permit?(*groups, &block)
+      return nil unless user
+      user.permit?(*groups, &block)
+    end
+    alias :permit :permit?
+
+    ##
+    # Indicates that a user must be in one of the specified groups to
+    # proceed.  If there is a user logged in and she is not in any of
+    # the specified groups, she will get a `403 Forbidden` response.
+    # If the user is not logged in, she will be prompted to log in
+    # (just like with {#authentication_required!}).
+    #
+    # @return [void]
+    def permit!(*groups)
+      authentication_required!
+      throw :warden, :groups_required => groups unless user.permit?(*groups)
+    end
+
+    private
+
+    def inauthentic_reason
+      @inauthentic_reason =
+        if !user
+          { :login_required => true }
+        elsif !configuration.portal? || user.may_access?(configuration.portal)
+          nil
+        else
+          { :portal_required => configuration.portal }
+        end
+    end
+  end
+end

data/lib/aker/rack/failure.rb

@@ -0,0 +1,69 @@
+require 'aker/rack'
+require 'warden'
+
+module Aker::Rack
+  ##
+  # The Rack endpoint which handles authentication failures.
+  #
+  # @see Aker::Rack.use_in
+  # @see http://wiki.github.com/hassox/warden/failures
+  #      Warden failures documentation
+  class Failure
+    include EnvironmentHelper
+
+    ##
+    # Receives the rack environment in case of a failure and renders a
+    # response based on the interactiveness of the request and the
+    # nature of the configured modes.
+    #
+    # @param [Hash] env a rack environment
+    #
+    # @return [Array] a rack response
+    def call(env)
+      conf = configuration(env)
+      if login_required?(env)
+        if interactive?(env)
+          ::Warden::Strategies[conf.ui_mode].new(env).on_ui_failure.finish
+        else
+          headers = {}
+          headers["WWW-Authenticate"] =
+            conf.api_modes.collect { |mode_key|
+            ::Warden::Strategies[mode_key].new(env).challenge
+          }.join("\n")
+          headers["Content-Type"] = "text/plain"
+          [401, headers, ["Authentication required"]]
+        end
+      else
+        log_authorization_failure(env)
+        msg = "#{user(env).username} may not use this page."
+        Rack::Response.
+          new("<html><head><title>Authorization denied</title></head><body>#{msg}</body></html>",
+              403,
+              "Content-Type" => "text/html").finish
+      end
+    end
+
+    private
+
+    def login_required?(env)
+      env['warden.options'][:login_required]
+    end
+
+    def user(env)
+      env['aker.check'].user
+    end
+
+    def log_authorization_failure(env)
+      wo = env['warden.options']
+      msg = "Resource authorization failure: User \"#{user(env).username}\" " <<
+        if wo[:portal_required]
+          "is not in the #{wo[:portal_required].inspect} portal."
+        elsif wo[:groups_required]
+          "is not in any of the required groups #{wo[:groups_required].inspect}."
+        else
+          "is just generally unauthorized.  Don't ask questions."
+        end
+      configuration(env).logger.info(msg)
+    end
+  end
+end

data/lib/aker/rack/logout.rb

@@ -0,0 +1,63 @@
+require 'aker'
+
+module Aker
+  module Rack
+    ##
+    # Middleware for ending authenticated sessions.  This middleware
+    # listens for `GET` requests to the logout path and when such
+    # requests are received, clears user data.
+    #
+    # The logout path is `/logout` by default. It may be overridden in
+    # the Aker configuration by setting a value for `:logout_path` in
+    # the `:rack` parameter group.
+    #
+    # ## Implications of GET
+    #
+    # `GET` was chosen to ensure that there always exists a way to clear
+    # application session data independent of whether it is possible to get to a
+    # logout link.  (If unmarshalable data exists in the session -- say, stored
+    # objects whose format has changed between application revisions -- it is
+    # possible to get into a state where logout links cannot be accessed.)
+    #
+    # Using `GET` does mean that it is possible to execute CSRF attacks that
+    # will log out the user.  The severity of this can range from a minor
+    # annoyance (just having to log in again while browsing a series of pages)
+    # to major (losing all data in a large POST).
+    #
+    # @see Aker::Rack.use_in
+    #
+    # @author David Yip
+    class Logout
+      include ConfigurationHelper
+
+      ##
+      # Instantiates the middleware.
+      #
+      # @param app [Rack app] the Rack application on which this middleware
+      #                       should be layered
+      def initialize(app)
+        @app = app
+      end
+
+      ##
+      # When given a `GET` for the configured logout path, invokes
+      # Warden's logout procedure (which resets the session), and
+      # passes control down to the rest of the application.
+      #
+      # If the application or a mode does not provide a handler for
+      # the configured logout path, then the handler defined by
+      # {DefaultLogoutResponder} will be invoked.
+      #
+      # @see Aker::Rack.use_in
+      # @param env [Hash] a Rack environment
+      # @return [Array] a finished Rack response
+      def call(env)
+        if env['REQUEST_METHOD'] == 'GET' && env['PATH_INFO'] == logout_path(env)
+          env['warden'].logout
+        end
+
+        @app.call(env)
+      end
+    end
+  end
+end

data/lib/aker/rack/request_ext.rb

@@ -0,0 +1,19 @@
+require 'aker'
+
+module Aker::Rack
+  ##
+  # Extensions for `Rack::Request`.
+  #
+  # To use these, `include` them into `Rack::Request`.
+  module RequestExt
+    include Aker::Rack::EnvironmentHelper
+
+    ##
+    # Whether the current request is interactive.
+    #
+    # @return [Boolean]
+    def interactive?
+      super(env)
+    end
+  end
+end

data/lib/aker/rack/session_timer.rb

@@ -0,0 +1,95 @@
+require 'aker'
+
+module Aker::Rack
+  ##
+  # Middleware that permits a Web application to enforce a session inactivity
+  # limit. When a request is made after the session expires, the
+  # middleware resets the session, forcing the user to be reauthenticated.
+  #
+  # The session inactivity limit is determined by the `session-timeout-seconds`
+  # parameter in Aker's `policy` parameter group.  It defaults to 1800 seconds
+  # (30 minutes), and can be overridden by a {Aker::ConfiguratorLanguage Aker
+  # configuration block} or {Aker::CentralParameters central parameters file}.
+  # To disable session timeout, set `session-timeout-seconds` to `nil` or `0`.
+  #
+  # Algorithm
+  # =========
+  #
+  # On each request:
+  #
+  #     let lr = timestamp of last request,
+  #         cr = timestamp of current request,
+  #         st = session timeout from configuration,
+  #         ta = lr + st
+  #
+  #     if st is nil
+  #       pass control to rest of application
+  #     end
+  #
+  #     store ta in the Rack environment as aker.timeout_at
+  #     lr := cr
+  #     store lr in the session
+  #
+  #     if lr is nil
+  #       pass control to rest of application
+  #     end
+  #
+  #     if cr is in [lr, ta]
+  #       pass control to rest of application
+  #     else
+  #       reset session
+  #       pass control to rest of application
+  #     end
+  #
+  #
+  # Requirements
+  # ============
+  #
+  # SessionTimer expects a session manager that behaves like a `Rack::Session`
+  # session manager to be present in the `rack.session` Rack environment
+  # variable.
+  #
+  # SessionTimer should be configured earlier in the middleware stack
+  # than any middleware which checks for cached
+  # credentials. {Aker::Rack.use_in} arranges things this way.
+  class SessionTimer
+    include EnvironmentHelper
+    include ConfigurationHelper
+
+    def initialize(app)
+      @app = app
+    end
+
+    ##
+    # Determines whether the incoming request arrived within the timeout
+    # window.  If it did, then the request is passed onto the rest of the Rack
+    # stack; otherwise, the user is redirected to the configured
+    # logout path.
+    #
+    def call(env)
+      now              = Time.now.to_i
+      session          = env['rack.session']
+      window_size      = window_size(env)
+      previous_timeout = session['aker.last_request_at']
+
+      return @app.call(env) unless window_size > 0
+
+      env['aker.timeout_at'] = now + window_size
+      session['aker.last_request_at'] = now
+
+      return @app.call(env) unless previous_timeout
+
+      if now >= previous_timeout + window_size
+        env['aker.session_expired'] = true
+        env['warden'].logout
+      end
+      @app.call(env)
+    end
+
+    private
+
+    def window_size(env)
+      configuration(env).parameters_for(:policy)[%s(session-timeout-seconds)].to_i
+    end
+  end
+end

data/lib/aker/rack/setup.rb

@@ -0,0 +1,77 @@
+require 'aker/rack'
+
+module Aker::Rack
+  ##
+  # The middleware which makes the aker environment available in the
+  # rake environment and authenticates the credentials that the
+  # request provides (if any).  It is responsible for determining
+  # whether the request is interactive or not and will use the
+  # appropriate configured {Aker::Modes mode} based on this decision.
+  #
+  # You probably don't want to `use` this directly; use
+  # {Aker::Rack.use_in} to configure in this middleware and all its
+  # dependencies simultaneously.
+  #
+  # @see Aker::Rack.use_in
+  # @see Aker::Configuration#ui_mode
+  # @see Aker::Configuration#api_modes
+  class Setup
+    ##
+    # Creates a new instance of the middleware.
+    #
+    # @param [#call] app the application this middleware is being
+    #   wrapped around.
+    # @param [Aker::Configuration] configuration the configuration to use for
+    #   this instance.
+    #
+    # @see Aker::Rack.use_in
+    def initialize(app, configuration)
+      @app = app
+      @configuration = configuration
+    end
+
+    ##
+    # Implements the rack middleware behavior.
+    #
+    # This class exposes three environment variables to downstream
+    # middleware and the app:
+    #
+    #  * `"aker.configuration"`: the {Aker::Configuration configuration}
+    #     for this application.
+    #  * `"aker.authority"`: the {Aker::Authorities authority} for
+    #    this application.
+    #  * `"aker.interactive"`: a boolean indicating whether this
+    #    request is being treated as an interactive (UI) or
+    #    non-interactive (API) request
+    #
+    # [There is a related fourth environment variable:
+    #
+    #  * `"aker.check"`: an instance of {Aker::Rack::Facade}
+    #    permitting authentication and authorization queries about the
+    #    current user (if any).
+    #
+    # This fourth variable is added by the {Authenticate} middleware;
+    # see its documentation for more.]
+    #
+    # @param [Hash] env the rack env
+    # @return [Array] the standard rack return
+    def call(env)
+      env['aker.configuration'] = @configuration
+      env['aker.authority'] = @configuration.composite_authority
+      env['aker.interactive'] = interactive?(env)
+
+      @app.call(env)
+    end
+
+    ##
+    # Determines if the given rack env represents an interactive
+    # request.
+    #
+    # @return [Boolean, nil] true if interactive, false or nil otherwise
+    def interactive?(env)
+      @configuration.api_modes.empty? or
+        env["HTTP_ACCEPT"] =~ %r{text/html} or
+        env["HTTP_USER_AGENT"] =~ %r{Mozilla}
+    end
+  end
+end