Bouncer (beta)

Token-based authorization and session management for Phoenix (Elixir)

Why

I needed a way to authorize API requests to my Phoenix application. Addict didn't fit the bill since it uses Phoenix's built-in session system. Phoenix uses cookies to authorize requests but when dealing with an API, it's easier to deal with an Authorization header. Phoenix's session system also uses memory or ETS to store session data and this wouldn't work for my application which would be scaled horizontally and so would be running on multiple machines. Redis is great at solving this problem because it's crazy-fast and can be accessed by multiple machines. The ecosystem around Redis is strong so working with the session data is pretty easy.

Guardian also wouldn’t work because it uses JSON Web Tokens (JWT) as the basis for it’s authorization scheme. JWTs can work but I don’t believe it’s a better system than the traditional session-based system. JWTs don't provide a way of immediately invalidating user sessions instead relying on short token lifetimes. The ability to immediately invalidate a session is a feature that I find useful in certain situations (i.e. when a user resets their password).

Features

• Creating a session returns a token that can be used in the authorization header of each API request.
• Backed by Redis so it's able to be used in a multi-server or multi-container environment without configuring sticky sessions. Also, Redis is pretty fast.
• Simple API to create, update, and destroy session data.
• Simple API to generate, verify, and regenerate email verification or password reset tokens.

Installation

Bouncer is available in Hex, the package can be installed as:

1. Add bouncer to your list of dependencies in mix.exs:

```elixir
def deps do
  [{:bouncer, "~> 0.3.0"}]
end
```

2. Ensure bouncer is started before your application:

```elixir
def application do
  [applications: [:bouncer]]
end
```

Requirements & Configuration

Bouncer requires the Phoenix framework because it uses it's Token module to generate tokens that are used both as an Authorization header and a session key. Despite this requirement, I imagine it could be used with any Plug-based framework. Bouncer provides a plug that can be used to authorize a request for certain controllers and/or controller actions:

# This would be added near the top of a UserController for example
plug Bouncer.Plugs.Authorize when action in [:show, :update, :delete]

Bouncer only has one session store adapter so far: Redis. Bouncer uses the fantastic Redix library to interface with Redis and we've added a module called Bouncer.RedixPool that will pool connections to Redis. Here's what you would put in your environment's configuration file:

# config/dev.exs
config :bouncer,
  adapter: Bouncer.Adapters.Redis,
  redis: "redis://somehost:6379/1"

The second configuration option, redis, is not necessary if your Redis instance is on localhost and using the default port. You might want to specify a different database (i.e. redis://localhost:6379/2) in your test configuration file.

Documentation

The source is really small so reading through it should be straight-forward but the full package documentation is available at https://hexdocs.pm/bouncer.

Example of a SessionController

Here's and example of how you can use the Bouncer.Session API in your application:

# web/controllers/session_controller.ex
defmodule MyApp.SessionController do
  use MyApp.Web, :controller

  alias MyApp.User
  alias MyApp.UserView
  alias Bouncer.Session
  alias Comeonin.Bcrypt

  plug Bouncer.Plugs.Authorize when action in [:delete]

  def create(conn, %{"user" => user_params}) do
    case Repo.get_by(User, %{username: user_params["username"]}) do
      nil ->
        Bcrypt.dummy_checkpw()
        send_resp(conn, :bad_request, "")

      user ->
        if Bcrypt.checkpw(user_params["password"], user.encrypted_password) do
          user_map = User.to_map(user, true)
          {:ok, token} = Session.generate(conn, user_map)

          conn
          |> put_status(:created)
          |> render("create.json", %{user: user_map, token: token})
        else
          send_resp(conn, :bad_request, "")
        end
    end
  end

  def delete conn, _params do
    if user = conn.private.current_user do
      case Session.destroy conn.private.auth_token, user["id"] do
        {:ok, _} -> send_resp conn, :no_content, ""
        _ -> send_resp conn, :bad_request, ""
      end
    else
      send_resp conn, :unauthorized, ""
    end
  end
end