Action Policy Documentation

Action Policy is a flexible authorization layer for Ruby applications. It focuses on answering the single question: How to verify access?

Unlike some other authorization libraries, Action Policy does not force a specific model (like roles or permissions) on you. It provides the tools to implement your own authorization logic. It is designed to be Rails-free but offers seamless integration and specific extensions for Rails applications.

Action Policy is an authorization framework for Ruby and Rails designed to manage access control in a structured and maintainable way. Key capabilities include:

• Policy Classes: Defining authorization logic using rule methods.
• Pre-checks and Aliases: Using pre-checks to keep policy logic DRY (Don't Repeat Yourself) and creating aliases for common rules.
• Scoping: Restricting record visibility so users only see the data they are authorized to access.
• Testing: Utilizing built-in test helpers to verify policies and authorization logic.
• Failure Reasons: Providing specific feedback to users explaining why an action was denied.

The HelpDesk application is a support ticket management system used in this tutorial to demonstrate Action Policy. It features three distinct user roles:

• Alice (Customer): Submits and tracks support tickets.
• Bob (Agent): Handles and responds to tickets.
• Charlie (Admin): Full access to manage everything.

In its initial state, the application lacks access controls, meaning any user can perform any action (edit, delete, read internal comments, etc.). This serves as the baseline for implementing authorization with Action Policy.

Beyond the core tutorial, Action Policy provides several advanced features for production-grade applications:

• Caching: Cache policy results to avoid redundant checks and improve performance.
• Namespaces: Organize policies into namespaces (e.g., Admin::TicketPolicy) to manage complexity in large applications.
• Instrumentation: Hook into the policy evaluation lifecycle for monitoring and observability.
• GraphQL integration: Use Action Policy to enforce authorization within GraphQL APIs.

Action Policy is designed to address common limitations in other authorization frameworks through the following features:

• Performance: Includes multiple out-of-the-box caching strategies to minimize overhead (especially for rules involving database queries) and built-in instrumentation to monitor and detect bottlenecks.
• Composition & Customization: Built using standard Ruby classes and modules with minimal magic. You can use only the features you need or extend functionality easily. Authorization can be added anywhere in your code, not just in controllers.
• Code Organization: Supports namespaces to organize different authorization strategies and pre_checks to make business logic rules more readable.
• Advanced Capabilities: Provides built-in support for testability, i18n integrations, and actionable errors.

Since scopes are transformed into class instance methods, they support standard Ruby inheritance. You can chain scopes from a parent policy by using the super keyword within the scope block.

Important: You must explicitly pass the argument to super (e.g., super(relation)); using super with implicit arguments is not supported because scopes are defined using define_method internally.

class ApplicationPolicy < ActionPolicy::Base
  scope_for :relation do |relation|
    relation.where(account_id: account.id)
  end
end

class PostPolicy < ApplicationPolicy
  scope_for :relation do |relation|
    super(relation).published
  end
end

Rule-level memoization ensures that if the same rule method is called multiple times on the same policy instance, the result is returned immediately after the first execution.

This is only available if your policy inherits from ActionPolicy::Base or includes ActionPolicy::Policy::CachedApply in your ApplicationPolicy.

The lookup chain is an array of probes (lambdas) used to find the appropriate policy for a resource. The lookup process follows a simple sequential logic:

1. Call the first probe in the array.
2. If the probe returns a non-nil value, that value is used as the policy and the process stops.
3. If the probe returns nil, the process moves to the next probe in the chain.

If the entire chain is exhausted without a non-nil return, Action Policy typically raises an ActionPolicy::NotFound error.