About

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

In the above example, Phauxth.Authenticate queries the Plug session for the user_id. If there is a current user, it will then call the database to get the user details. This behavior can be customized by creating a new module with use Phauxth.Authenticate.Base, and overriding the check_session function.

In the case of an api, you would probably want to use tokens. For this, you need to add method: :token to the command.

pipeline :api do
  plug Phauxth.Authenticate, method: :token
end

In this example, Phauxth.Authenticate checks the token for the user_id. If there is a current user, it will then call the database to get the user details. This behavior can be customized by creating a new module with use Phauxth.Authenticate.Base, and overriding the check_token function.

For more information about creating a customized Authenticate module, see the documentation for Phauxth.Authenticate.Base.

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

Phauxth.Login.verify is used to verify the password by comparing it with a stored password hash. It then returns {:ok, user} or {:error, message}. If the login is successful, you then need to add the user to the session, as in the example below, or send the user a token.

def create(conn, %{"session" => params}) do
  case Phauxth.Login.verify(params, MyApp.Accounts) do
    {:ok, user} ->
      put_session(conn, :user_id, user.id)
      |> configure_session(renew: true)
      |> success("You have been logged in", user_path(conn, :index))
    {:error, message} ->
      error(conn, message, session_path(conn, :new))
  end
end

For more information about creating a customized Login module, see the documentation for Phauxth.Login.Base.

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, Accounts) do
      {:ok, user} ->
        Accounts.confirm_user(user)
        Message.confirm_success(user.email)
        conn
        |> put_flash(:info, "Your account has been confirmed")
        |> redirect(to: session_path(conn, :new))
      {:error, message} ->
        conn
        |> put_flash(:error, message)
        |> redirect(to: session_path(conn, :new))
        |> halt
    end
  end

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

For password resetting, use Phauxth.Confirm with the mode: :pass_reset option.

In the following example, the verify function is called within the update function in the password reset controller (in this example, the max age of the key is set to 600 seconds, that is, 10 minutes).

def update(conn, %{"password_reset" => params}) do
    case Phauxth.Confirm.verify(params, MyApp.Accounts, max_age: 600, mode: :pass_reset) do
      {:ok, user} ->
        Accounts.update_user(user, params)
        Message.reset_success(user.email)
        configure_session(conn, drop: true)
        |> put_flash(:info, "Your password has been reset")
        |> redirect(to: 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 Accounts.update_user function.

For more information about creating a customized Confirm module, see the documentation for Phauxth.Confirm.Base.