# Gardien

Authorization for Phoenix projects.

## Installation

Add gardien to your list of dependencies in `mix.exs`:

    def deps do
      [{:gardien, "~> 0.0.1"}]
    end

Then run mix `deps.get` to fetch the dependencies.

## Configuration

### `gardien_user` - optional
`gardien_user` - user performing some action on a resource.
**By default Gardien will try to extract user from `conn.assigns`
using `current_user` key.** In case you want to change this behaviour you can
configure `gardien_user` as follows:

    # specified as a key that can be used to extract user from `conn.assigns`, e.g
    # %Plug.Conn{assigns: %{admin: user}}
    config :gardien,
      gardien_user: :admin

    # as a function that takes `conn` as an argument and returns user
    config :gardien,
      gardien_user: fn(conn) -> conn.assigns.current_user end

    # as a remote function in {Module, atom} format
    config :gardien,
      gardien_user: {MyHelpers, :gardien_user}

## `Gardien.Policy` protocol

`Gardien.Policy` protocol should be
implemented for each `resource` that needs to be authorized!
This protocol defines `authorize?(resource, user, action)` function and
is used by Gardien to verify whether `user` is allowed to perform some `action`
on a given `resource`.

**Important:** `Gardien.Policy.authorize?/3` **should return `true` or `false`.**

**Note:** Gardien comes with a `Gardien.Authorize` module, that can be `use`-d
in order to implement a more descriptive policy.

`Gardien.Policy` implementation example (with `Gardien.Authorize`):

    defimpl Gardien.Policy, for: MyApplication.Post do
      use Gardien.Authorize

      def new(_resource, _user) do
        true
      end

      def edit(resource, user) do
        user.id == resource.user_id
      end

      def update(resource, user) do
        edit(resource, user)
      end

      ...
    end

In case you're building a closed system, where only logged in users are able
to do anything, you can define your own Authorize:

    defmodule MyApplication.Authorize do
      defmacro __using__(_opts) do
        def authorize?(_resource, user, _action) when is_nil(user), do
          do: false
        def authorize?(resource, user, action),
          do: apply(__MODULE__, action, [resource, user])
      end
    end

    defimpl Gardien.Policy, for: MyApplication.Post do
      use MyApplication.Authorize

      ...
    end

## TODO: describe available authorization functions

## TODO: add examples