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
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 connuser
(term) - override the current user picked up from connpolicy
(atom) - override the policy determined from the term
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 connuser
(term) - override the current user picked up from connpolicy
(atom) - override the policy determined from the termerror_message
(String) - override the default error messageerror_status
(integer) - override the default HTTP error code
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
Manually marks a conn
as successfully authorized.
This is mainly used to satisfy verify_authorized/2
when authorization is performed outside of Bodyguard.
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 connpolicy
(atom) - override the policy determined from the term
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
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 connuser
(term) - override the current user picked up from connpolicy
(atom) - override the policy determined from the term
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 messageerror_status
(integer) - override the default HTTP error code