express_access 1.0.0.a

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 69226d8e98c1c6312546082c4681bfe66a731c49
+  data.tar.gz: 6bdd3bdfc256a6ff39798456ba22eabd48e8740c
+SHA512:
+  metadata.gz: 8c59c6da7fa8c8c8e1a9c5f3f5fae02821ade84a5a899f60d9ce057eb838c11030c2916567a939bde579aaf497a8d3a5ea9d43722b29ecbf70f344d038ef1e22
+  data.tar.gz: 1ec3617f42dfeba476104f84abc0e754253d30132fe56f2e562a6044959ae89af075ee740f8c9081f62502903b70806fd53620e19654d5b0c829f58aa5160bf6

data/README.md

@@ -0,0 +1,87 @@
+# ExpressAccess
+
+[![Circle CI](https://circleci.com/gh/aelogica/express_access.svg?style=svg&circle-token=afa108d54cb1c149787f2ffde22d05794f0eee9b)](https://circleci.com/gh/aelogica/express_access)
+
+## Summary
+
+ExpressAccess provides Role-Based Authorization and Control for Rails applications using [ExpressAdmin](http://github.com/aelogica/express_admin).
+
+ExpressAccess is part of the [AppExpress](http://appexpress.io) suite of add-ons, however it may be used outside of AppExpress.  A sample Rails application template is provided to get you up and running quickly.
+
+## Description
+
+ExpressAccess allows a developer or other designated security policy administrator (a superadmin or superuser) to create and manage access control and permissions for an application or a group of applications.  It accomplishes this associating Users with:
+
+  * Roles
+  * Permissions
+  * Groups (optional)
+
+Specific permissions are created as needed and are granted to users directly or through the User's association with a Role or Group.  Users may belong to one or more Roles or Groups.  Roles may be hierarchical, inheriting their permissions through their parent role.
+
+### Example
+
+Let us suppose we have the following roles and permissions:
+
+  * Reader
+      - comments#create
+  * Author
+      - article#create
+      - article#update
+  * Editor
+      - article#publish
+  * Admin
+      - users#create
+      - users\_roles#create
+      - users\_roles#delete
+
+If we define the hierarchy as:
+
+    Reader -> Author -> Editor -> Admin
+
+then a User with the Editor role, will be able to create, update and publish articles.  A User who only has the Author role will be able to create and update articles but will not be able to publish them.  Both would also be able to create comments.   A User with the Admin role would be able to create other users and assign roles to them.
+
+The permissions are named according to convention.  It is up to the application developer to interperet and enforce permissions correctly according to the needs of their application.
+
+ExpressAccess provides an administrative interface and model for associating a bundle of Permissions with a User through Groups and Roles.
+
+In addition, ExpressAccess provides a controller mixin which enforces permissions on a controller/action level based on the convention of naming permissions using either the controller name alone or the controller#action pair.
+
+### Model Level Access Control
+
+It may be possible to implement a more fine-grained control of access to specific data objects or fields at a model level, however we have not seen a need for this in the majority of our work.  Most Rails applications perform access control functions at the controller level.
+
+### Why Not Define Roles and Permissions in Code?
+
+Many applications need the ability to adjust access control policies without triggering an application deployment.  In addition, in a small enterprise environment, the security policy administrator may also be a non-technical application owner.  He or she not be able to correctly read or interpret a Ruby DSL for access control and may not wish to enter a developer-type workflow or call on a developer in order to change application security policies.
+
+## Dependencies
+
+This engine requires [ExpressAdmin](http://github.com/aelogica/express_admin) to function.  Please follow the instructions to install ExpressAdmin before installing ExpressAccess.
+
+## Usage
+
+To use ExpressAccess add this to your gemfile:
+
+    gem "express_access"
+
+Run bundle install:
+
+    bundle install
+
+Then run the install generator:
+
+    rails generate express_access:install
+
+This will mount the engine in your application at '/admin/access', however you may override the location by changing your routes.rb.
+
+## Sample Application
+
+If you want to start a new application that is prepared for ExpressAccess installation, use the ExpressAdmin template.  Simply run:
+
+    rails new my_great_app -t https://github.com/aelogica/express_admin/template.rb
+
+Then perform the steps above in Usage.
+
+---
+
+This project rocks and uses MIT-LICENSE.

data/Rakefile

@@ -0,0 +1,34 @@
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rdoc/task'
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'ExpressAccess'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+APP_RAKEFILE = File.expand_path("../test/dummy/Rakefile", __FILE__)
+load 'rails/tasks/engine.rake'
+
+
+
+Bundler::GemHelper.install_tasks
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+
+task default: :test

data/app/assets/javascripts/express_access/admin.js

@@ -0,0 +1 @@
+//= require_tree .

data/app/assets/stylesheets/express_access/admin.css

@@ -0,0 +1,5 @@
+/*
+*= require express_admin
+*= require express_access/main
+*= require_self
+*/

data/app/assets/stylesheets/express_access/application.css

@@ -0,0 +1,15 @@
+/*
+ * This is a manifest file that'll be compiled into application.css, which will include all the files
+ * listed below.
+ *
+ * Any CSS and SCSS file within this directory, lib/assets/stylesheets, vendor/assets/stylesheets,
+ * or vendor/assets/stylesheets of plugins, if any, can be referenced here using a relative path.
+ *
+ * You're free to add application-wide styles to this file and they'll appear at the bottom of the
+ * compiled file so the styles you add here take precedence over styles defined in any styles
+ * defined in the other CSS/SCSS files in this directory. It is generally better to create a new
+ * file per style scope.
+ *
+ *= require express_admin
+ *= require_self
+ */

data/app/assets/stylesheets/express_access/main.sass

@@ -0,0 +1,3 @@
+// @import 'foundation'
+// @import 'express_admin/globals/variables'
+// @import 'sections/role_dashboard'

data/app/assets/stylesheets/express_access/sections/_role_dashboard.sass

@@ -0,0 +1,29 @@
+.role-page
+  @include grid-block($orientation: vertical)
+
+  .role-information
+    @include grid-block
+
+  .resource-access
+    @include grid-block
+
+  .role-tree
+    @include grid-block(2)
+    border:
+      bottom: 1px solid $border-color
+
+  .additional-information
+    @include grid-block(5, $orientation: vertical)
+
+  .role-form
+    @include grid-block(5)
+    border:
+      bottom: 1px solid $border-color
+
+.role-list
+  @extend .block-list
+
+.role-information
+  > .pane
+    border:
+      bottom: 1px solid $border-color

data/app/assets/stylesheets/express_access.css

@@ -0,0 +1,4 @@
+/*
+*= require express_admin
+*= require express_access/main
+*/

data/app/controllers/express_access/permissions_controller.rb

@@ -0,0 +1,4 @@
+module ExpressAccess
+  class PermissionsController < ExpressAdmin::StandardController
+  end
+end

data/app/controllers/express_access/roles_controller.rb

@@ -0,0 +1,14 @@
+module ExpressAccess
+  class RolesController < ExpressAdmin::StandardController
+
+    protected
+
+      def load_collection
+        if action_name.eql?('show')
+          @roles = super.top_level
+        else
+          super
+        end
+      end
+  end
+end

data/app/controllers/express_access/routes_controller.rb

@@ -0,0 +1,30 @@
+module ExpressAccess
+  class RoutesController < ExpressAdmin::StandardController
+
+    protected
+
+      # not used because we don't build routes in the UI
+      def build_resource(*args)
+        Object.new
+      end
+
+      def search(scope)
+        search_results = scope.all.find_all do |route|
+                          match_substring(scope,route)
+                        end
+      end
+
+    private
+
+      def match_substring(scope,route)
+        columns = scope.columns.map(&:name)
+        columns.find do |col|
+          unless route.try(col).nil?
+            if route.try(col).include? params[:search_string]
+              route
+            end
+          end
+        end
+      end
+  end
+end

data/app/controllers/express_access/users_controller.rb

@@ -0,0 +1,21 @@
+module ExpressAccess
+  class UsersController < ExpressAdmin::StandardController
+
+    private
+
+      def user_params
+        user_params = params.require(:user)
+        if user_params[:password].blank? && user_params[:password_confirmation].blank?
+          user_params.delete(:password)
+          user_params.delete(:password_confirmation)
+        end
+        user_params.permit!
+      end
+
+    protected
+
+      def resource_class
+        ::User
+      end
+  end
+end

data/app/helpers/express_access/application_helper.rb

@@ -0,0 +1,4 @@
+module ExpressAccess
+  module ApplicationHelper
+  end
+end

data/app/helpers/express_access/permissions_helper.rb

@@ -0,0 +1,4 @@
+module ExpressAccess
+  module PermissionsHelper
+  end
+end

data/app/helpers/express_access/roles_helper.rb

@@ -0,0 +1,4 @@
+module ExpressAccess
+  module RolesHelper
+  end
+end

data/app/models/express_access/audit_log.rb

@@ -0,0 +1,27 @@
+module ExpressAccess
+  class AuditLog < ActiveRecord::Base
+
+    belongs_to :user
+
+    def self.for(endp)
+      endpoint = endp.split("#")
+      controller_path = endpoint.first
+      action_name = endpoint.last
+      log_for_endpoint = find_by_endpoint(controller_path, action_name)
+      grouped_logs = group_by_date(log_for_endpoint)
+    end
+
+    def self.find_by_endpoint(path, name)
+      AuditLog.where("controller_name='#{path}' AND action_name='#{name}'").last(5)
+    end
+
+    def self.group_by_date(unsorted_log)
+      sorted_log = []
+      sorted_log << unsorted_log.group_by do |log|
+        log.created_at.to_date
+      end
+      sorted_log.reverse
+    end
+
+  end
+end

data/app/models/express_access/permission.rb

@@ -0,0 +1,130 @@
+module ExpressAccess
+  class Permission < ActiveRecord::Base
+    has_many :role_permissions
+    has_many :roles, through: :role_permissions, source: :role
+
+    has_many :user_permissions
+    has_many :specially_permitted_users, through: :user_permissions,
+             source: :user, class_name: "::User"
+
+    default_scope -> { order(:name) }
+
+    def self.[] name
+      Permission.find_by_name(name.to_s)
+    end
+
+    # Returns roles that have this permission. Includes any Roles that
+    # have this permission directly, as well as their children who
+    # inherit this permission
+    def all_roles
+      @roles = roles.map(&:all_children).flatten.to_set
+    end
+
+    def all_routes
+      Route.all.select { |r| r.permission.eql?(self) }
+    end
+
+    def user_count
+      all_roles.map {|r| r.users.count }.sum + specially_permitted_users.count
+    end
+
+    def controllers
+      all_routes.map(&:controller).to_set
+    end
+
+    # Searches for the most specific permission that ought to apply
+    # for a request with the specified controller, action and path.
+    # Returns nil if no permissions should apply.
+    #
+    # This mediates between potentially conflicting permissions by
+    # establishing a clear priority.
+    #
+    # For example:
+    #
+    #   admin/posts#edit
+    #
+    # is more specific than:
+    #
+    #   admin/posts
+    #   admin
+    #
+    #
+    # A particularly difficult case arises when both path
+    # and module/controller#action style permissions exist for a
+    # given controller, action and path.
+    #
+    # In this case, we seek to identify which one is more "specific"
+    # based on how long it is.  In the case where the matching path and
+    # controller path with action both have the same length, the path
+    # takes priority.  This allows us to protect specific resources
+    # within a collection should we desire.
+    #
+    # For example, a permission named "/posts/999" is more specific
+    # than "posts#publish" even though they both consist of two segments.
+    # This means the "/posts/999" should apply when someone accesses:
+    #
+    #    /posts/999/publish
+    #
+    def self.for(controller: nil, action: nil, path: nil)
+      controller_permissions = controller_action_permissions_for(controller, action)
+      path_permissions = path_permissions_for(path)
+
+      # use the longer (more specific) list as basis for zip
+      possible_permissions = normalize_and_zip( controller_permissions, path_permissions)
+
+      # return the first non-nil entry of the zipped arrays
+      possible_permissions.first
+    end
+
+    private
+
+      # Return an array containing a list of potentially applicable permissions
+      # in order from most specific to least specific.
+      def self.normalize_and_zip(longer, shorter)
+        longer, shorter = shorter, longer if longer.size < shorter.size
+
+        longer.reverse.zip(shorter.reverse).flatten.compact.reverse
+      end
+
+      # Return a list of permissions matching the path segments
+      # in order of specificity from most specific (matching the entire
+      # path segment tuple) to the least specific. (matching only the first
+      # path segment)
+      #
+      # The list will contain nils where no matching Permission exists.
+      def self.path_permissions_for(path)
+        path_permissions = []
+        if path
+          path_parts = path.split("/")
+          path_permissions << Permission[path]
+          while path_parts.pop && !path_parts.empty?
+            path_permissions << Permission[path_parts.join("/")]
+          end
+        end
+        path_permissions
+      end
+
+      # Return a list of permissions matching the namespace/controller/action
+      # path from most specific (matching the entire tuple) to the
+      # least specific.  (matching only the top-level namespace or the
+      # controller if not namespaced)  We create the first, most specific
+      # permission name by including the action.
+      #
+      # The list will contain nils where no matching Permission exists.
+      def self.controller_action_permissions_for(controller, action)
+        controller_permissions = []
+        if controller && action
+          controller_modules = controller.split("/")
+          # order from most specific to least specific
+          controller_permissions << Permission["#{controller}##{action}"]
+
+          while controller_modules.pop && !controller_modules.empty?
+            controller_permissions << Permission[controller_modules.join("/")]
+          end
+          controller_permissions << Permission["#{controller}"]
+        end
+        controller_permissions
+      end
+
+  end
+end

data/app/models/express_access/role.rb

@@ -0,0 +1,75 @@
+module ExpressAccess
+  class Role < ActiveRecord::Base
+    belongs_to :parent, class_name: 'ExpressAccess::Role',
+                        inverse_of: :children
+    has_many :role_permissions
+    has_many :direct_permissions,    through: :role_permissions,
+                                     source: :permission
+
+    has_many :children, :inverse_of => :parent,
+                        :foreign_key => :parent_id,
+                        :class_name => 'ExpressAccess::Role'
+
+    scope :top_level, -> { where(parent_id: nil) }
+
+    has_many :user_roles
+    has_many :users, through: :user_roles,
+                      source: :user,
+                  class_name: "::User"
+
+    def self.expressers
+      find_by(name: 'Expresser').users
+    end
+
+    def childrens_users
+      (all_children - [self]).map(&:users).flatten
+    end
+
+    def all_children
+      visitor = -> (visitor, role) {
+          [role] + role.children.map { |child|
+            visitor.call(visitor, child)
+          }
+        }
+      visitor.call(visitor,self).flatten
+    end
+
+    def self.[] name
+      Role.find_by_name(name.to_s.titleize)
+    end
+
+    def source_of(permission)
+      if direct_permissions.include?(permission)
+        "direct"
+      else
+        current = self
+        ancestors = []
+        while current = current.parent
+          ancestors << current
+        end
+        source = ancestors.detect {|ancestor| ancestor.direct_permissions.include?(permission)}
+        "inherited from #{source.name}"
+      end
+    end
+
+    def parent_name
+      parent.try(:name) || ''
+    end
+
+    def direct_permissions_count
+      direct_permissions.count
+    end
+
+    def total_permissions_count
+      permissions.size
+    end
+
+    def permissions
+      direct_permissions + inherited_permissions
+    end
+
+    def inherited_permissions
+      parent ? parent.permissions : []
+    end
+  end
+end

data/app/models/express_access/role_permission.rb

@@ -0,0 +1,6 @@
+module ExpressAccess
+  class RolePermission < ActiveRecord::Base
+    belongs_to :role
+    belongs_to :permission
+  end
+end

data/app/models/express_access/user_permission.rb

@@ -0,0 +1,7 @@
+module ExpressAccess
+  class UserPermission < ActiveRecord::Base
+    belongs_to :user, class_name: "::User"
+    belongs_to :permission
+    delegate :name, to: :permission
+  end
+end

data/app/models/express_access/user_role.rb

@@ -0,0 +1,7 @@
+module ExpressAccess
+  class UserRole < ActiveRecord::Base
+    belongs_to :user, class_name: '::User'
+    belongs_to :role
+    delegate :name, to: :role
+  end
+end

data/app/views/express_access/permissions/index.html.et

@@ -0,0 +1,13 @@
+pane(title: "Permissions") {
+  smart_table(:permissions,
+      columns: {
+      "Permission Name" => :name_link,
+      "Created"         => :created_at_in_words,
+      "Updated"         => :updated_at_in_words
+      })
+
+}
+
+pane(title: "Create a Permission") {
+  smart_form(:permission, exclude: [:users, :roles, :specially_permitted_users, :created_at, :updated_at])
+}

data/app/views/express_access/permissions/show.html.et

@@ -0,0 +1,33 @@
+v_box {
+  pane(title: "<strong>#{permission.name}</strong>".html_safe,
+      status: "#{permission.all_roles.size} Roles, #{permission.all_routes.size} Routes, #{permission.user_count} Users") {
+    dl {
+      dt { "Permission Created:" }
+      dd { permission.created_at ? "#{time_ago_in_words(permission.created_at)}" + " ago" : "unknown"}
+
+      dt { "Roles:" }
+      dd { permission.all_roles.map {|role| helpers.link_to role.name, role_path(role)}.join(", ").html_safe}
+
+      dt { "User Assignments:" }
+      dd { permission.specially_permitted_users.any? ? permission.specially_permitted_users.map {|user| helpers.link_to user.name, user_path(user) }.join(", ").html_safe : 'None'}
+
+      dt { "Controllers:"}
+      dd { permission.controllers.any? ? "#{ul { permission.controllers.each { |controller| li { controller } }}}" : "None" }
+    }
+  }
+
+  pane(title: 'Role & User Assignments') {
+    smart_form(:permission, exclude: [:name, :created_at, :updated_at])
+  }
+}
+
+
+pane(title: 'Resources Protected', class: 'large-table-container') {
+  smart_table(:routes, actions: false,
+      collection: -> { permission.all_routes.to_a },
+      columns: {
+      "Path" => :path_link,
+      "Endpoint" => :endp_link,
+      "Description" => :description_link
+      })
+}

data/app/views/express_access/roles/index.html.et

@@ -0,0 +1,9 @@
+main_region {
+  h2 { 'Roles' }
+  smart_table(:roles,
+      columns: {"Name"               => :name_link,
+                "Parent"             => :parent_id,
+                "Description"        => :description,
+                "Direct Permissions" => :direct_permissions_count,
+                "Total Permissions"  => :total_permissions_count})
+}

data/app/views/express_access/roles/show.html.et

@@ -0,0 +1,68 @@
+h_box {
+  v_box {
+    h_box {
+      pane(title: "#{role.name} Role") {
+        para {
+          role.description
+        }
+        section(class: "role-list") {
+          tree_for(:roles, title: "Roles") { |node|
+            div(class: (node.eql?(role) ? 'selected' : '')) {
+              a(href: role_path(node)) {
+                node.name
+              }
+            }
+          }
+        }
+      }
+      v_box {
+        pane(title: role.name.pluralize,
+             status: "#{role.users.count} users") {
+          smart_table(:users, actions: false, resource_class: '::User', resource_path: -> (user) { express_access.user_path(user) },
+                      collection: -> { role.users.sort_by(&:email) },
+                      columns: {
+                        'Name' => :name_link,
+                        'Last signed in' => :last_sign_in_at_in_words
+                      })
+
+        }
+        pane(title: "Inheritors of #{role.name}",
+                        status: "#{role.childrens_users.count} users") {
+          smart_table(:users, actions: false, resource_class: '::User', resource_path: -> (user) { express_access.user_path(user) },
+                      collection: -> { role.childrens_users.sort_by(&:email) },
+                      columns: {
+                        'Name' => :name_link,
+                        'Last signed in' => :last_sign_in_at_in_words
+                      })
+
+        }
+
+        pane(title: "All Permissions for #{role.name}") {
+          smart_table(:permissions, actions: false,
+                      collection: -> { role.permissions.sort_by(&:name) },
+                      columns: {
+                        'Permissions' => -> (permission) { helpers.link_to permission.name, permission_path(permission) },
+                        'Through' => -> (permission) { role.source_of(permission)}
+                      })
+        }
+      }
+    }
+    pane(title: "Resource Access for #{role.name}", class: 'large-table-container') {
+      smart_table(:routes, actions: false, scroll_table: true,
+                  collection: -> { ExpressAccess::Route.all },
+                  row_class: -> (route) { status = route.status_for_role(role) ; case status when "granted" ; 'green' ; when 'denied' ; 'red' else '' end },
+                  columns: {
+                    "Path" => :path_link,
+                    "Endpoint" => :endp_link,
+                    "Description" => :description_link,
+                    "Locked?" => -> (route) { route.status_for_role(role).upcase }
+                  })
+
+    }
+  }
+  pane(title: "Edit #{role.name}") {
+    smart_form(:role, exclude: [:users])
+  }
+}
+
+