aker-rails 2.0.2

data/CHANGELOG.md

@@ -0,0 +1,45 @@
+Aker-Rails History
+==================
+
+2.0.2
+-----
+
+### Development
+
+- First open-source version.
+- Project renamed from `bcsec-rails` to `aker-rails` to match the
+  renaming of the main project.
+- Switch integration test suite from Celerity to Mechanize. (#3931)
+  This eliminates the JRuby dependency for integration testing.
+
+Bcsec-Rails History
+===================
+
+2.0.1
+-----
+
+### Fixed
+
+- The bcsec middleware is no longer appended to the stack multiple
+  times when class reloading is active. (#4486)
+
+### Development
+
+- Use bundler 1.0. (#3930)
+- CI builds use most-recent-available gems for all dependencies,
+  including prerelease versions of bcsec. (#4422, #4427)
+
+2.0.0
+-----
+
+### Features
+
+- Package bcsec-rails as a gem
+- Namespace everything under `Bcsec::Rails`
+
+### Development
+
+- Full integrated test suite with cucumber, celerity, and a sample app
+- Full API documentation
+- Start tracking changes to the plugin
+- Move to internal git repo

data/README.md

@@ -0,0 +1,151 @@
+Aker-Rails
+===========
+
+`aker-rails` is the Rails plugin for Aker 3.0 and later.  It is a
+thin wrapper around Aker's rack support.
+
+There are separate plugins for Rails 3.x and Rails 2.3.x. You're
+looking at the version for **Rails 2.3.x**. The version for Rails 3.x
+has a version number with major version 3.
+
+Setup
+-----
+
+### Prerequisites
+
+`aker-rails` requires Rails ~> 2.3.5.
+
+Since `aker-rails` is just a thin wrapper, you'll want to be familiar
+with [Aker][] before you get started.
+
+[Aker]: http://rubydoc.info/github/NUBIC/aker/master/file/README.md
+
+### Get the gem
+
+`aker-rails` is a gem plugin.  In order to use it, either install the
+gem at the system level or (better) include it in your bundler-using
+application's Gemfile.
+
+#### Okay
+
+    !!!plain
+    $ gem install aker-rails
+
+#### Better
+
+    # in your Gemfile
+    gem 'aker-rails', '~> 2.0'
+
+### Add it to the application
+
+Next, configure the gem into your Rails application's environment.
+(This is necessary for gem plugins even if you are using bundler.)
+
+    # In config/environment.rb's initializer block
+    config.gem "aker-rails", :lib => 'aker/rails', :version => '~> 2.0'
+
+### Add an initializer for aker
+
+Put your global configuration in an initializer. By _global
+configuration_ I mean the parts that are the same no matter which
+environment you are using, like the portal name and the modes.  (N.b.:
+You have to put it in an initializer — if you just put it at the
+end of `config/environment.rb` it won't work.)
+
+    # In config/initializers/aker.rb
+    Aker.configure do
+      # The authentication protocol to use for interactive access.
+      # `:form` is the default.
+      ui_mode :form
+
+      # The authentication protocol(s) to use for non-interactive
+      # access.  There is no default.
+      api_mode :http_basic
+
+      # The portal to which this application belongs.  Optional.
+      portal :ENU
+    end
+
+For more information on the configuration syntax and options, see the
+aker API documentation for {Aker::Configuration}.
+
+### Add per-environment configurations
+
+In the environment initializer for each of your application's
+environments, put the parts of the Aker configuration which are
+env-specific. E.g., the LDAP server you use in production might not be
+visible from your workstation. This means that the `authorities` line
+will be env-specific.
+
+    # In config/environments/production.rb, for example
+    config.after_initialize do
+      Aker.configure do
+        # The authorities to use.  See the aker API documentation
+        # for `Aker::Authorities` for options.
+        authorities :ldap
+
+        # The server-central parameters file for authority
+        # and policy parameters (optional). See
+        # `Aker::CentralParameters` for a discussion of why this is a
+        # good idea.
+        central '/etc/nubic/aker-prod.yml'
+      end
+    end
+
+Integration into your app
+-------------------------
+
+With the plugin installed, Aker provides a general infrastructure for
+supporting authentication and authorization in your application.  If
+you want to _require_ authentication or authorization for particular
+resources (and I think you do), you need to do a bit more
+configuration.
+
+### Securing pages
+
+In any controller which authentication is required, include
+{Aker::Rails::SecuredController}.  If authentication is required for
+all controllers, you can include this module in
+`ApplicationController`.
+
+If you want to further require that all actions in a controller
+require that the user be a member of a certain group, you can use the
+{Aker::Rails::SecuredController::ClassMethods#permit permit} method:
+
+    class ManuscriptController < ActionController::Base
+      include Aker::Rails::SecuredController
+      permit :editor
+    end
+
+### Partial authorization
+
+Aker also supports resources which are only partially limited to a
+particular group or groups.  The helper for this is also called
+{Aker::Rails::Application#permit? permit}:
+
+    # In a controller action
+    class DashboardController < ActionController::Base
+      # ...
+      def index
+        if permit?(:editor)
+          @manuscripts = Manuscript.all
+        end
+      end
+    end
+
+    # Or in a view
+    <%= permit?(:editor) do %>
+       @manuscripts.collect { |m| m.title }.join(', ')
+    <% end %>
+
+This permit helper is available to all controllers and views, not just
+ones that mix in {Aker::Rails::SecuredController}.  This means you
+can have a publically-accessible page which has additional/different
+content for a logged-in user.
+
+### The current user
+
+Aker provides a method {Aker::Rails::Application#current_user
+current_user} to all controllers and views.  It will return a
+{Aker::User} object for the current user, or `nil` if there isn't
+one.

data/lib/aker/rails/application.rb

@@ -0,0 +1,60 @@
+require 'aker/rails'
+
+module Aker::Rails
+  ##
+  # A mixin for the rails application controller.  Provides global
+  # aker integration, but does not enforce any authentication or
+  # authorization requirements.  (See
+  # {Aker::Rails::SecuredController} for one way to enforce
+  # authentication and authorization.)
+  #
+  # This module is automatically mixed into the application controller
+  # when the plugin is initialized.
+  module Application
+    ##
+    # Sets up the aker global infrastructure and helpers in the
+    # application controller.
+    #
+    # @return [void]
+    def self.included(controller_class)
+      controller_class.class_eval do
+        helper_method :current_user, :permit?, :permit
+      end
+    end
+
+    ##
+    # Sets up the aker global infrastructure that is not affected by
+    # Rails' development-mode class reloading.
+    #
+    # @return [void]
+    def self.one_time_setup
+      Aker::Rack.use_in(ActionController::Dispatcher.middleware)
+      Rack::Request.send(:include, Aker::Rack::RequestExt)
+    end
+
+    ##
+    # Exposes the logged-in user (if any) to the application.
+    #
+    # This method is also available to views (i.e., it is a helper).
+    #
+    # @return [Aker::User,nil]
+    def current_user
+      request.env['aker.check'].user
+    end
+
+    ##
+    # Aids group-level authorization.  It is safe to call this method
+    # without checking that there is a logged in user first.
+    #
+    # This method delegates directly to {Aker::Rack::Facade#permit?};
+    # see the documentation for that method for more information.
+    #
+    # This method is also available to views (i.e., it is a helper).
+    #
+    # @return [Boolean,Object,nil]
+    def permit?(*groups, &block)
+      request.env['aker.check'].permit?(*groups, &block)
+    end
+    alias :permit :permit?
+  end
+end

data/lib/aker/rails/secured_controller.rb

@@ -0,0 +1,66 @@
+require 'aker/rails'
+
+module Aker::Rails
+  ##
+  # This mixin tags a controller as always requiring authentication.
+  #
+  # It also adds a
+  # {Aker::Rails::SecuredController::ClassMethods#permit method}
+  # which allows you to mark a controller as only accessible to a
+  # particular group or groups.  For example:
+  #
+  #     class SecretController
+  #       include Aker::Rails::SecuredController
+  #       permit :confidential
+  #     end
+  module SecuredController
+    ##
+    # @private implements the behavior described by the module
+    #   description
+    # @return [void]
+    def self.included(controller_class)
+      controller_class.before_filter :aker_authorize
+      controller_class.extend ClassMethods
+    end
+
+    ##
+    # The filter which actually forces any user accessing a controller
+    # which mixes this in to be authenticated.
+    #
+    # It delegates to {Aker::Rack::Facade#authentication_required!};
+    # see that method's documentation for more information.
+    #
+    # @return [void]
+    def aker_authorize
+      request.env['aker.check'].authentication_required!
+    end
+
+    ##
+    # Extensions for the rails controller DSL for
+    # authentication-required controllers.
+    #
+    # @see SecuredController
+    module ClassMethods
+      ##
+      # Tags a controller as requiring that a user both be
+      # authenticated and belong to one of a set of groups.
+      #
+      # It delegates to {Aker::Rack::Facade#permit!}; see that
+      # methods's documentation for more information.
+      #
+      # @return [void]
+      def permit(*groups)
+        options =
+          if Hash === groups.last
+            groups.pop
+          else
+            {}
+          end
+
+        before_filter(options) do |controller|
+          controller.request.env['aker.check'].permit!(*groups)
+        end
+      end
+    end
+  end
+end

data/lib/aker/rails/test/helpers.rb

@@ -0,0 +1,33 @@
+require File.join(File.dirname(__FILE__), %w(.. test))
+
+##
+# Helpers for common test tasks.
+#
+# To use these helpers with a Rails application using RSpec:
+#
+#     # spec/spec_helper.rb
+#     Spec::Runner.configure do |config|
+#       config.include Aker::Rails::Test::Helpers
+#       ...
+#     end
+module Aker::Rails::Test::Helpers
+  include Aker::Test::Helpers
+
+  ##
+  # Logs in a user.
+  #
+  # Users can be identified by:
+  #
+  # * their username
+  # * building a `Aker::User` instance representing that user
+  # * the return value of
+  #
+  #       Aker.authority.valid_credentials?(:user, username, password)
+  #
+  #   (which is a `Aker::User`)
+  #
+  # @param [String, Aker::User] user a user's username or `Aker::User` object
+  def login_as(user)
+    request.env.merge!(login_env(user))
+  end
+end

data/lib/aker/rails/test.rb

@@ -0,0 +1,5 @@
+require File.join(File.dirname(__FILE__), %w(.. rails))
+
+module Aker::Rails::Test
+  autoload :Helpers, 'aker/rails/test/helpers'
+end

data/lib/aker/rails/version.rb

@@ -0,0 +1,7 @@
+module Aker
+  module Rails
+    # VERSION is in a separate file with no external dependencies so it
+    # can be sourced from the gemspec.
+    VERSION = "2.0.2"
+  end
+end

data/lib/aker/rails.rb

@@ -0,0 +1,16 @@
+require 'aker'
+
+module Aker
+  ##
+  # Rails integration for aker.  In general, it is a thin wrapper
+  # around aker's rack integration.
+  #
+  # Everything in this module is in the `aker-rails` gem plugin.
+  module Rails
+    autoload :VERSION, 'aker/rails/version'
+
+    autoload :Application,       'aker/rails/application'
+    autoload :SecuredController, 'aker/rails/secured_controller'
+    autoload :Test,              'aker/rails/test'
+  end
+end

data/rails/init.rb

@@ -0,0 +1,18 @@
+require 'aker/rails'
+
+Rails.logger.debug "Initializing aker-rails"
+# We do this up here to allow the application to override if desired
+Aker.configure {
+  logger Rails.logger
+}
+config.after_initialize do
+  Aker::Rails::Application.one_time_setup
+
+  if config.cache_classes
+    ApplicationController.send(:include, Aker::Rails::Application)
+  else
+    config.to_prepare do
+      ApplicationController.send(:include, Aker::Rails::Application)
+    end
+  end
+end

data/spec/aker/rails/application_spec.rb

@@ -0,0 +1,87 @@
+require File.expand_path("../../../spec_helper", __FILE__)
+require 'rack'
+require 'action_controller'
+
+module Aker::Rails
+  class FakeApplicationController
+    attr_accessor :request
+
+    def self.helper_method(*names)
+      helper_methods.concat(names)
+    end
+
+    def self.helper_methods
+      @helper_methods ||= []
+    end
+
+    Aker.configure { }
+    include Application
+    Aker.configuration = nil
+  end
+
+  describe Application do
+    before do
+      @controller = FakeApplicationController.new
+
+      @env = Rack::MockRequest.env_for('/')
+      @env['aker.check'] = (@aker = mock)
+      @controller.request = Rack::Request.new(@env)
+    end
+
+    it "adds current_user" do
+      @aker.should_receive(:user).and_return(Aker::User.new("jo"))
+
+      @controller.current_user.username.should == "jo"
+    end
+
+    it "defines current_user as a helper method" do
+      @controller.class.helper_methods.should include(:current_user)
+    end
+
+    describe "#permit?" do
+      it "delegates to the aker rack facade" do
+        @aker.should_receive(:permit?).with(:bar, :quux)
+
+        @controller.permit?(:bar, :quux)
+      end
+
+      it "passes a block to the aker rack facade, if present" do
+        @aker.should_receive(:permit?).with(:bar, :quux).and_yield
+
+        @controller.permit?(:bar, :quux) { 1 + 1 }.should == 2
+      end
+
+      it "is registered as a helper method" do
+        @controller.class.helper_methods.should include(:permit?)
+      end
+
+      describe "permit alias" do
+        it "exists" do
+          @aker.should_receive(:permit?).with(:bar, :baz)
+
+          @controller.permit(:bar, :baz)
+        end
+
+        it "is also registered as a helper method" do
+          @controller.class.helper_methods.should include(:permit)
+        end
+      end
+    end
+  end
+
+  describe Application, ".one_time_setup" do
+    before do
+      Aker.configure { }
+
+      Application.one_time_setup
+    end
+
+    after do
+      Aker.configuration = nil
+    end
+
+    it "adds the aker middleware to the action controller middleware stack" do
+      ActionController::Dispatcher.middleware.should include(Aker::Rack::Setup)
+    end
+  end
+end

data/spec/aker/rails/secured_controller_spec.rb

@@ -0,0 +1,69 @@
+require File.expand_path("../../../spec_helper", __FILE__)
+require 'rack'
+
+module Aker::Rails
+  class SomeController
+    attr_accessor :request
+
+    def initialize(request)
+      @request = request
+    end
+
+    def self.before_filter(*args, &block)
+      filter =
+        if block
+          block
+        else
+          args.shift
+        end
+      self.before_filters << [filter, *args]
+    end
+
+    def self.before_filters
+      @before_filters ||= []
+    end
+
+    include Aker::Rails::SecuredController
+  end
+
+  describe SecuredController do
+    before do
+      @request = Rack::Request.new(Rack::MockRequest.env_for("/some"))
+      @aker = (@request.env['aker.check'] = mock)
+      @controller = SomeController.new(@request)
+    end
+
+    describe "#aker_authorize" do
+      it "is registered as a filter" do
+        @controller.class.before_filters.should == [ [:aker_authorize] ]
+      end
+
+      it "invokes authentication_required on the aker rack facade" do
+        @aker.should_receive(:authentication_required!)
+        @controller.aker_authorize
+      end
+    end
+
+    describe ".permit" do
+      it "adds a filter" do
+        @controller.class.permit(:foo, :quux)
+        @controller.class.should have(2).before_filters
+        @controller.class.before_filters.last[0].class.should == Proc
+      end
+
+      describe "and options" do
+        it "passes options on to before_filter" do
+          @controller.class.permit(:foo, :quux, :only => :zamm)
+          @controller.class.before_filters.last[1].should == { :only => :zamm }
+        end
+
+        it "passes empty options if no options are specified" do
+          @controller.class.permit(:foo, :quux, :vom)
+          @controller.class.before_filters.last[1].should == {}
+        end
+      end
+    end
+
+    # filter behavior is further characterized in integrated tests
+  end
+end

data/spec/aker/rails/test/helpers_spec.rb

@@ -0,0 +1,40 @@
+require File.expand_path("../../../../spec_helper", __FILE__)
+require 'action_controller'
+require 'action_controller/test_process'
+
+module Aker::Rails::Test
+  describe Helpers do
+    before do
+      Aker.configure do
+        s = Aker::Authorities::Static.new
+
+        s.valid_credentials!(:user, "jo", "50-50")
+        authorities s
+      end
+
+      @test_case = Class.new do
+        include Aker::Rails::Test::Helpers
+
+        def request
+          @request ||= ActionController::TestRequest.new
+        end
+      end.new
+    end
+
+    describe "#login_as" do
+      it "logs in a user by username" do
+        @test_case.login_as("jo")
+
+        @test_case.request.env['aker.check'].user.username.should == "jo"
+      end
+
+      it "accepts Aker::User objects" do
+        user = Aker::User.new("jo")
+
+        @test_case.login_as(user)
+
+        @test_case.request.env['aker.check'].user.should == user
+      end
+    end
+  end
+end

data/spec/aker/rails_spec.rb

@@ -0,0 +1,13 @@
+require File.expand_path("../../spec_helper", __FILE__)
+
+describe Aker::Rails do
+  describe "::VERSION" do
+    it "exists" do
+      lambda { Aker::Rails::VERSION }.should_not raise_error
+    end
+
+    it "has three or four dot-separated parts" do
+      Aker::Rails::VERSION.split('.').size.should be_between(3, 4)
+    end
+  end
+end

data/spec/deprecation_helper.rb

@@ -0,0 +1,61 @@
+module Aker::Rails
+  module Spec
+    # Copied from aker due to laziness.  May want to separate out and
+    # share later.
+
+    class DeprecationMode
+      def self.use_in(spec_config)
+        spec_config.include DeprecationHelper
+
+        spec_config.before(:each) do
+          @original_deprecation_mode, Aker::Deprecation.mode =
+            Aker::Deprecation.mode, DeprecationMode.new
+        end
+
+        spec_config.after(:each) do
+          begin
+            Aker::Deprecation.mode.fail_if_any_very_obsolete
+          ensure
+            Aker::Deprecation.mode = @original_deprecation_mode
+          end
+        end
+      end
+
+      def messages
+        @messages ||= []
+      end
+
+      def report(level, message, version)
+        messages << { :level => level, :message => message, :version => version }
+      end
+
+      def reset
+        @messages = nil
+      end
+
+      def fail_if_any_very_obsolete
+        obs = messages.select { |m| very_obsolete?(m[:version]) }
+        unless obs.empty?
+          fail "Very obsolete code still present.  Remove it and its specs.\n" <<
+            "- #{obs.collect { |o| o[:message] }.join("\n- ")}"
+        end
+      end
+
+      def very_obsolete?(version)
+        # "very obsolete" if it was deprecated at least two minor
+        # versions ago
+        major_minor(Aker::Rails::VERSION) - Rational(2, 10) >= major_minor(version)
+      end
+
+      def major_minor(version)
+        Rational(version.split('.')[0, 2].inject(0) { |s, i| s = s * 10 + i.to_i }, 10)
+      end
+    end
+
+    module DeprecationHelper
+      def deprecation_message(n=0)
+        (Aker::Deprecation.mode.messages[n] || {})[:message]
+      end
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,11 @@
+require "spec"
+
+$LOAD_PATH.unshift File.expand_path("../../lib", __FILE__)
+
+require 'aker/rails'
+
+require File.expand_path('../deprecation_helper', __FILE__)
+
+Spec::Runner.configure do |config|
+  Aker::Rails::Spec::DeprecationMode.use_in(config)
+end

metadata

@@ -0,0 +1,113 @@
+--- !ruby/object:Gem::Specification 
+name: aker-rails
+version: !ruby/object:Gem::Version 
+  hash: 11
+  prerelease: false
+  segments: 
+  - 2
+  - 0
+  - 2
+  version: 2.0.2
+platform: ruby
+authors: 
+- David Yip
+- Rhett Sutphin
+- Peter Nyberg
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-07-20 00:00:00 -05:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  version_requirements: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 9
+        segments: 
+        - 2
+        - 3
+        - 5
+        version: 2.3.5
+  requirement: *id001
+  name: rails
+  prerelease: false
+  type: :runtime
+- !ruby/object:Gem::Dependency 
+  version_requirements: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 7
+        segments: 
+        - 3
+        - 0
+        version: "3.0"
+  requirement: *id002
+  name: aker
+  prerelease: false
+  type: :runtime
+description: 
+email: r-sutphin@northwestern.edu
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- CHANGELOG.md
+- README.md
+- lib/aker/rails/application.rb
+- lib/aker/rails/secured_controller.rb
+- lib/aker/rails/test/helpers.rb
+- lib/aker/rails/test.rb
+- lib/aker/rails/version.rb
+- lib/aker/rails.rb
+- spec/aker/rails/application_spec.rb
+- spec/aker/rails/secured_controller_spec.rb
+- spec/aker/rails/test/helpers_spec.rb
+- spec/aker/rails_spec.rb
+- spec/deprecation_helper.rb
+- spec/spec_helper.rb
+- rails/init.rb
+has_rdoc: true
+homepage: https://github.com/NUBIC/aker-rails
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Easy Rails integration for the Aker security framework
+test_files: []
+