blacklight-access_controls 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 715bccb2faf2cc502417ad8d1f9052baf98c2c2e
+  data.tar.gz: c011219a6d76e3c0e6bba5640c9f5c92eb5fe300
+SHA512:
+  metadata.gz: d80acc63c003ee2d3b84b5790bd5a755cea409efb58ee4311fd6e5b236712c3fbbb92e9609f6e93e948bc7cfae7bd0938dfad4f51e6d109a603ce3dc4ea4dfdd
+  data.tar.gz: 54dfe0310b6df052616602eb53d0f916e431717f0a918b0d436e992d8ee9eacb03312d5b69de7be2d880f62bfc0ee1d10db2b653c66b60195321790a526cafad

data/.gitignore

@@ -0,0 +1,10 @@
+.rvmrc
+Gemfile.lock
+
+# Used by solr_wrapper
+solr
+tmp
+
+# Test app generated by engine_cart
+.internal_test_app
+

data/Gemfile

@@ -0,0 +1,32 @@
+source "https://rubygems.org"
+
+# Specify gem dependencies in blacklight-access_controls.gemspec
+gemspec
+
+# -------------------------
+# BEGIN ENGINE_CART BLOCK
+# engine_cart: 0.8.0
+# engine_cart stanza: 0.8.0
+# the below comes from engine_cart, a gem used to test this Rails engine gem in the context of a Rails app.
+file = File.expand_path("Gemfile", ENV['ENGINE_CART_DESTINATION'] || ENV['RAILS_ROOT'] || File.expand_path(".internal_test_app", File.dirname(__FILE__)))
+if File.exist?(file)
+  begin
+    eval_gemfile file
+  rescue Bundler::GemfileError => e
+    Bundler.ui.warn '[EngineCart] Skipping Rails application dependencies:'
+    Bundler.ui.warn e.message
+  end
+else
+  Bundler.ui.warn "[EngineCart] Unable to find test application dependencies in #{file}, using placeholder dependencies"
+
+  gem 'rails', ENV['RAILS_VERSION'] if ENV['RAILS_VERSION']
+
+  if ENV['RAILS_VERSION'].nil? || ENV['RAILS_VERSION'] =~ /^4.2/
+    gem 'responders', "~> 2.0"
+    gem 'sass-rails', ">= 5.0"
+  else
+    gem 'sass-rails', "< 5.0"
+  end
+end
+# END ENGINE_CART BLOCK
+# -------------------------

data/README.textile

@@ -0,0 +1,74 @@
+h1. Blacklight Access Controls
+
+Provides access controls for Blacklight-based applications.
+
+*Background*:  Much of this code was extracted from "hydra-access-controls":https://github.com/projecthydra/hydra-head/tree/master/hydra-access-controls
+
+
+h2. Adding Access Controls to a Blacklight App
+
+h3. Install the gem
+
+* Add blacklight-access_controls to your Gemfile
+* bundle install
+
+h3. Configure solr
+
+* Make sure your solrconfig.xml has a requestHandler for "permissions".  For an example, see solr_conf/conf/solrconfig.xml.
+
+* If you use solr field names that don't match the default field names used in Blacklight::AccessControls::Config for the "permissions" handler, you'll need to create a Rails initializer to set those values in Blacklight::AccessControls::Config.
+
+h3. Run the generator
+
+<pre>
+rails generate blacklight:access_controls
+</pre>
+
+
+h2. Using Access Controls
+
+Some notes about using blacklight-access_controls within your Blacklight app:
+
+* You can grant access to a record to specific users or groups by adding them to the correct fields in the solr document.  For example, discover_access_group_ssim: "public" or read_access_person_ssim: "frodo@example.com".
+
+* The gem expects user.groups to return a list of groups that the user belongs to.  By default, all users belong to a group called "public", and all logged-in users belong to a group called "registered".
+
+* If you want a record to be readable by the public, you need to add "public" to the "read_access_group_ssim" field in the solr document, or if you want discover-only access, add "public" to "discover_access_group_ssim".  (Discover-only means that the user can see that the record exists in a catalog search, but won't be able to view the record itself.)
+
+
+h2. Developer Notes
+
+This section contains information about working on the blacklight-access_controls gem itself.
+
+h3. Set up Solr
+
+<pre>
+$ bundle exec rake solr:clean
+$ bundle exec rake solr:config
+$ bundle exec rake solr:start
+$ bundle exec rake solr:stop
+</pre>
+
+h3. Generate a Rails test app
+
+<pre>
+$ bundle exec rake engine_cart:clean
+$ bundle exec rake engine_cart:generate
+</pre>
+
+h3. Run the test suite
+
+<pre>
+$ bundle exec rake engine_cart:clean
+$ bundle exec rake engine_cart:generate
+$ bundle exec rake solr:spec
+</pre>
+
+h3. Run the Rails server in development mode
+
+<pre>
+$ bundle exec rake solr:start
+$ bundle exec rake engine_cart:generate
+$ bundle exec rake engine_cart:server
+</pre>
+

data/Rakefile

@@ -0,0 +1,47 @@
+#!/usr/bin/env rake
+
+require 'solr_wrapper'
+
+SOLR_OPTIONS = {
+    verbose: true,
+    cloud: false,
+    port: '8983',
+    version: '5.3.1',
+    instance_dir: 'solr',
+    download_dir: 'tmp'
+}
+
+SolrWrapper.default_instance_options = SOLR_OPTIONS
+
+require 'solr_wrapper/rake_task'
+require 'engine_cart/rake_task'
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => 'solr:spec'
+
+def solr_config_dir
+  File.join(File.expand_path(File.dirname(__FILE__)), "solr_conf", "conf")
+end
+
+namespace :solr do
+
+  desc 'Configure solr cores'
+  task :config do
+    SolrWrapper.wrap do |solr|
+      core = solr.create(name: 'development', dir: solr_config_dir)
+      core = solr.create(name: 'test', dir: solr_config_dir)
+    end
+  end
+
+  desc "Run test suite (with solr wrapper)"
+  task :spec do
+    SolrWrapper.wrap do |solr|
+      solr.with_collection(name:'test', dir: solr_config_dir) do |collection_name|
+        Rake::Task['spec'].invoke
+      end
+    end
+  end
+
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/blacklight-access_controls.gemspec

@@ -0,0 +1,29 @@
+version = File.read(File.expand_path("../VERSION", __FILE__)).strip
+
+Gem::Specification.new do |gem|
+  gem.name          = "blacklight-access_controls"
+
+  gem.description   = %q{Access controls for blacklight-based applications}
+  gem.summary       = %q{Access controls for blacklight-based applications}
+  gem.homepage      = "https://github.com/projectblacklight/blacklight-access_controls"
+  gem.email         = ["blacklight-development@googlegroups.com"]
+  gem.authors       = ["Chris Beer", "Justin Coyne", "Matt Zumwalt", "Valerie Maher"]
+
+  gem.files         = `git ls-files`.split($\)
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = ["lib"]
+  gem.version       = version
+  gem.license       = "APACHE2"
+
+  gem.required_ruby_version = '>= 1.9.3'
+
+  gem.add_dependency 'cancancan', '~> 1.8'
+  gem.add_dependency "blacklight", '~> 5.16'
+
+  gem.add_development_dependency "rake", '~> 10.1'
+  gem.add_development_dependency 'rspec', '~> 3.1'
+  gem.add_development_dependency "engine_cart", "~> 0.8"
+  gem.add_development_dependency "solr_wrapper"
+  gem.add_development_dependency "factory_girl_rails", "~> 4.0"
+  gem.add_development_dependency "database_cleaner"
+end

data/lib/blacklight-access_controls.rb

@@ -0,0 +1,23 @@
+require 'rails'
+require 'cancan'
+require 'blacklight'
+require 'blacklight/access_controls'
+
+module Blacklight::AccessControls
+  extend ActiveSupport::Autoload
+
+  class << self
+    def configure
+      @config ||= Config.new
+      yield @config if block_given?
+      @config
+    end
+    alias :config :configure
+  end
+
+  # This error is raised when a user isn't allowed to access a given controller action.
+  # This usually happens within a call to Enforcement#enforce_access_controls but can be
+  # raised manually.
+  class AccessDenied < ::CanCan::AccessDenied; end
+
+end

data/lib/blacklight/access_controls.rb

@@ -0,0 +1,14 @@
+module Blacklight
+  module AccessControls
+    extend ActiveSupport::Autoload
+
+    autoload :Config
+    autoload :User
+    autoload :PermissionsQuery
+    autoload :PermissionsCache
+    autoload :PermissionsSolrDocument
+    autoload :Ability
+    autoload :Enforcement
+    autoload :Catalog
+  end
+end

data/lib/blacklight/access_controls/ability.rb

@@ -0,0 +1,148 @@
+require 'cancan'
+
+module Blacklight
+  module AccessControls
+    module Ability
+      extend ActiveSupport::Concern
+
+      included do
+        include CanCan::Ability
+        include Blacklight::AccessControls::PermissionsQuery
+
+        # Once you include this module, you can add custom
+        # permission methods to ability_logic, like so:
+        # self.ability_logic +=[:setup_my_permissions]
+        class_attribute :ability_logic
+        self.ability_logic = [:discover_permissions, :read_permissions]
+      end
+
+      def initialize(user, options={})
+        @current_user = user || guest_user
+        @options = options
+        @cache = Blacklight::AccessControls::PermissionsCache.new
+        grant_permissions
+      end
+
+      attr_reader :current_user, :options, :cache
+
+      def self.user_class
+        Blacklight::AccessControls.config.user_model.constantize
+      end
+
+      # A user who isn't logged in
+      def guest_user
+        Blacklight::AccessControls::Ability.user_class.new
+      end
+
+      def grant_permissions
+        Rails.logger.debug("Usergroups are " + user_groups.inspect)
+        self.ability_logic.each do |method|
+          send(method)
+        end
+      end
+
+      def discover_permissions
+        can :discover, String do |id|
+          test_discover(id)
+        end
+
+        can :discover, SolrDocument do |obj|
+          cache.put(obj.id, obj)
+          test_discover(obj.id)
+        end
+      end
+
+      def read_permissions
+        can :read, String do |id|
+          test_read(id)
+        end
+
+        can :read, SolrDocument do |obj|
+          cache.put(obj.id, obj)
+          test_read(obj.id)
+        end
+      end
+
+      def test_discover(id)
+        Rails.logger.debug("[CANCAN] Checking discover permissions for user: #{current_user.user_key} with groups: #{user_groups.inspect}")
+        group_intersection = user_groups & discover_groups(id)
+        !group_intersection.empty? || discover_users(id).include?(current_user.user_key)
+      end
+
+      def test_read(id)
+        Rails.logger.debug("[CANCAN] Checking read permissions for user: #{current_user.user_key} with groups: #{user_groups.inspect}")
+        group_intersection = user_groups & read_groups(id)
+        !group_intersection.empty? || read_users(id).include?(current_user.user_key)
+      end
+
+      # You can override this method if you are using a different AuthZ (such as LDAP)
+      def user_groups
+        return @user_groups if @user_groups
+
+        @user_groups = default_user_groups
+        @user_groups |= current_user.groups if current_user.respond_to? :groups
+        @user_groups |= ['registered'] unless current_user.new_record?
+        @user_groups
+      end
+
+      # Everyone is automatically a member of group 'public'
+      def default_user_groups
+        ['public']
+      end
+
+      # read implies discover, so discover_groups is the union of read and discover groups
+      def discover_groups(id)
+        doc = permissions_doc(id)
+        return [] if doc.nil?
+        dg = read_groups(id) | (doc[self.class.discover_group_field] || [])
+        Rails.logger.debug("[CANCAN] discover_groups: #{dg.inspect}")
+        dg
+      end
+
+      # read implies discover, so discover_users is the union of read and discover users
+      def discover_users(id)
+        doc = permissions_doc(id)
+        return [] if doc.nil?
+        dp = read_users(id) | (doc[self.class.discover_user_field] || [])
+        Rails.logger.debug("[CANCAN] discover_users: #{dp.inspect}")
+        dp
+      end
+
+      def read_groups(id)
+        doc = permissions_doc(id)
+        return [] if doc.nil?
+        rg = Array(doc[self.class.read_group_field])
+        Rails.logger.debug("[CANCAN] read_groups: #{rg.inspect}")
+        rg
+      end
+
+      def read_users(id)
+        doc = permissions_doc(id)
+        return [] if doc.nil?
+        rp = Array(doc[self.class.read_user_field])
+        Rails.logger.debug("[CANCAN] read_users: #{rp.inspect}")
+        rp
+      end
+
+      module ClassMethods
+
+        def discover_group_field
+          Blacklight::AccessControls.config.discover_group_field
+        end
+
+        def discover_user_field
+          Blacklight::AccessControls.config.discover_user_field
+        end
+
+        def read_group_field
+          Blacklight::AccessControls.config.read_group_field
+        end
+
+        def read_user_field
+          Blacklight::AccessControls.config.read_user_field
+        end
+
+      end
+    end
+  end
+end

data/lib/blacklight/access_controls/catalog.rb

@@ -0,0 +1,27 @@
+# This is behavior for the catalog controller.
+
+module Blacklight
+  module AccessControls
+    module Catalog
+      extend ActiveSupport::Concern
+
+      # Override blacklight to produce a search_builder that has
+      # the current ability in context
+      def search_builder processor_chain = search_params_logic
+        super(true).tap { |builder| builder.current_ability = current_ability }
+      end 
+
+      # Controller "before" filter for enforcing access controls
+      # on show actions.
+      # @param [Hash] opts (optional, not currently used)
+      def enforce_show_permissions(opts={})
+        permissions = current_ability.permissions_doc(params[:id])
+        unless can? :read, permissions
+          raise Blacklight::AccessControls::AccessDenied.new("You do not have sufficient access privileges to read this document, which has been marked private.", :read, params[:id])
+        end
+        permissions
+      end
+
+    end
+  end
+end

data/lib/blacklight/access_controls/config.rb

@@ -0,0 +1,39 @@
+module Blacklight
+  module AccessControls
+    class Config
+
+      def initialize
+        @user_model = default_user_model
+        @discover_group_field = default_discover_group_field
+        @discover_user_field = default_discover_user_field
+        @read_group_field = default_read_group_field
+        @read_user_field = default_read_user_field
+      end
+
+      attr_accessor :user_model
+      attr_accessor :discover_group_field, :discover_user_field
+      attr_accessor :read_group_field, :read_user_field
+
+      def default_user_model
+        'User'
+      end
+
+      def default_discover_group_field
+        "discover_access_group_ssim"
+      end
+
+      def default_discover_user_field
+        "discover_access_person_ssim"
+      end
+
+      def default_read_group_field
+        "read_access_group_ssim"
+      end
+
+      def default_read_user_field
+        "read_access_person_ssim"
+      end
+
+    end
+  end
+end