How to handle authorization failures in Phoenix controllers with Bodyguard?

Use the action_fallback macro to define a fallback controller that catches {:error, :unauthorized} results and renders appropriate HTTP status codes, as shown in the FallbackController example. This keeps error handling centralized and clean.

Does Bodyguard support LiveView authorization out of the box?

Yes, Bodyguard can be used in LiveView mount/3 and handle_event/3 callbacks by calling Bodyguard.permit functions directly. The README references Phoenix LiveView's security model for best practices on integrating checks.

Bodyguard vs Canary for Phoenix apps?

Bodyguard focuses on context-based policies and schema scoping with a convention-over-configuration approach, while Canary offers more declarative rules and Ecto integration. Choose Bodyguard for tighter integration with business logic; Canary if you prefer resource-centric authorization.

How to implement role-based access control using Bodyguard?

Define authorize/3 callbacks in your context modules that pattern-match on user roles, like the admin example in the README. You'll need to manage roles in your user schema and write custom logic for each action, as Bodyguard doesn't provide role helpers.

Can Bodyguard scope Ecto queries automatically?

Yes, by implementing the Bodyguard.Schema behaviour on your Ecto schemas and using Bodyguard.scope/4 in queries. This automatically applies scope/3 callbacks to filter results, but you must define the scoping logic per schema.

Is Bodyguard suitable for large, complex applications?

It can scale with careful organization, such as delegating policies to separate modules, but the lack of built-in permission inheritance or dynamic updates might require additional layers of abstraction in very complex systems.

bodyguard — Phoenix Authorization Conventions

What is bodyguard?

Bodyguard is an authorization library for Phoenix applications that provides simple conventions for implementing permission checks. It solves the problem of scattered authorization logic by centralizing policy definitions within context modules while supporting checks from controllers, views, sockets, and tests.

Target Audience

Elixir developers building Phoenix applications who need a clean, maintainable way to implement authorization rules across their business logic and web interfaces.

Value Proposition

Developers choose Bodyguard for its convention-over-configuration approach that keeps authorization logic close to business contexts, its seamless integration with Phoenix components, and its support for both action-based policies and data-scoping patterns.

Simple authorization conventions for Phoenix apps

Use Cases

Best For

Implementing role-based access control in Phoenix applications
Adding authorization checks to Phoenix contexts and controllers
Scoping database queries based on user permissions
Handling authorization failures with Phoenix fallback controllers
Securing LiveView components with permission checks
Testing authorization logic in Elixir applications

Not Ideal For

Projects using Elixir without Phoenix, as it's tightly integrated with Phoenix's context and controller layers
Teams needing dynamic, database-driven permissions that change at runtime without code deploys
Applications requiring hierarchical or inheritance-based permission models, like multi-tenant systems with complex role hierarchies
Developers preferring declarative YAML/JSON configuration over code-based policy definitions

Pros & Cons

Pros

Context-Integrated Policies

Authorization logic is embedded directly in Phoenix context modules, keeping business rules close to the code that enforces them, as shown in the blog example where MyApp.Blog implements Bodyguard.Policy.

Schema Scoping for Queries

The Bodyguard.Schema behaviour automatically filters database results based on user permissions, preventing data leaks without manual query adjustments, demonstrated in the Post.scope/3 callback.

Seamless Phoenix Stack Support

It works out-of-the-box with controllers via action_fallback, LiveView mount/handle_event, plugs for pipeline checks, and includes testing utilities, ensuring consistent authorization across the entire application.

Clean Delegation Patterns

Policies can be separated into dedicated modules using defdelegate, allowing for better code organization while maintaining the same interface, as mentioned in the policy delegation section.

Cons

No Built-in Role Management

Bodyguard only provides the policy enforcement layer; you must implement role definitions, permission storage, and dynamic updates yourself, which adds overhead for complex authorization needs.

Potential Policy Duplication

Since policies are defined per context, similar rules across different contexts (e.g., user management and blog posts) can lead to code repetition without a central way to share logic.

Complex Fallback Setup

Handling authorization failures requires manual configuration of fallback controllers and plug options, which the README admits can be tricky, especially for beginners integrating with Phoenix pipelines.

Frequently Asked Questions

What is bodyguard?

Target Audience

Elixir developers building Phoenix applications who need a clean, maintainable way to implement authorization rules across their business logic and web interfaces.

Value Proposition

Use Cases

Best For

Implementing role-based access control in Phoenix applications
Adding authorization checks to Phoenix contexts and controllers
Scoping database queries based on user permissions
Handling authorization failures with Phoenix fallback controllers
Securing LiveView components with permission checks
Testing authorization logic in Elixir applications

Not Ideal For

Projects using Elixir without Phoenix, as it's tightly integrated with Phoenix's context and controller layers
Teams needing dynamic, database-driven permissions that change at runtime without code deploys
Applications requiring hierarchical or inheritance-based permission models, like multi-tenant systems with complex role hierarchies
Developers preferring declarative YAML/JSON configuration over code-based policy definitions

Pros & Cons

Pros

Context-Integrated Policies

Schema Scoping for Queries

The Bodyguard.Schema behaviour automatically filters database results based on user permissions, preventing data leaks without manual query adjustments, demonstrated in the Post.scope/3 callback.

Seamless Phoenix Stack Support

Clean Delegation Patterns

Policies can be separated into dedicated modules using defdelegate, allowing for better code organization while maintaining the same interface, as mentioned in the policy delegation section.

Cons

No Built-in Role Management

Bodyguard only provides the policy enforcement layer; you must implement role definitions, permission storage, and dynamic updates yourself, which adds overhead for complex authorization needs.

Potential Policy Duplication

Since policies are defined per context, similar rules across different contexts (e.g., user management and blog posts) can lead to code repetition without a central way to share logic.

Complex Fallback Setup

Frequently Asked Questions

bodyguard

What is bodyguard?

Overview

Use Cases

Best For

Not Ideal For

Pros & Cons

Pros

Cons

Frequently Asked Questions

Related Projects

Found a gem we're missing?

bodyguard

What is bodyguard?

Overview

Use Cases

Best For

Not Ideal For

Pros & Cons

Pros

Cons

Frequently Asked Questions

Related Projects

Found a gem we're missing?