h1. hydra-access-controls

The hydra-access-controls gem provides access controls models and functionality for Hydra Heads.  See the "hydra-head":http://github.com/projecthydra/hydra-head gem and the "Hydra Project website":http://projecthydra.org for more info.

Some background information is available on the wiki at https://github.com/projecthydra/hydra-head/wiki/Access-Controls

h2. Installation

The easiest way to make your code use this gem is to run the hydra generator that comes with the hydra-head gem.  That will set up everything you need:

* adds _include Hydra::User_ to your User class
* modifies the filters in your CatalogController class to inject access controls into solr queries
* adds the YAML files that are used by the default RoleMapper class
* adds section to hydra_config initializer that sets names used to look up enforcement info in solr (see "Modifying solr field names for enforcement" below)

h2. Usage

h3. Enforcing Hydra-based Access Controls using CanCan and Hydra::Ability

They hydra generator handles part of this for you - it sets up the CatalogController (Blacklight's main controller for searches) to do gated discovery for you.

Beyond enabling gated discovery, *everything is done using "CanCan":https://github.com/ryanb/cancan*.  For more information on CanCan, how to use it, and how to define access controls policies (aka "abilities":https://github.com/ryanb/cancan/wiki/Defining-Abilities), refer to the "CanCan documentation":https://github.com/ryanb/cancan/blob/master/README.rdoc.

Within your CanCan ability definitions (usually ability.rb), if you include the "Hydra::Ability":https://github.com/projecthydra/hydra-head/blob/master/hydra-access-controls/lib/hydra/ability.rb module, you will have :read and :edit permissions defined for you, along with some convenience methods that help you evaluate permssions against info in the rightsMetadata. *Note*: the Hydra rails generator includes this module into your ability.rb for you!

In your custom controllers, you need to tell them to enforce access controls using "CanCan":https://github.com/ryanb/cancan.  There are a number of ways to do this.  The easiest way is to use the cancan "controller action":https://github.com/ryanb/cancan/wiki/Authorizing-Controller-Actions 'load_and_authorize_resource', however on show and edit, this also causes a load the resource from fedora, which you may want to avoid.  If you want to authorize from solr, you ought to be able to call the cancan methods `authorize!` or `can?` which just checks the solr permissions handler. 

Examples of using authorize! and can? in controller methods:

<pre>
def show
  authorize! :show, params[:id] # raises CanCan::Access denied if they don't have permission
  ...
end

def edit
  if can? :edit, params[:id]
    ## User is authorized
  else
    ## not authorized
  end
end
</pre>

h3. Modifying solr field names for enforcement

Hydra uses its own set of default solr field names to track rights-related metadata in solr.  If you want to use your own field names, you can change them in your Hydra config.  You will also have to modify the permissions response handler in your solrconfig.xml to return those fields.

Note: The hydra generator sets up the defaults for you in this file.  You only need to edit it if you want to change the field names.

In config/initializers/hydra_config.rb

<pre>
  Hydra.configure(:shared) do |config|
    # ... other stuff ...
    config[:permissions] = {
      :discover => {:group =>"discover_access_group_t", :individual=>"discover_access_person_t"},
      :read => {:group =>"read_access_group_t", :individual=>"read_access_person_t"},
      :edit => {:group =>"edit_access_group_t", :individual=>"edit_access_person_t"},
      :owner => "depositor_t",
      :embargo_release_date => "embargo_release_date_dt"
    }
    config[:permissions][:inheritable] = {
      :discover => {:group =>"inheritable_discover_access_group_t", :individual=>"inheritable_discover_access_person_t"},
      :read => {:group =>"inheritable_read_access_group_t", :individual=>"inheritable_read_access_person_t"},
      :edit => {:group =>"inheritable_edit_access_group_t", :individual=>"inheritable_edit_access_person_t"},
      :owner => "inheritable_depositor_t",
      :embargo_release_date => "inheritable_embargo_release_date_dt"
    }
  end
</pre>

h3. Policy-based Enforcement (or Collecton-level enforcement)

If you have Policy-based enforcement enabled, then objects will inherit extra GRANT permissions from AdminPolicy objects they are linked to with an isGovernedBy RDF relationship (stored in solr as _is_governed_by_s__ field).  This allows you to grant discover/read/edit access for a whole set of objects by changing the policy they are governed by.

AdminPolicy objects store their inheritable rightsMetadata in a datastream called defaultRights.  This datastream uses the regular Hydra rightsMetadata schema.  Each AdminPolicy object also has its own rightsMetadata datasream, like all other Hydra assets, which specifies who is able to _edit_ the Policy or _use_ it (associate it with objects).

Object-level permissions and Policy-level permissions are combined to produce the list of Individuals & Groups who have access to the object.  This means that if _either_ the object's rightsMetadata or the Policy's defaultRights grants access to an Individual or Group, that access will be allowed.

* Currently, an asset can have only one Policy associated with it -- you can't associate objects with multiple policies

To turn on Policy-based enforcement, 

* include the Hydra::PolicyAwareAbility module in your Ability class (Make sure to include it _after_ Hydra::Ability because it overrides some of the methods provided by that module.)
* include the Hydra::PolicyAwareAccessControlsEnforcement module into any appropriate Controllers (or into ApplicationController)
 

Example app/models/ability.rb

<pre>
  # Allows you to use CanCan to control access to Models
  require 'cancan'
  class Ability
    include CanCan::Ability
    include Hydra::Ability
    include Hydra::PolicyAwareAbility
  end
</pre>

Example app/controllers/catalog_controller.rb

<pre>
  class CatalogController < ApplicationController  

    include Blacklight::Catalog
    include Hydra::Controller::ControllerBehavior
    include Hydra::PolicyAwareAccessControlsEnforcement
    
    # ...
  end
</pre>



h2. Contributing

1. Fork it
2. Create your feature branch (`git checkout -b my-new-feature`)
3. Commit your changes (`git commit -am 'Added some feature'`)
4. Push to the branch (`git push origin my-new-feature`)
5. Create new Pull Request

h2. Testing

    $ git submodule init
    $ rake jetty:config
    $ rake jetty:start
    $ rake spec