Home

A collection of functions to be used to authenticate Phoenix web apps.

Phauxth is designed to be secure, extensible and well-documented.

Phauxth offers two types of functions: Plugs, which are called with plug, and verify/3 functions, which are called inside the function bodies.

Plugs

Plugs take a conn (connection) struct, a context module (MyApp.Accounts by default) and opts as arguments and return a conn struct.

Authenticate

Phauxth.Authenticate checks to see if there is a valid cookie or token for the user and sets the current_user value accordingly.

Note that Phauxth.Authenticate does not perform any authorization. For information about how to use the current_user value to authorize users, see this page.

This is usually added to the pipeline you want to authenticate in the router.ex file, as in the following example.

pipeline :browser do
  plug Phauxth.Authenticate
end

Remember

This Plug provides a check for a remember_me cookie.

pipeline :browser do
  plug Phauxth.Authenticate
  plug Phauxth.Remember
end

This needs to be called after plug Phauxth.Authenticate

Phauxth verify/3

Each verify/3 function takes a map (usually Phoenix params), a context module (usually MyApp.Accounts) and opts (an empty list by default) and returns {:ok, user} or {:error, message}.

Login

In the example below, Phauxth.Login.verify is called within the create function in the session controller.

def create(conn, %{"session" => params}) do
  case Phauxth.Login.verify(params, MyApp.Accounts) do
    {:ok, user} -> handle_successful_login
    {:error, message} -> handle_error
  end
end

Note that this function does not add the user to the session, or send a token to the user. You need to do that yourself in the handle_successful_login function.

User confirmation

Phauxth.Confirm.verify is used for user confirmation, using email, phone or any other method.

In the following example, the verify function is called within the new function in the confirm controller.

def new(conn, params) do
  case Phauxth.Confirm.verify(params, MyApp.Accounts) do
    {:ok, user} ->
      Accounts.confirm_user(user)
      message = "Your account has been confirmed"
      Message.confirm_success(user.email)
      handle_success(conn, message, session_path(conn, :new))
    {:error, message} ->
      handle_error(conn, message, session_path(conn, :new))
  end
end

Note that this function does not confirm the user in the database. You need to do that yourself in the confirm_user function.

Phauxth.Confirm.PassReset.verify is used for password resetting.

In the following example, the verify function is called within the update function in the password reset controller, and the key validity is set to 20 minutes (the default is 60 minutes).

def update(conn, %{"password_reset" => params}) do
  case Phauxth.Confirm.PassReset.verify(params, MyApp.Accounts, key_validity: 20) do
    {:ok, user} ->
      Accounts.update_user(user, params)
      Message.reset_success(user.email)
      message = "Your password has been reset"
      configure_session(conn, drop: true) |> handle_success(message, session_path(conn, :new))
    {:error, message} ->
      conn
      |> put_flash(:error, message)
      |> render("edit.html", email: params["email"], key: params["key"])
  end
end

Note that this function does not actually reset the password in the database. You need to do that yourself in the update_user function.

Phauxth with a new Phoenix project

Go to the New project page.

Customizing Phauxth

See the documentation for Phauxth.Authenticate.Base, Phauxth.Login.Base and Phauxth.Confirm.Base for more information on extending these modules.