Bodyguard Authorization Library

An Action is a composable data structure used to build up authorization parameters throughout a request lifecycle before executing a final task (the job).

It follows this general lifecycle:

1. Initialize: Create an action with a context using act(context).
2. Configure: Add the user (put_user/2), custom policies (put_policy/2), or extra parameters (assign/3).
3. Authorize: Perform the check using permit/3 or permit!/3. This step uses the provided policy to validate the user against a specific action name.
4. Execute: Run the task using run/1 or run!/1.

If authorization succeeds, the job is executed. If it fails, Bodyguard will either execute a provided fallback function or return/raise the authorization error.

import Bodyguard.Action
      alias MyApp.Blog

act(Blog)
      |> put_user(get_current_user())
      |> put_policy(Blog.SomeSpecialPolicy)
      |> assign(:drafts, true)
      |> permit(:list_posts, drafts: true)
      |> put_job(fn action ->
        Blog.list_posts(action.user, drafts_only: action.assigns.drafts)
      end)
      |> put_fallback(fn _action -> {:error, :not_found} end)
      |> run()

The Bodyguard.Plug.Authorize plug performs authorization checks within a Plug pipeline (such as a Phoenix router or controller). It evaluates a policy against a specific action, a user, and optional parameters.

If authorization fails:

1. Default behavior: It raises a Bodyguard.NotAuthorizedError directly to the router.
2. With :fallback: If a :fallback option is provided (a module acting as a plug or controller), the plug calls the fallback with the error and then halts the connection pipeline.

# Raise on failure
plug Bodyguard.Plug.Authorize,
  policy: MyApp.Blog,
  action: &action_name/1,
  user: {MyApp.Authentication, :current_user}

# Fallback on failure
plug Bodyguard.Plug.Authorize,
  policy: MyApp.Blog,
  action: &action_name/1,
  user: {MyApp.Authentication, :current_user},
  fallback: MyAppWeb.FallbackController

# Params as a function
plug Bodyguard.Plug.Authorize,
  policy: MyApp.Blog,
  action: &action_name/1,
  user: {MyApp.Authentication, :current_user},
  params: &get_params/1

Testing authorization is done using the top-level Bodyguard API. You can assert against successful permits, failures, and the specific Bodyguard.NotAuthorizedError raised by permit/4.

Key functions for testing:

• Bodyguard.permit(policy, action, user, params): Returns :ok or {:error, reason}.
• Bodyguard.permit?(policy, action, user, params): Returns true or false.
• Bodyguard.permit!(policy, action, user, params): Raises Bodyguard.NotAuthorizedError on failure.

assert :ok == Bodyguard.permit(MyApp.Blog, :successful_action, user)
assert {:error, :unauthorized} == Bodyguard.permit(MyApp.Blog, :failing_action, user)

assert Bodyguard.permit?(MyApp.Blog, :successful_action, user)
refute Bodyguard.permit?(MyApp.Blog, :failing_action, user)

error = assert_raise Bodyguard.NotAuthorizedError, fun ->
  Bodyguard.permit!(MyApp.Blog, :failing_action, user)
end
assert %{status: 403, message: "not authorized"} = error

You can perform authorization in the middle of a Phoenix pipeline using Bodyguard.Plug.Authorize.

Because the plug halts the pipeline on failure, you must specify the :fallback option to point to a controller (like your FallbackController) that can handle the error.

Configuration options for the plug include:

• policy: The module implementing @behaviour Bodyguard.Policy.
• action: A tuple defining the action to check (e.g., {Phoenix.Controller, :action_name}).
• user: A 1-arity getter function that accepts conn and returns the user.
• params: A 1-arity getter function that accepts conn and returns the parameters to pass to authorize/3.
• fallback: The controller to call if authorization fails.

# lib/my_app_web/controllers/post_controller.ex
module MyAppWeb.PostController do
  use MyAppWeb, :controller

  plug :get_post when action in [:show]

  plug Bodyguard.Plug.Authorize,
    policy: MyApp.Blog.Policy,
    action: {Phoenix.Controller, :action_name},
    user: {MyApp.Authentication, :current_user},
    params: {__MODULE__, :extract_post},
    fallback: MyAppWeb.FallbackController

  def show(conn, _) do
    render(conn, "show.html")
  end

  defp get_post(conn, _) do
    assign(conn, :post, MyApp.Posts.get_post!(conn.params["id"]))
  end

  def extract_post(conn), do: conn.assigns.posts
end

To define authorization rules, add @behaviour Bodyguard.Policy to a module (typically a context). You must implement the authorize(action, user, params) callback.

Callback Signature

authorize(action, user, params)

Return Values

Your callback should return one of the following to indicate the result:

• :ok or true: Permit the action.
• :error, {:error, reason}, or false: Deny the action.

Using Bodyguard.permit/4

Do not call your authorize/3 callback directly. Instead, use Bodyguard.permit/4. This helper:

1. Converts params (which may be a keyword list) into a map.
2. Coerces your callback result into a strict :ok or {:error, reason} tuple.
3. Defaults to {:error, :unauthorized} if the result is a failure.

If you want to keep policies separate from your context, you can use defdelegate to forward the authorize/3 call to a dedicated policy module.

# lib/my_app/blog/blog.ex
defmodule MyApp.Blog do
  @behaviour Bodyguard.Policy

  # Admins can update anything
  def authorize(:update_post, %{role: :admin} = _user, _post), do: :ok

  # Users can update their owned posts
  def authorize(:update_post, %{id: user_id} = _user, %{user_id: user_id} = _post), do: :ok

  # Otherwise, denied
  def authorize(:update_post, _user, _post), do: :error
end