bodyguard v0.6.0 Bodyguard.Controller
Include this module in your Phoenix/Plug controllers to gain wrapper functions for 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(Plug.Conn.t, term, keyword) :: {:ok, Plug.Conn.t} | {:error, :unauthorized} | {:error, term}
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 returns
{: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 fromconn
user
(term) - override the current user picked up fromconn
policy
(atom) - override the policy determined fromterm
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 fromconn
user
(term) - override the current user picked up fromconn
policy
(atom) - override the policy determined fromterm
error_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.
permitted_attributes(Plug.Conn.t, term, keyword) :: [atom]
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.
If the scope
argument is a struct, module name, or an Ecto query, the schema
can be automatically inferred. Otherwise, you must pass the policy
option to
explicitly determine the policy.
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