Need help with canary?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

cpjk
449 Stars 54 Forks MIT License 238 Commits 9 Opened issues

Description

:hatching_chick: Elixir authorization and resource-loading library for Plug applications.

Services available

!
?

Need anything else?

Contributors list

No Data

Canary (Notice: This project is not actively maintained)

Build Status Hex pm

An authorization library in Elixir for Plug applications that restricts what resources the current user is allowed to access, and automatically loads resources for the current request.

Inspired by CanCan for Ruby on Rails.

Read the docs

Installation

For the latest master:

defp deps do
  {:canary, github: "cpjk/canary"}
end

For the latest release:

defp deps do
  {:canary, "~> 1.1.1"}
end

Then run

mix deps.get
to fetch the dependencies.

Usage

Canary provides three functions to be used as plugs to load and authorize resources:

load_resource/2
,
authorize_resource/2
, and
load_and_authorize_resource/2
.

load_resource/2
and
authorize_resource/2
can be used by themselves, while
load_and_authorize_resource/2
combines them both.

In order to use Canary, you will need, at minimum:

  • A Canada.Can protocol implementation (a good place would be

    lib/abilities.ex
    )
  • An Ecto record struct containing the user to authorize in

    conn.assigns.current_user
    (the key can be customized - see https://github.com/cpjk/canary#overriding-the-default-user).
  • Your Ecto repo specified in your

    config/config.exs
    :
    config :canary, repo: YourApp.Repo

Then, just

import Canary.Plugs
in order to use the plugs. In a Phoenix app the best place would probably be inside
controller/0
in your
web/web.ex
, in order to make the functions available in all of your controllers.

load_resource/2

Loads the resource having the id given in

conn.params["id"]
from the database using the given Ecto repo and model, and assigns the resource to
conn.assigns.
, where
resource_name
is inferred from the model name.

For example,

plug :load_resource, model: Project.Post

Will load the

Project.Post
having the id given in
conn.params["id"]
through
YourApp.Repo
, into
conn.assigns.post

authorize_resource/2

Checks whether or not the

current_user
for the request can perform the given action on the given resource and assigns the result (true/false) to
conn.assigns.authorized
. It is up to you to decide what to do with the result.

For Phoenix applications, Canary determines the action automatically.

For non-Phoenix applications, or to override the action provided by Phoenix, simply ensure that

conn.assigns.canary_action
contains an atom specifying the action.

In order to authorize resources, you must specify permissions by implementing the Canada.Can protocol for your

User
model (Canada is included as a light weight dependency).

loadandauthorize_resource/2

Authorizes the resource and then loads it if authorization succeeds. Again, the resource is loaded into

conn.assigns.
.

In the following example, the

Post
with the same
user_id
as the
current_user
is only loaded if authorization succeeds.

Usage Example

Let's say you have a Phoenix application with a

Post
model, and you want to authorize the
current_user
for accessing
Post
resources.

Let's suppose that you have a file named

lib/abilities.ex
that contains your Canada authorization rules like so:
defimpl Canada.Can, for: User do
  def can?(%User{ id: user_id }, action, %Post{ user_id: user_id })
    when action in [:show], do: true

def can?(%User{ id: user_id }, _, _), do: false end

and in your

web/router.ex:
you have:
get "/posts/:id", PostController, :show
delete "/posts/:id", PostController, :delete

To automatically load and authorize on the

Post
having the
id
given in the params, you would add the following plug to your
PostController
:
plug :load_and_authorize_resource, model: Post

In this case, on

GET /posts/12
authorization succeeds, and the
Post
specified by
conn.params["id]
will be loaded into
conn.assigns.post
.

However, on

DELETE /posts/12
, authorization fails and the
Post
resource is not loaded.

Excluding actions

To exclude an action from any of the plugs, pass the

:except
key, with a single action or list of actions.

For example,

Single action form:

plug :load_and_authorize_resource, model: Post, except: :show

List form:

plug :load_and_authorize_resource, model: Post, except: [:show, :create]

Authorizing only specific actions

To specify that a plug should be run only for a specific list of actions, pass the

:only
key, with a single action or list of actions.

For example,

Single action form:

plug :load_and_authorize_resource, model: Post, only: :show

List form:

plug :load_and_authorize_resource, model: Post, only: [:show, :create]

Note: Passing both

:only
and
:except
to a plug is invalid. Canary will simply pass the
Conn
along unchanged.

Overriding the default user

Globally, the default key for finding the user to authorize can be set in your configuration as follows:

config :canary, current_user: :some_current_user

In this case, canary will look for the current user record in

conn.assigns.some_current_user
.

The current user key can also be overridden for individual plugs as follows:

plug :load_and_authorize_resource, model: Post, current_user: :current_admin

Specifying resource_name

To specify the name under which the loaded resource is stored, pass the

:as
flag in the plug declaration.

For example,

plug :load_and_authorize_resource, model: Post, as: :new_post

will load the post into

conn.assigns.new_post

Preloading associations

Associations can be preloaded with

Repo.preload
by passing the
:preload
option with the name of the association:
plug :load_and_authorize_resource, model: Post, preload: :comments

Non-id actions

For the

:index
,
:new
, and
:create
actions, the resource passed to the
Canada.Can
implementation should be the module name of the model rather than a struct.

For example, when authorizing access to the

Post
resource,

you should use

def can?(%User{}, :index, Post), do: true

instead of

def can?(%User{}, :index, %Post{}), do: true

You can specify additional actions for which Canary will authorize based on the model name, by passing the

non_id_actions
opt to the plug.

For example,

elixir
plug :authorize_resource, model: Post, non_id_actions: [:find_by_name]

Implementing Canada.Can for an anonymous user

You may wish to define permissions for when there is no logged in current user (when

conn.assigns.current_user
is
nil
). In this case, you should implement
Canada.Can
for
nil
like so:
defimpl Canada.Can, for: Atom do
  # When the user is not logged in, all they can do is read Posts
  def can?(nil, :show, %Post{}), do: true
  def can?(nil, _, _), do: false
end

Nested associations

Sometimes you need to load and authorize a parent resource when you have a relationship between two resources and you are creating a new one or listing all the children of that parent. By specifying the

:persisted
option with
true
you can load and/or authorize a nested resource. Specifying this option overrides the default loading behavior of the
:index
,
:new
, and
:create
actions by loading an individual resource. It also overrides the default authorization behavior of the
:index
,
:new
, and
create
actions by loading a struct instead of a module name for the call to
Canada.can?
.

For example, when loading and authorizing a

Post
resource which can have one or more
Comment
resources, use
plug :load_and_authorize_resource, model: Post, id_name: "post_id", persisted: true, only: [:create]

to load and authorize the parent

Post
resource using the
post_id
in /posts/:post_id/comments before you create the
Comment
resource using its parent.

Specifing database field

You can tell Canary to search for a resource using a field other than the default

:id
by using the
:id_field
option. Note that the specified field must be able to uniquely identify any resource in the specified table.

For example, if you want to access your posts using a string field called

slug
, you can use
plug :load_and_authorize_resource, model: Post, id_name: "slug", id_field: "slug"

to load and authorize the resource

Post
with the slug specified by
conn.params["slug"]
value.

If you are using Phoenix, your

web/router.ex
should contain something like:
resources "/posts", PostController, param: "slug"

Then your URLs will look like:

/posts/my-new-post

instead of

/posts/1

Handling unauthorized actions

By default, when an action is unauthorized, Canary simply sets

conn.assigns.authorized
to
false
. However, you can configure a handler function to be called when authorization fails. Canary will pass the
Plug.Conn
to the given function. The handler should accept a
Plug.Conn
as its only argument, and should return a
Plug.Conn
.

For example, to have Canary call

Helpers.handle_unauthorized/1
:
config :canary, unauthorized_handler: {Helpers, :handle_unauthorized}

Handling resource not found

By default, when a resource is not found, Canary simply sets the resource in

conn.assigns
to
nil
. Like unauthorized action handling , you can configure a function to which Canary will pass the
conn
when a resource is not found:
config :canary, not_found_handler: {Helpers, :handle_not_found}

You can also specify handlers on an individual basis (which will override the corresponding configured handler, if any) by specifying the corresponding

opt
in the plug call:
plug :load_and_authorize_resource Post,
  unauthorized_handler: {Helpers, :handle_unauthorized},
  not_found_handler: {Helpers, :handle_not_found}

Tip: If you would like the request handling to stop after the handler function exits, e.g. when redirecting, be sure to call

Plug.Conn.halt/1
within your handler like so:
def handle_unauthorized(conn) do
  conn
  |> put_flash(:error, "You can't access that page!")
  |> redirect(to: "/")
  |> halt
end

Note: If both an

:unauthorized_handler
and a
:not_found_handler
are specified for
load_and_authorize_resource
, and the request meets the criteria for both, the
:unauthorized_handler
will be called first.

License

MIT License. Copyright 2016 Chris Kelly.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.