canary v0.10.4 Canary.Plugs
Plug functions for loading and authorizing resources for the current request.
Plugs all store data in conn.assigns (in Phoenix applications, keys in conn.assigns can be accessed with @key_name
in both views and controllers)
In order to use the plug functions, you must use Canary
.
You must also specify the Ecto repo to use in your configuration:
config :canary, repo: Project.Repo
If you wish, you may also specify the key where Canary will look for the current user record to authorize against:
config :canary, current_user: :some_current_user
Summary
Functions
Authorize the current user for the given resource
Authorize the given resource and then load it if authorization succeeds
Load the given resource
Functions
Authorize the current user for the given resource.
In order to use this function,
1) conn.assigns[Application.get_env(:canary, :current_user, :current_user)]
must be an ecto
struct representing the current user
2) conn.private
must be a map (this should not be a problem unless you explicitly modified it)
If authorization succeeds, sets conn.assigns.authorized
to true.
If authorization fails, sets conn.assigns.authorized
to false.
For the :index
, :new
, and :create
actions, the resource in the Canada.Can
implementation
should be the module name of the model rather than a struct.
For example:
use
def can?(%User{}, :index, Post), do: true
instead of
def can?(%User{}, :index, %Post{}), do: true
Required opts:
:model
- Specifies the module name of the model to authorize access to
Optional opts:
:only
- Specifies which actions to authorize:except
- Specifies which actions for which to skip authorization:preload
- Specifies association(s) to preload:id_name
- Specifies the name of the id inconn.params
, defaults to “id”
Examples:
plug :authorize_resource, model: Post
plug :authorize_resource, model: User, preload: :posts
plug :authorize_resource, model: User, only: [:index, :show], preload: :posts
Authorize the given resource and then load it if authorization succeeds.
If the resource cannot be loaded or authorization fails, conn.assigns.resource_name is set to nil.
The result of the authorization (true/false) is assigned to conn.assigns.authorized.
Also, see the documentation for load_resource/2 and authorize_resource/2.
Required opts:
:model
- Specifies the module name of the model to load resources from
Optional opts:
:as
- Specifies theresource_name
to use:only
- Specifies which actions to authorize:except
- Specifies which actions for which to skip authorization:preload
- Specifies association(s) to preload:id_name
- Specifies the name of the id inconn.params
, defaults to “id”
Examples:
plug :load_and_authorize_resource, model: Post
plug :load_and_authorize_resource, model: User, preload: :posts, as: :the_user
plug :load_and_authorize_resource, model: User, only: [:index, :show], preload: :posts, as: :person
plug :load_and_authorize_resource, model: User, except: [:destroy]
Load the given resource.
Load the resource with id given by conn.params["id"]
(or conn.params[opts[:id_name]]
if opts[:id_name]
is specified)
and ecto model given by opts[:model]
into conn.assigns.resource_name
.
resource_name
is either inferred from the model name or specified in the plug declaration with the :as
key.
To infer the resource_name
, the most specific(right most) name in the model’s
module name will be used, converted to underscore case.
For example, load_resource model: Some.Project.BlogPost
will load the resource into
conn.assigns.blog_post
If the resource cannot be fetched, conn.assigns.resource_name
is set
to nil.
If the action is :index
, all records from the specified model will be loaded.
Currently, :new
and :create
actions are ignored, and conn.assigns.resource_name
will be set to nil for these actions.
Required opts:
:model
- Specifies the module name of the model to load resources from
Optional opts:
:as
- Specifies theresource_name
to use:only
- Specifies which actions to authorize:except
- Specifies which actions for which to skip authorization:preload
- Specifies association(s) to preload:id_name
- Specifies the name of the id inconn.params
, defaults to “id”
Examples:
plug :load_resource, model: Post
plug :load_resource, model: User, preload: :posts, as: :the_user
plug :load_resource, model: User, only: [:index, :show], preload: :posts, as: :person
plug :load_resource, model: User, except: [:destroy]