bodyguard v0.5.0 Bodyguard.Controller

Convenience functions for Phoenix/Plug controller authorization.

Summary

Functions

Authorizes the controller action for the current user

Similar to authorize/3 but returns a modified conn on success and raises Bodyguard.NotAuthorizedError on failure

Retrieves the authenticated current user, previously assigned to the conn

Manually marks a conn as successfully authorized

Whitelists parameters based on the current user

A plug to set controller-wide authorization options

Scopes the current resource based on the action and user

Raises Bodyguard.NotAuthorizedError if the conn tries to send without any authorization being run

Functions

authorize(conn, term, opts \\ [])

Authorizes the controller action for the current user.

On success, returns {:ok, conn} with a modified conn that is marked as authorized – see verify_authorized/2.

On failure, returns {:error, :unauthorized} by default, or passes through {:error, reason} if the policy function explicitly returns that.

def index(conn, _params) do
  case authorize(conn, Post) do
    {:ok, conn} -> 
      # ...
    {:error, reason} ->
      # ...
  end
end

def show(conn, %{"id" => id}) do
  post = Repo.get(Post, id)
  case authorize(conn, post) do
    {:ok, conn} ->
      # ...
    {:error, reason} ->
      # ...
  end
end

Available options:

  • action (atom) - override the controller action picked up from conn
  • user (term) - override the current user picked up from conn
  • policy (atom) - override the policy determined from the term
authorize!(conn, term, opts \\ [])

Similar to authorize/3 but returns a modified conn on success and raises Bodyguard.NotAuthorizedError on failure.

Available options:

  • action (atom) - override the controller action picked up from conn
  • user (term) - override the current user picked up from conn
  • policy (atom) - override the policy determined from the term
  • error_message (String) - override the default error message
  • error_status (integer) - override the default HTTP error code
get_current_user(conn)

Retrieves the authenticated current user, previously assigned to the conn.

By default, the assign key is :current_user, but this may be changed with the :current_user configuration option:

config :bodyguard, current_user: :my_custom_assign_key
mark_authorized(conn)

Manually marks a conn as successfully authorized.

This is mainly used to satisfy verify_authorized/2 when authorization is performed outside of Bodyguard.

permitted_attributes(conn, term, opts \\ [])

Whitelists parameters based on the current user.

The result can be passed into Ecto.Changeset.cast/3 if you are constructing the changeset in your controller. If you are using service modules or constructing a changeset elsewhere, then you don’t need this function – call Bodyguard.permitted_attributes/3 directly instead.

Available options:

  • user (term) - override the current user picked up from conn
  • policy (atom) - override the policy determined from the term
put_bodyguard_options(conn, opts)

A plug to set controller-wide authorization options.

This is a controller plug to apply shared authorization options to all its actions. Any per-action options will be merged with these default options.

These defaults do not apply to the view helpers.

For example, to specify a custom policy module for a controller:

defmodule MyApp.DraftController do
  use MyApp.Web, :controller

  plug :put_bodyguard_options, policy: Post.DraftPolicy

  # Authorization checks in this controller will use
  # Post.DraftPolicy unless otherwise specified
end
scope(conn, term, opts \\ [])

Scopes the current resource based on the action and user.

def index(conn, _params) do
  {:ok, conn} = authorize(conn, Post)
  posts = scope(conn, Post) |> Repo.all
  # ...
end

def show(conn, %{id: id}) do
  post = scope(conn, Post) |> Repo.get(id)
  {:ok, conn} = authorize(conn, post)
  # ...
end

Available options:

  • action (atom) - override the controller action picked up from conn
  • user (term) - override the current user picked up from conn
  • policy (atom) - override the policy determined from the term
verify_authorized(conn, opts \\ [])

Raises Bodyguard.NotAuthorizedError if the conn tries to send without any authorization being run.

This is mainly used as a function plug on your controller.

Available options:

  • error_message (String) - override the default error message
  • error_status (integer) - override the default HTTP error code