README.md

Doorman

Modules and functions to make authentication with Plug/Phoenix and Ecto easy without tons of configuration or boxing users into rigid framework.

The primary goal of Doorman is to build an opinionated interface and easy to use API on top of flexible modules that can also be used directly.

You can find more in-depth documentation here.

Installation

Add doorman to your dependencies in mix.exs.

def deps do
  [{:doorman, "~> 0.6.2"}]
end

Then add the configuration to config/config.exs.

config :doorman,
  repo: MyApp.Repo,
  secure_with: Doorman.Auth.Bcrypt,
  user_module: MyApp.User

Phoenix Quick Start

First generate a user model with a hashed_password and session_secret field.

$ mix phoenix.gen.model User users email hashed_password session_secret

Please note: we recommend using citext (or equivalent for non-postgres databases) for the email column so that your email is case insensitive.

Next, use Doorman.Auth.Bcrypt in your new User module and add a virtual password field. hash_password/1 is used in the changeset to hash our password and put it into the changeset as hashed_password.

defmodule MyApp.User do
  use MyApp.Web, :model
  import Doorman.Auth.Bcrypt, only: [hash_password: 1]

  schema "users" do
    field :email, :string
    field :hashed_password, :string
    field :password, :string, virtual: true
    field :session_secret, :string

    timestamps
  end

  def create_changeset(struct, params \\ %{}) do
    struct
    |> cast(params, ~w(email password))
    |> hash_password
  end
end

Finally, we can add our plug so we can have access to current_user on conn.assigns. 99% of the time that means adding the Doorman.Login.Session plug to your :browser pipeline:

pipeline :browser do
  # ...
  plug Doorman.Login.Session
  # ...
end

Creating Users

To create a user we can use the MyApp.create_changeset/2 function we defined. Here we'll also add the session_secret to the user, which is only needed when creating an user or in case of compromised sessions.

defmodule MyApp.UserController do
  use MyApp.Web, :controller
  alias Doorman.Auth.Secret
  alias MyApp.User

  def new(conn, _params) do
    changeset = User.create_changeset(%User{})
    conn |> render("new.html", changeset: changeset)
  end

  def create(conn, %{"user" => user_params}) do
    changeset = 
      %User{}
      |> User.create_changeset(user_params)
      |> Secret.put_session_secret()

    case Repo.insert(changeset) do
      {:ok, user} ->
        conn |> redirect(to: "/")
      {:error, changeset} ->
        conn |> render("new.html", changeset: changeset)
    end
  end
end

Logging in users

To login users we can use Doorman.authenticate and Doorman.Login.Session.login/2.

defmodule MyApp.SessionController do
  use Myapp.Web, :controller
  import Doorman.Login.Session, only: [login: 2]

  def create(conn, %{"session" => %{"email" => email, "password" => password}}) do
    if user = Doorman.authenticate(email, password) do
      conn
      |> login(user) # Sets :user_id and :session_secret on conn's session
      |> put_flash(:notice, "Successfully logged in")
      |> redirect(to: "/")
    else
      conn
      |> put_flash(:error, "No user found with the provided credentials")
      |> render("new.html")
    end
  end
end

Requiring Authentication

To require a user to be authenticated you can build a simple plug around Doorman.logged_in?/1.

defmodule MyApp.RequireLogin do
  import Plug.Conn

  def init(opts), do: opts

  def call(conn, _opts) do
    if Doorman.logged_in?(conn) do
      conn
    else
      conn
      |> Phoenix.Controller.redirect(to: "/login")
      |> halt
    end
  end
end