ae_declarative_authorization 0.12.1 → 1.0.0

data/README.rdoc

@@ -1,597 +0,0 @@
-= Declarative Authorization
-
-The declarative authorization plugin offers an authorization mechanism inspired
-by _RBAC_.  The most notable distinction to other authorization plugins is the
-declarative approach.  That is, authorization rules are not defined
-programmatically in between business logic but in an authorization configuration.
-
-With programmatic authorization rules, the developer needs to specify which roles are
-allowed to access a specific controller action or a part of a view, which is
-not DRY.  With a growing application code base roles' permissions often
-change and new roles are introduced. Then, at several places of the source code
-the changes have to be implemented, possibly leading to omissions and thus hard
-to find errors.  In these cases, a declarative approach as offered by decl_auth
-increases the development and maintenance efficiency.
-
-
-Plugin features
-* Authorization at controller action level
-* Authorization helpers for Views
-* Authorization at model level
-  * Authorize CRUD (Create, Read, Update, Delete) activities
-  * Query rewriting to automatically only fetch authorized records
-* DSL for specifying Authorization rules in an authorization configuration
-* Support for Rails 4 and 5
-
-
-Requirements
-* An authentication mechanism
-  * User object in Controller#current_user
-  * (For model security) Setting Authorization.current_user
-* User objects need to respond to a method :role_symbols that returns an
-  array of role symbols
-See below for installation instructions.
-
-
-There is a decl_auth screencast by Ryan Bates, nicely introducing the main concepts:
-http://railscasts.com/episodes/188-declarative-authorization
-
-
-= Quick Start
-
-=== Installer
-
-Declarative Authorization comes with an installer to make setup easy.
-
-First, include declarative_authorization in your gemfile.
-
-    #! Gemfile
-    gem 'declarative_authorization'
-
-Next, bundle and install.
-
-    $ bundle
-    $ rails g authorization:install [UserModel=User] [field:type field:type ...] [--create-user --commit --user-belongs-to-role]
-
-This installer will create a Role model, an admin and a user role, and set a
-has_and_belongs_to_many relationship between the User model and the Role model.
-It will also add a +role_symbols+ method to the user model to meet
-declarative_authorization's requirements.  The default User model is User.  You can override this by simply typing the name of a model as above.
-
-You can create the model with the fields provided by using the +--create-user+ option.
-
-The +--commit+ option will run +rake db:migrate+ and +rake db:seed+.
-
-The +--user-belongs-to-role+ option will set up a one-to-many relationship between Users and Roles.
-That is, each user has a role_id column and can only have one role.  Role inheritance can be used
-in authorization rules.
-
-Finally, the installer also copies default authorization rules, as below.
-
-=== Generate Authorization Rules
-
-To copy a default set of authorization rules which includes CRUD priveleges, run:
-
-    $ rails g authorization:rules
-
-This command will copy the following to +config/authorization_rules.rb+.  Remember
-to implement the requirements of this gem as described in the Installation section
-at the end of this README if you do not use the above installer.
-
-    authorization do
-      role :guest do
-        # add permissions for guests here, e.g.
-        # has_permission_on :conferences, :to => :read
-      end
-
-      # permissions on other roles, such as
-      # role :admin do
-      #   has_permission_on :conferences, :to => :manage
-      # end
-      # role :user do
-      #   has_permission_on :conferences, :to => [:read, :create]
-      #   has_permission_on :conferences, :to => [:update, :delete] do
-      #     if_attribute :user_id => is {user.id}
-      #   end
-      # end
-      # See the readme or GitHub for more examples
-    end
-
-    privileges do
-      # default privilege hierarchies to facilitate RESTful Rails apps
-      privilege :manage, :includes => [:create, :read, :update, :delete]
-      privilege :create, :includes => :new
-      privilege :read, :includes => [:index, :show]
-      privilege :update, :includes => :edit
-      privilege :delete, :includes => :destroy
-    end
-
-=== Controller Authorization
-
-For RESTful controllers, add +filter_resource_access+:
-
-    class MyRestfulController < ApplicationController
-      filter_resource_access
-      ...
-    end
-
-For a non-RESTful controller, you can use +filter_access_to+:
-
-    class MyOtherController < ApplicationController
-      filter_access_to :all
-      # or a group: filter_access_to [:action1, :action2]
-      ...
-    end
-
-=== View Authorization
-
-Declarative Authorization will use +current_user+ to check authorization.
-
-    <%= link_to 'Edit Post', edit_post_path(@post) if permitted_to? :update, @post %>
-
-
-= Authorization Data Model
-
- ----- App domain ----|-------- Authorization conf ---------|------- App domain ------
-
-                       includes                   includes
-                        .--.                        .---.
-                        |  v                        |   v
-  .------.  can_play  .------.  has_permission  .------------.  requires  .----------.
-  | User |----------->| Role |----------------->| Permission |<-----------| Activity |
-  '------' *        * '------' *              * '------------' 1        * '----------'
-                                                      |
-                                              .-------+------.
-                                           1 /        | 1     \ *
-                                 .-----------.   .---------.  .-----------.
-                                 | Privilege |   | Context |  | Attribute |
-                                 '-----------'   '---------'  '-----------'
-
-In the application domain, each *User* may be assigned to *Roles* that should
-define the users' job in the application, such as _Administrator_.  On the
-right-hand side of this diagram, application developers specify which *Permissions*
-are necessary for users to perform activities, such as calling a controller action,
-viewing parts of a View or acting on records in the database.  Note that
-Permissions consist of an *Privilege* that is to be performed, such as _read_,
-and a *Context* in that the Operation takes place, such as _companies_.
-
-In the authorization configuration, Permissions are assigned to Roles and Role
-and Permission hierarchies are defined.  *Attributes* may be employed to allow
-authorization according to dynamic information about the context and the
-current user, e.g. "only allow access on employees that belong to the
-current user's branch."
-
-
-= Examples
-
-A fully functional example application can be found at
-http://github.com/stffn/decl_auth_demo_app
-
-== Controller
-
-If authentication is in place, there are two ways to enable user-specific
-access control on controller actions.  For resource controllers, which more
-or less follow the CRUD pattern, +filter_resource_access+ is the simplest
-approach.  It sets up instance variables in before filters and calls
-filter_access_to with the appropriate parameters to protect the CRUD methods.
-
-    class EmployeesController < ApplicationController
-      filter_resource_access
-      ...
-    end
-
-See Authorization::Controller::DSL for options on
-nested resources and custom member and collection actions.
-
-By default, declarative_authorization will enable filter_resource_access compatibility with strong_parameters in Rails 4.  If you want to disable this behavior, you can use the +:strong_parameters+ option.
-
-    class EmployeesController < ApplicationController
-      filter_resource_access :strong_parameters => false
-      ...
-    end
-
-Simalarly, you can use +:strong_parameters => true+ if you are using strong_parameters in Rails 3.
-
-If you prefer less magic or your controller has no resemblance with the resource
-controllers, directly calling filter_access_to may be the better option.  Examples
-are given in the following.  E.g. the privilege index users is required for
-action index.  This works as a first default configuration for RESTful
-controllers, with these privileges easily handled in the authorization
-configuration, which will be described below.
-
-    class EmployeesController < ApplicationController
-      filter_access_to :all
-      def index
-        ...
-      end
-      ...
-    end
-
-When custom actions are added to such a controller, it helps to define more
-clearly which privileges are the respective requirements.  That is when the
-filter_access_to call may become more verbose:
-
-    class EmployeesController < ApplicationController
-      filter_access_to :all
-      # this one would be included in :all, but :read seems to be
-      # a more suitable privilege than :auto_complete_for_user_name
-      filter_access_to :auto_complete_for_employee_name, :require => :read
-      def auto_complete_for_employee_name
-        ...
-      end
-      ...
-    end
-
-For some actions it might be necessary to check certain attributes of the
-object the action is to be acting on.  Then, the object needs to be loaded
-before the action's access control is evaluated.  On the other hand, some actions
-might prefer the authorization to ignore specific attribute checks as the object is
-unknown at checking time, so attribute checks and thus automatic loading of
-objects needs to be enabled explicitly.
-
-    class EmployeesController < ApplicationController
-      filter_access_to :update, :attribute_check => true
-      def update
-        # @employee is already loaded from param[:id] because of :attribute_check
-      end
-    end
-
-You can provide the needed object through before_actions.  This way, you have
-full control over the object that the conditions are checked against.  Just make
-sure, your before_actions occur before any of the filter_access_to calls.
-
-    class EmployeesController < ApplicationController
-      before_action :new_employee_from_params, :only => :create
-      before_action :new_employee, :only => [:index, :new]
-      filter_access_to :all, :attribute_check => true
-
-      def create
-        @employee.save!
-      end
-
-      protected
-      def new_employee_from_params
-        @employee = Employee.new(params[:employee])
-      end
-    end
-
-If the access is denied, a +permission_denied+ method is called on the
-current_controller, if defined, and the issue is logged.
-For further customization of the filters and object loading, have a look at
-the complete API documentation of filter_access_to in
-Authorization::Controller::DSL.
-
-
-== Views
-
-In views, a simple permitted_to? helper makes showing blocks according to the
-current user's privileges easy:
-
-    <% permitted_to? :create, :employees do %>
-    <%= link_to 'New', new_employee_path %>
-    <% end %>
-
-Only giving a symbol :employees as context prevents any checks of attributes
-as there is no object to check against.  For example, in case of nested resources
-a new object may come in handy:
-
-    <% permitted_to? :create, Branch.new(:company => @company) do
-            # or @company.branches.new
-            # or even @company.branches %>
-    <%= link_to 'New', new_company_branch_path(@company) %>
-    <% end %>
-
-Lists are straight-forward:
-
-    <% for employee in @employees %>
-    <%= link_to 'Edit', edit_employee_path(employee) if permitted_to? :update, employee %>
-    <% end %>
-
-See also Authorization::AuthorizationHelper.
-
-
-== Models
-
-There are two distinct features for model security built into this plugin:
-authorizing CRUD operations on objects as well as query rewriting to limit
-results according to certain privileges.
-
-See also Authorization::AuthorizationInModel.
-
-=== Model security for CRUD operations
-To activate model security, all it takes is an explicit enabling for each
-model that model security should be enforced on, i.e.
-
-    class Employee < ActiveRecord::Base
-      using_access_control
-      ...
-    end
-
-Thus,
-    Employee.create(...)
-fails, if the current user is not allowed to :create :employees according
-to the authorization rules.  For the application to find out about what
-happened if an operation is denied, the filters throw
-Authorization::NotAuthorized exceptions.
-
-As access control on read are costly, with possibly lots of objects being
-loaded at a time in one query, checks on read need to be activated explicitly by
-adding the :include_read option.
-
-=== Query rewriting through named scopes
-When retrieving large sets of records from databases, any authorization needs
-to be integrated into the query in order to prevent inefficient filtering
-afterwards and to use LIMIT and OFFSET in SQL statements.  To keep authorization
-rules out of the source code, this plugin offers query rewriting mechanisms
-through named scopes.  Thus,
-
-    Employee.with_permissions_to(:read)
-
-returns all employee records that the current user is authorized to read.  In
-addition, just like normal named scopes, query rewriting may be chained with
-the usual find method:
-
-    Employee.with_permissions_to(:read).find(:all, :conditions => ...)
-
-If the current user is completely missing the permissions, an
-Authorization::NotAuthorized exception is raised.  Through
-Model.obligation_conditions, application developers may retrieve
-the conditions for manual rewrites.
-
-
-== Authorization Rules
-
-Authorization rules are defined in config/authorization_rules.rb
-(Or redefine rules files path via +Authorization::AUTH_DSL_FILES+).  E.g.
-
-    authorization do
-      role :admin do
-        has_permission_on :employees, :to => [:create, :read, :update, :delete]
-      end
-    end
-
-There is a default role :+guest+ that is used if a request is not associated
-with any user or with a user without any roles.  So, if your application has
-public pages, :+guest+ can be used to allow access for users that are not
-logged in.  All other roles are application defined and need to be associated
-with users by the application.
-
-If you need to change the default role, you can do so by adding an initializer
-that contains the following statement:
-
-    Authorization.default_role = :anonymous
-
-Privileges, such as :create, may be put into hierarchies to simplify
-maintenance.  So the example above has the same meaning as
-
-    authorization do
-      role :admin do
-        has_permission_on :employees, :to => :manage
-      end
-    end
-
-    privileges do
-      privilege :manage do
-        includes :create, :read, :update, :delete
-      end
-    end
-
-Privilege hierarchies may be context-specific, e.g. applicable to :employees.
-
-    privileges do
-      privilege :manage, :employees, :includes => :increase_salary
-    end
-
-For more complex use cases, authorizations need to be based on attributes.  Note
-that you then also need to set :attribute_check => true in controllers for filter_access_to.
-E.g. if a branch admin should manage only employees of his branch (see
-Authorization::Reader in the API docs for a full list of available operators):
-
-    authorization do
-      role :branch_admin do
-        has_permission_on :employees do
-          to :manage
-          # user refers to the current_user when evaluating
-          if_attribute :branch => is {user.branch}
-        end
-      end
-    end
-
-To reduce redundancy in has_permission_on blocks, a rule may depend on
-permissions on associated objects:
-
-    authorization do
-      role :branch_admin do
-        has_permission_on :branches, :to => :manage do
-          if_attribute :managers => contains {user}
-        end
-
-        has_permission_on :employees, :to => :manage do
-          if_permitted_to :manage, :branch
-          # instead of
-          #if_attribute :branch => {:managers => contains {user}}
-        end
-      end
-    end
-
-Lastly, not only privileges may be organized in a hierarchy but roles as well.
-Here, project manager inherit the permissions of employees.
-
-      role :project_manager do
-        includes :employee
-      end
-
-See also Authorization::Reader.
-
-== Testing
-
-declarative_authorization provides a few helpers to ease the testing with
-authorization in mind.
-
-In your test_helper.rb, to enable the helpers add
-
-    require 'declarative_authorization/maintenance'
-
-    class Test::Unit::TestCase
-      include Authorization::TestHelper
-      ...
-    end
-
-For using the test helpers with RSpec, just add the following lines to your
-spec_helper.rb (somewhere after require 'spec/rails'):
-
-    require 'declarative_authorization/maintenance'
-    include Authorization::TestHelper
-
-Now, in unit tests, you may deactivate authorization if needed e.g. for test
-setup and assume certain identities for tests:
-
-    class EmployeeTest < ActiveSupport::TestCase
-      def test_should_read
-        without_access_control do
-          Employee.create(...)
-        end
-        assert_nothing_raised do
-          with_user(admin) do
-            Employee.find(:first)
-          end
-        end
-      end
-    end
-
-Or, with RSpec, it would work like this:
-
-  describe Employee do
-    it "should read" do
-      without_access_control do
-        Employee.create(...)
-      end
-      with_user(admin) do
-        Employee.find(:first)
-      end
-    end
-  end
-
-In functional tests, get, posts, etc. may be tested in the name of certain users:
-
-    get_with admin, :index
-    post_with admin, :update, :employee => {...}
-
-See Authorization::TestHelper for more information.
-
-
-= Installation of declarative_authorization
-
-One of three options to install the plugin:
-* Install by Gem:  Add to your environment.rb in the initializer block:
-    config.gem "declarative_authorization"
-  Note: you need gemcutter support in place, i.e. call
-    gem install gemcutter
-    gem tumble
-  And call from your application's root directory
-    rake gems:install
-* Alternatively, in Rails 2, to install from github, execute in your application's root directory
-    cd vendor/plugins && git clone git://github.com/stffn/declarative_authorization.git
-
-Then,
-* provide the requirements as noted below,
-* create a basic config/authorization_rules.rb--you might want to take the
-  provided example authorization_rules.dist.rb in the plugin root as a starting
-  point,
-* add +filter_access_to+, +permitted_to+? and model security as needed.
-
-== Providing the Plugin's Requirements
-The requirements are
-* Rails >= 4.2.5.2 and Ruby >= 2.3.3
-* An authentication mechanism
-* A user object returned by Controller#current_user
-* An array of role symbols returned by User#role_symbols
-* (For model security) Setting Authorization.current_user to the request's user
-
-Of the various ways to provide these requirements, here is one way employing
-restful_authentication.
-
-* Install restful_authentication
-   cd vendor/plugins && git clone git://github.com/technoweenie/restful-authentication.git restful_authentication
-   cd ../.. && ruby script/generate authenticated user sessions
-* Move "include AuthenticatedSystem" to ApplicationController
-* Add +filter_access_to+ calls as described above.
-* If you'd like to use model security, add a before_action that sets the user
-  globally to your ApplicationController.  This is thread-safe.
-   before_action :set_current_user
-   protected
-   def set_current_user
-     Authorization.current_user = current_user
-   end
-
-* Add roles field to the User model through a :+has_many+ association
-  (this is just one possible approach; you could just as easily use
-  :+has_many+ :+through+ or a serialized roles array):
-  * create a migration for table roles
-     class CreateRoles < ActiveRecord::Migration
-       def self.up
-         create_table "roles" do |t|
-           t.column :title, :string
-           t.references :user
-         end
-       end
-
-       def self.down
-         drop_table "roles"
-       end
-     end
-
-  * create a model Role,
-     class Role < ActiveRecord::Base
-       belongs_to :user
-     end
-
-  * add +has_many+ :+roles+ to the User model and a roles method that returns the roles
-    as an Array of Symbols, e.g.
-     class User < ActiveRecord::Base
-       has_many :roles
-       def role_symbols
-         (roles || []).map {|r| r.title.to_sym}
-       end
-     end
-
-  * add roles to your User objects using e.g.
-     user.roles.create(:title => "admin")
-
-Note:  If you choose to generate an Account model for restful_authentication
-instead of a User model as described above, you have to customize the
-examples and create a ApplicationController#current_user method.
-
-
-== Debugging Authorization
-
-Currently, the main means of debugging authorization decisions is logging and
-exceptions.  Denied access to actions is logged to +warn+ or +info+, including
-some hints about what went wrong.
-
-All bang methods throw exceptions which may be used to retrieve more
-information about a denied access than a Boolean value.
-
-
-= Help and Contact
-
-We have an issue tracker[http://github.com/appfolio/ae_declarative_authorization/issues]
-for bugs and feature requests.
-You are very welcome to contribute. Just fork the git repository and send a pull request.
-
-
-= Contributors
-
-Thanks to John Joseph Bachir, Dennis Blöte, Eike Carls, Damian Caruso, Kai Chen, Erik Dahlstrand,
-Jeroen van Dijk, Alexander Dobriakov, Sebastian Dyck, Ari Epstein, Jeremy Friesen,
-Tim Harper, John Hawthorn, hollownest, Daniel Kristensen, Jeremy Kleindl, Joel Kociolek,
-Benjamin ter Kuile, Brad Langhorst, Brian Langenfeld,
-Georg Ledermann, Geoff Longman, Olly Lylo, Mark Mansour, Thomas Maurer, Kevin Moore,
-Tyler Pickett, Edward Rudd, Sharagoz,
-TJ Singleton, Mike Vincent, Joel Westerberg
-
-
-= License
-
-Copyright (c) 2008 Steffen Bartsch, TZI, Universität Bremen, Germany
-released under the MIT license

data/Rakefile

@@ -1,35 +0,0 @@
-require 'rubygems'
-require 'bundler'
-
-begin
-  Bundler.setup(:default, :development)
-rescue Bundler::BundlerError => e
-  $stderr.puts e.message
-  $stderr.puts "Run `bundle install` to install missing gems"
-  exit e.status_code
-end
-
-require 'rake'
-require 'rake/testtask'
-require 'rdoc/task'
-
-require 'bundler/gem_tasks'
-
-task default: :test
-
-Rake::TestTask.new(:test) do |t|
-  t.libs << 'lib' << 'test'
-  t.pattern = 'test/**/*_test.rb'
-  t.verbose = true
-  t.warning = false
-end
-
-Rake::RDocTask.new(:rdoc) do |rdoc|
-  rdoc.rdoc_dir = 'rdoc'
-  rdoc.title    = 'Authorization'
-  rdoc.options << '--line-numbers' << '--inline-source'
-  rdoc.options << '--charset' << 'utf-8'
-  rdoc.rdoc_files.include('README.rdoc')
-  rdoc.rdoc_files.include('CHANGELOG')
-  rdoc.rdoc_files.include('lib/**/*.rb')
-end

data/authorization_rules.dist.rb

@@ -1,20 +0,0 @@
-authorization do
-  role :guest do
-    # add permissions for guests here, e.g.
-    #has_permission_on :conferences, :to => :read
-  end
-  
-  # permissions on other roles, such as
-  #role :admin do
-  #  has_permission_on :conferences, :to => :manage
-  #end
-end
-
-privileges do
-  # default privilege hierarchies to facilitate RESTful Rails apps
-  privilege :manage, :includes => [:create, :read, :update, :delete]
-  privilege :read, :includes => [:index, :show]
-  privilege :create, :includes => :new
-  privilege :update, :includes => :edit
-  privilege :delete, :includes => :destroy
-end

data/init.rb

@@ -1,5 +0,0 @@
-begin
-  require File.join(File.dirname(__FILE__), 'lib', 'declarative_authorization') # From here
-rescue LoadError
-  require 'declarative_authorization' # From gem
-end