ae_declarative_authorization 1.5.0 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5e11a2b5e7153658db82ba4882cf04c2dc4f7e1ec22d21908365af7a860de466
-  data.tar.gz: 01cc82ce6c960d11af9199fa142334de736b7957fd8b30dd81a95822964bca64
+  metadata.gz: 793630999c148ddae30f3f0da1634b5a332f5b3d2674598aec7899050d19b6be
+  data.tar.gz: 614ac02d1633fc589c6a456a979f642bbd3d4bc0350b3458c024c02feef795da
 SHA512:
-  metadata.gz: c9c061d3055fdf6d84d81699a53e653e67bb42f6162dd4c27eac31e473d145e9cb14268cbe886114ba781428aafd179be2ea9449ba7b9e79ddbc4c2dfd3f6734
-  data.tar.gz: 708873a0ad5ab828bb8615d211b41d5a80cab0af1e4b7a985be167ef61267a6eba1add3f63b059677c5c9c212a31c891739c7200ab321b64e32bb2e0c9d8655b
+  metadata.gz: a66dbb22594918562d9a50753ccfb8c0fd45410bc9bf285acdfba685c87d39026f2a487f5296ea2aec26b7ed15543b6c48f0c858944c7682dd53d453bf68982c
+  data.tar.gz: bf58a2bb020e650cae1202afe79148c5a47025ff8d63f90f44d4294111cfec3fe24f7746b70b148206d13cd16a627f67c081d1f5281ca055ab6f832cd4042a9d

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2017-2024 AppFolio, Inc., Steffen Bartsch
+Copyright (c) 2017-2025 AppFolio, Inc., Steffen Bartsch
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -0,0 +1,620 @@
+# 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
+
+### Install
+
+Declarative Authorization comes with an installer to make setup easy.
+
+First, include ae_declarative_authorization in your gemfile.
+
+```ruby
+gem 'ae_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 privileges, 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.
+
+```ruby
+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`:
+
+```ruby
+class MyRestfulController < ApplicationController
+  filter_resource_access
+end
+```
+
+For a non-RESTful controller, you can use `filter_access_to`:
+
+```ruby
+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.
+
+```erb
+<%= 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.
+
+```ruby
+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`.
+If you want to disable this behavior, you can use the `:strong_parameters` option.
+
+```ruby
+class EmployeesController < ApplicationController
+  filter_resource_access :strong_parameters => false
+end
+```
+
+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.
+
+```ruby
+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:
+
+```ruby
+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.
+
+```ruby
+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.
+
+```ruby
+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:
+
+```erb
+<% 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:
+
+```erb
+<% 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:
+
+```erb
+<% for employee in @employees do %>
+  <%= 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.
+
+```ruby
+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,
+
+```ruby
+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:
+
+```ruby
+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.
+
+```ruby
+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:
+
+```ruby
+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
+
+```ruby
+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`.
+
+```ruby
+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):
+
+```ruby
+    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:
+
+```ruby
+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.
+
+```ruby
+role :project_manager do
+  includes :employee
+end
+```
+
+See also `Authorization::Reader`.
+
+## Testing
+
+ae_declarative_authorization provides a few helpers to ease the testing with
+authorization in mind.
+
+In your test_helper.rb, to enable the helpers add
+
+```ruby
+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'`):
+
+```ruby
+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:
+
+```ruby
+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:
+
+```ruby
+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:
+
+```ruby
+get_with admin, :index
+post_with admin, :update, :employee => {...}
+```
+
+See `Authorization::TestHelper` for more information.
+
+
+## Providing the Plugin's Requirements
+The requirements are
+* Rails >= 4.2.5.2 and Ruby >= 2.1.x
+* 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.
+
+
+## License
+
+Released under MIT license.
+
+Copyright (c) 2008 Steffen Bartsch, TZI, Universität Bremen, Germany
+
+Copyright (c) 2011-2017 AppFolio, Inc.

data/declarative_authorization.gemspec

@@ -12,12 +12,12 @@ Gem::Specification.new do |spec|
   spec.summary       = spec.description
   spec.homepage      = 'https://github.com/appfolio/ae_declarative_authorization'
   spec.license       = 'MIT'
-  spec.files         = Dir['**/*'].select { |f| f[%r{^(lib/|LICENSE.txt|.*gemspec)}] }
+  spec.files         = Dir['**/*'].select { |f| f[%r{^(lib/|LICENSE.txt|.*gemspec|README.md|rubocop-decl-auth.yml)}] }
   spec.require_paths = ['lib']
 
-  spec.required_ruby_version = Gem::Requirement.new('< 3.4')
+  spec.required_ruby_version = Gem::Requirement.new(['>= 3.2', '< 3.5'])
   spec.metadata['allowed_push_host'] = 'https://rubygems.org'
 
   spec.add_dependency('blockenspiel', ['>= 0.5', '< 1'])
-  spec.add_dependency('rails', ['>= 6.1', '< 7.3'])
+  spec.add_dependency('rails', ['>= 7', '< 8.1'])
 end

data/lib/declarative_authorization/version.rb

@@ -1,3 +1,3 @@
 module DeclarativeAuthorization
-  VERSION = '1.5.0'.freeze
+  VERSION = '1.6.0'.freeze
 end

data/rubocop-decl-auth.yml

@@ -0,0 +1,7 @@
+require:
+  - ./lib/rubocop/cop/decl_auth/before_actions_precede_access_filter
+
+DeclAuth/BeforeActionsPrecedeAccessFilter:
+  Enabled: true
+  Include:
+      - '**/controllers/**/*controller.rb'

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ae_declarative_authorization
 version: !ruby/object:Gem::Version
-  version: 1.5.0
+  version: 1.6.0
 platform: ruby
 authors:
 - AppFolio
 bindir: bin
 cert_chain: []
-date: 2025-01-17 00:00:00.000000000 Z
+date: 2025-01-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: blockenspiel
@@ -35,20 +35,20 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.1'
+        version: '7'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '7.3'
+        version: '8.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.1'
+        version: '7'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '7.3'
+        version: '8.1'
 description: Rails gem for maintainable authorization based on readable authorization
   rules.
 email: opensource@appfolio.com
@@ -57,6 +57,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - LICENSE.txt
+- README.md
 - declarative_authorization.gemspec
 - lib/declarative_authorization.rb
 - lib/declarative_authorization/authorization.rb
@@ -78,6 +79,7 @@ files:
 - lib/generators/authorization/rules/templates/authorization_rules.rb
 - lib/rubocop/cop/decl_auth/before_actions_precede_access_filter.rb
 - lib/tasks/authorization_tasks.rake
+- rubocop-decl-auth.yml
 homepage: https://github.com/appfolio/ae_declarative_authorization
 licenses:
 - MIT
@@ -88,16 +90,19 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
   - - "<"
     - !ruby/object:Gem::Version
-      version: '3.4'
+      version: '3.5'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.3
+rubygems_version: 3.6.2
 specification_version: 4
 summary: Rails gem for maintainable authorization based on readable authorization
   rules.