Class: Permit::PermitRules

Inherits:
Object
  • Object
show all
Includes:
Support
Defined in:
lib/permit/permit_rules.rb

Overview

Collection of PermitRule objects defining authorization.

Instance Attribute Summary (collapse)

Instance Method Summary (collapse)

Methods included from Support

#authorization_conditions, #get_role, #get_roles, #permit_arrayify, #resource_conditions, #role_condition

Constructor Details

- (PermitRules) initialize(logger, options = {})

Returns a new instance of PermitRules

Parameters:

  • logger (#info)

    the logger to use when evaluating rules

  • options (Hash) (defaults to: {})

    the set of options to use during rule evaluation

Options Hash (options):

  • :default_access (Symbol)

    overrides the value in Permit::Config#default_access to indicate how #permitted? will behave if no rules match.



13
14
15
16
17
18
# File 'lib/permit/permit_rules.rb', line 13

def initialize(logger, options = {})
  @action_deny_rules = {}
  @action_allow_rules = {}
  @logger = logger
  @options = options
end

Instance Attribute Details

- (Object) action_allow_rules

Returns the value of attribute action_allow_rules



6
7
8
# File 'lib/permit/permit_rules.rb', line 6

def action_allow_rules
  @action_allow_rules
end

- (Object) action_deny_rules

Returns the value of attribute action_deny_rules



6
7
8
# File 'lib/permit/permit_rules.rb', line 6

def action_deny_rules
  @action_deny_rules
end

- (Object) logger

Returns the value of attribute logger



6
7
8
# File 'lib/permit/permit_rules.rb', line 6

def logger
  @logger
end

- (Object) options

Returns the value of attribute options



6
7
8
# File 'lib/permit/permit_rules.rb', line 6

def options
  @options
end

Instance Method Details

- (PermitRule) allow(roles, options = {})

Adds an allow rule for the given actions to the collection.

Examples:

Allow a person that is a member of a team to show

allow :person, :who => :is_member, :of => :team, :to => :show

Allow a person that is a member of any of the teams to index.

allow :person, :who => :is_member, :of => [:team1, :team2], :to => :index

Allow a person with either of the named roles for a resource to perform any "write" operations.

allow [:project_admin, :project_manager], :of => :project, :to => :write

Allow a person with the viewer role of either of the projects to show.

allow :viewer, :of => [:project1, :project2], :to => :show

Parameters:

  • roles (Symbol, <Symbol>)

    the role(s) that the rule will apply to.

  • options (Hash) (defaults to: {})

    the options used to build the rule.

Options Hash (options):

  • :who (Symbol)

    the method to call on the target resource.

  • :that (Symbol)

    alias for :who

  • :of (Symbol, nil, :any, <Symbol, nil>)

    the name of the instance variable holding the target resource. If set to :any then the match will apply to a person that has a matching role authorization for any resource. If not given, or set to nil, then the match will apply to a person that has a matching role authorization for a nil resource. :any/nil functionality only applies when using named roles. (see Permit::NamedRoles).

  • :on (Symbol, nil, :any, <Symbol, nil>)

    alias for :of

  • :if (Symbol, String, Proc)

    code to evaluate at the end of the match if it is still valid. If it returns false, the rule will not match. If a proc if given, it will be passed the current subject and binding. A method will be called without any arguments.

  • :unless (Symbol, String, Proc)

    code to evaluate at the end of the match if it is still valid. If it returns true, the rule will not match. If a proc if given, it will be passed the current subject and binding. A method will be called without any arguments.

  • :to (Symbol, <Symbol>)

    the action(s) to allow access to if this rule matches. :all may be given to indicate that access is given to all actions if the rule matches. Actions will be expanded using the aliases defined in Config.action_aliases. The expansion operation is not recursive.

Returns:

  • (PermitRule)

    the rule that was created for the parameters.

Raises:



82
83
84
85
86
87
# File 'lib/permit/permit_rules.rb', line 82

def allow(roles, options = {})
  actions = options.delete(:to)
  rule = PermitRule.new(roles, options)
  index_rule_by_actions @action_allow_rules, actions, rule
  return rule
end

- (PermitRule) deny(roles, options = {})

Adds an deny rule for the given actions to the collection.

Examples:

Deny a person that is a member of a project from :show

deny :person, :who => :is_member, :of => :project, :from => :show

Deny a person with either of the named roles for a resource from writing.

deny [:project_admin, :project_manager], :of => :project, :from => :write

Parameters:

  • roles (Symbol, <Symbol>)

    the role(s) that the rule will apply to.

  • options (Hash) (defaults to: {})

    the options used to build the rule.

Options Hash (options):

  • :who (Symbol)

    the method to call on the target resource.

  • :that (Symbol)

    alias for :who

  • :of (Symbol)

    the name of the instance variable holding the target resource. If set to :any then the match will apply to a person that has a matching role authorization for any resource. If not given, or set to nil, then the match will apply to a person that has a matching role authorization for a nil resource. :any/nil functionality only applies when using named roles. (see Permit::NamedRoles).

  • :on (Symbol)

    alias for :of

  • :if (Symbol, String, Proc)

    code to evaluate at the end of the match if it is still valid. If it returns false, the rule will not match. The proc or method called, will be passed the current subject being matched, and the binding being used.

  • :unless (Symbol, String, Proc)

    code to evaluate at the end of the match if it is still valid. If it returns true, the rule will not match. The proc or method called, will be passed the current subject being matched, and the binding being used.

  • :from (Symbol, <Symbol>)

    the action(s) to deny access to if this rule matches. :all may be given to indicate that access is denied to all actions if the rule matches. Actions will be expanded using the aliases defined in Config.action_aliases. The expansion operation is not recursive.

Returns:

  • (PermitRule)

    the rule that was created for the parameters.

Raises:



123
124
125
126
127
128
# File 'lib/permit/permit_rules.rb', line 123

def deny(roles, options = {})
  actions = options.delete(:from)
  rule = PermitRule.new(roles, options)
  index_rule_by_actions @action_deny_rules, actions, rule
  return rule
end

- (true, false) permitted?(person, action, context_binding)

Determines if the person is permitted on the specified action by first evaluating deny rules, and then allow rules. If the :default_access option is set then its value will be used instead of the value from Permit::Config#default_access.

Parameters:

  • person (permit_person)

    the person to check for authorization

  • action (Symbol)

    the action to check for authorization on.

  • context_binding (Binding)

    the binding to use to locate the resource and/or process if/unless constraints.

Returns:

  • (true, false)

    true if the person is permitted on the given action, false otherwise.

Raises:



33
34
35
36
37
38
39
40
41
42
# File 'lib/permit/permit_rules.rb', line 33

def permitted?(person, action, context_binding)
  # Denial takes priority over allow
  return false if has_action_rule_match?(:deny, @action_deny_rules, person, action, context_binding)

  return true if has_action_rule_match?(:allow, @action_allow_rules, person, action, context_binding)

  # Default to no access if no rules match
  default_access = (@options[:default_access] || Permit::Config.default_access)
  return (default_access == :allow ? true : false)
end