class Rails::Auth::ACL

Route-based access control lists

Constants

DEFAULT_MATCHERS

Matchers available by default in ACLs

Attributes

resources[R]

Public Class Methods

from_yaml(yaml, **args) click to toggle source

Create a Rails::Auth::ACL from a YAML representation of an ACL

@param [String] :yaml serialized YAML to load an ACL from

# File lib/rails/auth/acl.rb, line 20
def self.from_yaml(yaml, **args)
  require "yaml"
  new(
    if YAML::VERSION >= "4.0"
      YAML.safe_load(yaml, aliases: true)
    else
      YAML.safe_load(yaml, [], [], true)
    end,
    **args
  )
end
new(acl, matchers: {}) click to toggle source

@param [Array<Hash>] :acl Access Control List configuration @param [Hash] :matchers authorizers use with this ACL

# File lib/rails/auth/acl.rb, line 35
def initialize(acl, matchers: {})
  raise TypeError, "expected Array for acl, got #{acl.class}" unless acl.is_a?(Array)

  @resources = []

  acl.each do |entry|
    raise TypeError, "expected Hash for acl entry, got #{entry.class}" unless entry.is_a?(Hash)

    resources = entry["resources"]
    raise ParseError, "no 'resources' key present in entry: #{entry.inspect}" unless resources

    matcher_instances = parse_matchers(entry, matchers.merge(DEFAULT_MATCHERS))

    resources.each do |resource|
      @resources << Resource.new(resource, matcher_instances).freeze
    end
  end

  @resources.freeze
end

Public Instance Methods

match(env) click to toggle source

Match the Rack environment against the ACL, checking all matchers

@param [Hash] :env Rack environment

@return [String, nil] name of the first matching matcher, or nil if unauthorized

# File lib/rails/auth/acl.rb, line 62
def match(env)
  @resources.each do |resource|
    matcher_name = resource.match(env)
    return matcher_name if matcher_name
  end

  nil
end
matching_resources(env) click to toggle source

Find all resources that match the ACL. Matchers are NOT checked, instead only the initial checks for the “resources” section of the ACL are performed. Use the ‘#match` method to validate matchers.

This method is intended for debugging AuthZ failures. It can find all resources that match the given request so the corresponding matchers can be introspected.

@param [Hash] :env Rack environment

@return [Array<Rails::Auth::ACL::Resource>] matching resources

# File lib/rails/auth/acl.rb, line 83
def matching_resources(env)
  @resources.find_all { |resource| resource.match!(env) }
end

Private Instance Methods

parse_matchers(entry, matchers) click to toggle source
# File lib/rails/auth/acl.rb, line 89
def parse_matchers(entry, matchers)
  matcher_instances = {}

  entry.each do |name, options|
    next if name == "resources"

    matcher_class = matchers[name.to_sym]
    raise ArgumentError, "no matcher for #{name}" unless matcher_class
    raise TypeError, "expected Class for #{name}" unless matcher_class.is_a?(Class)

    matcher_instances[name.freeze] = matcher_class.new(options.freeze).freeze
  end

  matcher_instances.freeze
end