ixtlan-guard 0.7.2 → 0.8.0

data/README.md

@@ -0,0 +1,104 @@
+# ixtlan guard #
+
+it is an simple authorization framework for restful rails especially using rails as API server.
+
+the idea is simple: 
+
+* each user belongs to set of groups
+* each controller/action pair permits a set of groups to execute it
+* the guard class checks if the user has any group which is allowed by the controller/action pair
+
+## current\_user\_groups method ##
+
+this is similar to the **current_user** method common on authentication. the **current_user_groups** method is an array of object which responds to __:name__. call these objects groups which have name. the name is used in the permission config of the controller.
+
+having something like PosixAccounts and PosixGroups (as know from ldap) would lead to an implementation like (which is the default when there is no such method)
+
+     def current_user_groups
+       current_user.groups
+     end
+     
+## config for a controller
+
+this is a yaml file in **RAILS_ROOT/app/guards/my\_users\_guard.yml**. for example
+
+     my_users:
+       index:
+         - root
+         - user-admin
+         - app-admin
+       show: [root,app-admin,guest]
+       new: [root]
+       create: [root]
+       edit: [root,app-admin]
+       update: [root,app-admin]
+       destroy: [root]
+
+with the special action **defaults** this can be reduced to
+
+     my_users:
+       defaults: [root]
+       index:
+         - root
+         - user-admin
+         - app-admin
+       show: [root,app-admin,guest]
+       edit: [root,app-admin]
+       update: [root,app-admin]
+
+and since **root** is handle by the guard anyways it can be further reduced to
+
+     my_users:
+       defaults: []
+       index:
+         - user-admin
+         - app-admin
+       show: [app-admin,guest]
+       edit: [app-admin]
+       update: [app-admin]
+
+## rails helper methods
+
+### authorize method of controller
+
+  the authorize method asked the Guard if a certain action on a controller is allowed by the current_user, if not the method raises an Error. this method is registered as before-filter on the application-contrller. so **skip-before-filter :authorize** will disable the guard.
+  
+### allowed? method of controller
+
+the call `allowed?(:destroy)` will give the permissions for the given action on the current controller.
+
+### allowed? method of views
+
+it takes two arguments since the controller name (or resource name) is needed as well. the call `allowed?(:users, :destroy)` will give the permissions for the given action controller pair.
+
+### getting the Guard instance
+
+to get an instance of the **Guard** on the controller itself just call `guard`. otherwise `Rails.application.config.guard` will give you such an instance.
+
+# more advanced
+
+sometimes you want to bind resource to a user/group pair, i.e. given an organizations which have report-writers and report-readers. example as rails before-filter:
+
+    skip_before-filter :authorize
+    guard_filter :authorize_organization_reader, :only => [:show]
+    guard_filter :authorize_organization_writer, :only => [:edit, :update]
+
+    def authorize_organization_writer(groups)
+      groups.select { |g| g.writer?(current_user) }
+    end
+    
+    def authorize_organization_reader
+      groups.select { |g| g.writer?(current_user) || org.writer?(current_user)|}
+    end
+
+of course you can organize such relations also like that
+
+    skip_before_filter :authorize
+    guard_filter :authorize_organization
+
+    def authorize_organization(groups)
+      gou = GroupsOrganizationsUser.where(:org_id => params(:org_id),
+                                          :user_id => current_user.id)
+      ids = gou.collect { |i| i.group_id }
+      groups.select { |g| ids.include?(g.id) }
+    end

data/lib/ixtlan/guard.rb

@@ -1 +1 @@
-require 'ixtlan/guard/guard_ng'
+require 'ixtlan/guard/guard'

data/lib/ixtlan/guard/{guard_ng.rb → guard.rb}

@@ -2,7 +2,7 @@ require 'ixtlan/guard/guard_config'
 
 module Ixtlan
   module Guard
-    class GuardNG
+    class Guard
 
       attr_reader :superuser
 
@@ -13,6 +13,10 @@ module Ixtlan
         @logger = options[:logger]
       end
 
+      def superuser_name
+        @superuser[0]
+      end
+
       def block_groups(groups)
         @blocked_groups = (groups || []).collect { |g| g.to_s}
         @blocked_groups.delete(@superuser)
@@ -33,8 +37,11 @@ module Ixtlan
           end
       end
 
-      def allowed_groups(resource_name, action, current_group_names)
-        allowed = @config.allowed_groups(resource_name, action) - blocked_groups + @superuser
+      def allowed_groups(resource_name, 
+                         action, 
+                         current_group_names)
+        allowed = @config.allowed_groups(resource_name, action)
+        allowed = allowed - blocked_groups + @superuser
         if allowed.member?('*')
           # keep superuser in current_groups if in there
           current_group_names - (blocked_groups - @superuser)
@@ -59,37 +66,35 @@ module Ixtlan
       end
       private :group_map
 
-      def allowed?(resource_name, action, current_groups, association = nil, &block)
+      def check(resource_name, action, current_groups, &block)
+        action = action.to_s
         group_map = group_map(current_groups)
         allowed_group_names = allowed_groups(resource_name, action, group_map.keys)
-        logger.debug { "guard #{resource_name}##{action}: #{allowed_group_names.size > 0}" }
+
         if allowed_group_names.size > 0
-          if block || association
-            group_allowed?(group_map, allowed_group_names, association, &block)
-          else
-            true
+          groups = allowed_group_names.collect { |name| group_map[name] }
+          # call block to filter groups unless we are superuser
+          if block && !allowed_group_names.member?(superuser_name)
+            groups = block.call(groups)
           end
+          
+          logger.debug { "guard #{resource_name}##{action}: #{groups.size > 0}" }
+
+          # nil means 'access denied', i.e. there are no allowed groups
+          groups if groups.size > 0
         else
           unless @config.has_guard?(resource_name)
             raise ::Ixtlan::Guard::GuardException.new("no guard config for '#{resource_name}'")
           else
-            false
+            logger.debug { "guard #{resource_name}##{action}: #{allowed_group_names.size > 0}" }
+            # nil means 'access denied', i.e. there are no allowed groups
+            nil
           end
         end
       end
 
-      def group_allowed?(group_map, allowed_group_names, association, &block)
-        g = allowed_group_names.detect do |group_name|
-          block.call(group_map[group_name], association)
-        end if association && block
-        logger.debug do
-          if g
-            "found group #{g} for #{association}" 
-          else
-            "no group found for #{association}"
-          end
-        end
-        g != nil
+      def allowed?(resource, action, groups, &block)
+        check(resource, action, groups, &block) != nil
       end
 
       def permissions(current_groups, &block)
@@ -101,20 +106,24 @@ module Ixtlan
           perm = Node.new(:permission)
           perm[:resource] = resource
           perm[:actions] = nodes
-          default_actions = actions.delete('defaults') || []
-          default_actions = group_map.keys & (default_actions + @superuser) unless default_actions.member?('*')
+
+          # setup default_groups
+          default_groups = actions.delete('defaults') || []
+          default_groups = group_map.keys & (default_groups + @superuser) unless default_groups.member?('*')
+
           deny = if actions.size == 0
                    # no actions
-                   # deny = false: !default_actions.member?('*')
-                   # deny = true: default_actions.member?('*') || current_group_names.member?(@superuser[0])
-                   default_actions.member?('*') || group_map.keys.member?(@superuser[0]) || !group_map.keys.detect {|g| default_actions.member? g }.nil?
+                   # deny = false: !default_groups.member?('*')
+                   # deny = true: default_groups.member?('*') || current_group_names.member?(@superuser[0])
+                   default_groups.member?('*') || group_map.keys.member?(@superuser[0]) || !group_map.keys.detect {|g| default_groups.member? g }.nil?
                  else
                    # actions
-                   # deny = false : default_actions == []
-                   # deny = true : default_actions.member?('*')
-                   default_actions.size != 0 || default_actions.member?('*')
+                   # deny = false : default_groups == []
+                   # deny = true : default_groups.member?('*')
+                   default_groups.size != 0 || default_groups.member?('*')
                  end
           perm[:deny] = deny
+
           actions.each do |action, groups|
             group_names = groups.collect { |g| g.is_a?(Hash) ? g.keys : g }.flatten if groups
             node = Node.new(:action)
@@ -125,22 +134,29 @@ module Ixtlan
                 names = group_map.keys & ((group_names || []) + @superuser)
                 names.collect { |name| group_map[name] }
               end
+
             if (deny && allowed_groups.size == 0) || (!deny && allowed_groups.size > 0)
               node[:name] = action
               if block
                 if allowed_groups.size > 0
-                  node.content.merge!(block.call(resource, action, allowed_groups) || {})
+                  assos = block.call(resource, allowed_groups)
+                  node[:associations] = assos if assos && assos.size > 0
                 else
-                  perm.content.merge!(block.call(resource, action, group_map.values) || {})
+                  assos = block.call(resource, group_map.values)
+                  perm[:associations] = assos if assos && assos.size > 0
                 end
               end
               nodes << node
+            elsif deny && allowed_groups.size > 0 && block
+              assos = block.call(resource, group_map.values)
+              perm[:associations] = assos if assos && assos.size > 0
             end
           end
           # TODO is that right like this ?
-          # only default_actions, i.e. no actions !!!
+          # only default_groups, i.e. no actions !!!
           if block && actions.size == 0 && deny
-            perm.content.merge!(block.call(resource, nil, group_map.values) || {})
+            assos = block.call(resource, group_map.values)
+            perm[:associations] = assos if assos && assos.size > 0
           end
           perms << perm
         end

data/lib/ixtlan/guard/guard.rb~

@@ -0,0 +1,195 @@
+require 'ixtlan/guard/guard_config'
+
+module Ixtlan
+  module Guard
+    class Guard
+
+      attr_reader :superuser
+
+      def initialize(options = {})
+        options[:guards_dir] ||= File.expand_path(".")
+        @superuser = [(options[:superuser] || "root").to_s]
+        @config = Config.new(options)
+        @logger = options[:logger]
+      end
+
+      def superuser_name
+        @superuser[0]
+      end
+
+      def block_groups(groups)
+        @blocked_groups = (groups || []).collect { |g| g.to_s}
+        @blocked_groups.delete(@superuser)
+        @blocked_groups
+      end
+
+      def blocked_groups
+        @blocked_groups ||= []
+      end
+
+      def logger
+        @logger ||= 
+          if defined?(Slf4r::LoggerFactory)
+            Slf4r::LoggerFactory.new(Ixtlan::Guard)
+          else
+            require 'logger'
+            Logger.new(STDOUT)
+          end
+      end
+
+      def allowed_groups_and_restricted(resource_name, 
+                                        action, 
+                                        current_group_names)
+        allowed, restricted = 
+          @config.allowed_groups_and_restricted(resource_name, action)
+        allowed = allowed - blocked_groups + @superuser
+        result = if allowed.member?('*')
+                   # keep superuser in current_groups if in there
+                   current_group_names - (blocked_groups - @superuser)
+                 else
+                   allowed & current_group_names
+                 end
+        [result, restricted]
+      end
+
+      def group_map(current_groups)
+        names = current_groups.collect do |g| 
+          key = case g
+                when String 
+                  g
+                when Symbol 
+                  g.to_s
+                else 
+                  g.name.to_s
+                end
+          [key, g] 
+        end
+        Hash[*(names.flatten)]
+      end
+      private :group_map
+
+      def check(resource_name, action, current_groups, &block)
+        action = action.to_s
+        group_map = group_map(current_groups)
+        allowed_group_names, restricted = 
+          allowed_groups_and_restricted(resource_name, action, group_map.keys)
+        
+        logger.debug { "guard #{resource_name}##{action}: #{allowed_group_names.size > 0}" }
+
+        if allowed_group_names.size > 0
+          groups = allowed_group_names.collect { |name| group_map[name] }
+          # call block to filter groups if restricted applies
+          if restricted && !allowed_group_names.member?(superuser_name)
+            raise "no block given to filter groups" unless block 
+            except = restricted['except'] || []
+            only = restricted['only'] || [action]
+            if !except.member?(action) && only.member?(action)
+              groups = block.call(groups)
+            end
+          end
+
+          # nil means 'access denied', i.e. there are no allowed groups
+          groups if groups.size > 0
+        else
+          unless @config.has_guard?(resource_name)
+            raise ::Ixtlan::Guard::GuardException.new("no guard config for '#{resource_name}'")
+          else
+            # nil means 'access denied', i.e. there are no allowed groups
+            nil
+          end
+        end
+      end
+
+      def allowed?(resource, action, groups, &block)
+        check(resource, action, groups, &block) != nil
+      end
+
+      def permissions(current_groups, &block)
+        group_map = group_map(current_groups)
+        perms = []
+        m = @config.map_of_all
+        m.each do |resource, actions|
+          nodes = []
+          perm = Node.new(:permission)
+          perm[:resource] = resource
+          perm[:actions] = nodes
+
+          restricted = actions.delete('restricted')
+
+          # setup default_groups
+          default_groups = actions.delete('defaults') || []
+          default_groups = group_map.keys & (default_groups + @superuser) unless default_groups.member?('*')
+
+          deny = if actions.size == 0
+                   # no actions
+                   # deny = false: !default_groups.member?('*')
+                   # deny = true: default_groups.member?('*') || current_group_names.member?(@superuser[0])
+                   default_groups.member?('*') || group_map.keys.member?(@superuser[0]) || !group_map.keys.detect {|g| default_groups.member? g }.nil?
+                 else
+                   # actions
+                   # deny = false : default_groups == []
+                   # deny = true : default_groups.member?('*')
+                   default_groups.size != 0 || default_groups.member?('*')
+                 end
+          perm[:deny] = deny
+
+          actions.each do |action, groups|
+            group_names = groups.collect { |g| g.is_a?(Hash) ? g.keys : g }.flatten if groups
+            node = Node.new(:action)
+            allowed_groups = 
+              if groups && group_names.member?('*')
+                group_map.values
+              else
+                names = group_map.keys & ((group_names || []) + @superuser)
+                names.collect { |name| group_map[name] }
+              end
+
+            if (deny && allowed_groups.size == 0) || (!deny && allowed_groups.size > 0)
+              node[:name] = action
+              if block
+                if allowed_groups.size > 0
+                  assos = block.call(resource, allowed_groups)
+                  node[:associations] = assos if assos && assos.size > 0
+                else
+                  assos = block.call(resource, group_map.values)
+                  perm[:associations] = assos if assos && assos.size > 0
+                end
+              end
+              nodes << node
+            elsif deny && allowed_groups.size > 0 #block
+              assos = block.call(resource, group_map.values)
+              perm[:associations] = assos if assos && assos.size > 0
+            end
+          end
+          # TODO is that right like this ?
+          # only default_groups, i.e. no actions !!!
+          if block && actions.size == 0 && deny
+            assos = block.call(resource, group_map.values)
+            perm[:associations] = assos if assos && assos.size > 0
+          end
+          perms << perm
+        end
+        perms
+      end
+    end
+    class Node < Hash
+
+      attr_reader :content
+
+      def initialize(name)
+        map = super
+        @content = {}
+        merge!({ name => @content })
+      end
+
+      def []=(k,v)
+        @content[k] = v
+      end
+      def [](k)
+        @content[k]
+      end
+    end
+    class GuardException < Exception; end
+    class PermissionDenied < GuardException; end
+  end
+end