Canary

An authorization library in Elixir for Plug and Phoenix.LiveView applications that restricts what resources the current user is allowed to access, and automatically load and assigns resources.

Inspired by CanCan for Ruby on Rails.

Read the docs

Canary 2.0.0

The master branch is for the development of Canary 2.0.0. Check out branch 1.2.x if you are looking Canary 1 (only plug authentication).

Installation

For the latest master (2.0.0-dev):

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

For the latest release:

defp deps do
  {:canary, "~> 2.0.0-dev"}
end

Then run mix deps.get to fetch the dependencies.

Quick start

Canary provides functions to be used as plugs or LiveView hooks to load and authorize resources:

load_resource, authorize_resource, authorize_controller*, and load_and_authorize_resource.

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

Available only in plug based authentication

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 assigns.current_user (the key can be customized - see more).

• Your Ecto repo specified in your config/config.exs: config :canary, repo: YourApp.Repo

For the plugs just import Canary.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.

For the liveview hooks just use Canary.Hooks. In a Phoenix app the best place would probably be inside live_view/0 in your web/web.ex, in order to make the functions available in all of your controllers.

load_resource

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

<!-- tabs-open -->

Conn Plugs example

plug :load_resource, model: Project.Post

Will load the Project.Post having the id given in conn.params["id"] through YourApp.Repo, and assign it to conn.assigns.post.

LiveView Hooks example

mount_canary :load_resource, model: Project.Post

Will load the Project.Post having the id given in params["id"] through YourApp.Repo, and assign it to socket.assigns.post

<!-- tabs-close -->

authorize_resource

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 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 assigns.canary_action contains an atom specifying the action.

For the LiveView on handle_params it uses socket.assigns.live_action as action, on handle_event it uses the event name as 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).

load_and_authorize_resource

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

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

Example for Conn Plugs

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.

Example for LiveView Hooks

In your web/router.ex: you have:

live "/posts/:id", PostLive, :show

and in your PostLive module web/live/post_live.ex:

defmodule MyAppWeb.PostLive do
  use MyAppWeb, :live_view

  def render(assigns) do
    ~H"""
    Post id: {@post.id}
    <button phx-click="delete">Delete</button>
    """
  end

  def mount(_params, _session, socket), do: {:ok, socket}

  def handle_event("delete", _params, socket) do
    # Do the action
    {:noreply, update(socket, :temperature, &(&1 + 1))}
  end
end

To automatically load and authorize on the Post having the id given in the params, you would add the following hook to your PostLive:

mount_hook :load_and_authorize_resource, model: Post

In this case, once opening /posts/12 the load_and_authorize_resource on handle_params stage will be performed. The the Post specified by params["id] will be loaded into socket.assigns.post.

However, when the delete event will be triggered, authorization fails and the Post resource is not loaded. Socket will be halted.

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

mount_canary :load_and_authorize_resource, model: Post, except: :show

List form:

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

mount_canary :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

mount_canary :load_and_authorize_resource, model: Post, only: :show

List form:

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

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

Note: Having both :only and :except in opts is invalid. Canary will raise ArgumentError "You can't use both :except and :only options"

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 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

mount_canary :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

mount_canary :load_and_authorize_resource, model: Post, as: :new_post

will load the post into 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

mount_canary :load_and_authorize_resource, model: Post, preload: :comments

Non-id actions

To authorize actions where there is no loaded resource, the resource passed to the Canada.Can implementation should be the module name of the model rather than a struct.

To authorize such actions use authorize_resource plug with required: false option

plug :authorize_resource, model: Post, only: [:index, :new, :create], required: false

mount_canary :authorize_resource, model: Post, only: [:index, :new, :create], required: false

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

Deprecated {: .warning}

The :non_id_actions is deprecated as of 2.0.0-dev and will be removed in Canary 2.1.0 Please follow the Upgrade guide to 2.0.0 for more details.

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. Depending on your authorization model you migth authorize against the parent resource or against the child.

defmodule MyAppWeb.CommentCon