Phauxth behaviour (Phauxth v2.5.1) View Source

Authentication library for Phoenix, and other Plug-based, web applications.

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

Phauxth offers two types of functions: Plugs, which are called with plug, and verify/2 functions.

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 session_id in the current session and sets the current_user value accordingly.

AuthenticateToken

Phauxth.AuthenticateToken checks to see if there is an authorization token in the headers, verifies it, and sets the current_user value accordingly.

Remember

Phauxth.Remember checks to see if there is a valid remember_me cookie. If there is one, it verifies the cookie and, if the verification is successful, adds the user to the session.

Phauxth verify/2

The verify/2 functions take a map (usually Phoenix params) and opts (an empty list by default) and return {:ok, user} or {:error, message}.

Phauxth.Login.verify is used for user login.

User confirmation

Phauxth.Confirm.verify is used for email confirmation.

Password resetting

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

Phauxth with a new Phoenix project

The easiest way to get started is to use the phauxth_new installer. First, download and install it:

mix archive.install https://github.com/riverrun/phauxth_installer/raw/master/archives/phauxth_new.ez

Then run the mix phauxth.new command in the main directory of the Phoenix app. The following options are available:

--api - create files for an api
--confirm - add files for email confirmation
--remember - add remember_me functionality
--backups - create backup files, with .bak extension, before writing new files

Phauxth uses the user_context module to communicate with the underlying database. This value needs to be set in the config. See the documentation for Phauxth.Config.user_context for details.

In addition, the user_context module needs to have a get_by(attrs) function defined (see the examples below).

@spec get_by(map) :: User.t() | nil
def get_by(%{"session_id" => session_id}) do
  with %Session{user_id: user_id} <- Sessions.get_session(session_id),
  do: get_user(user_id)
end

def get_by(%{"email" => email}) do
  Repo.get_by(User, email: email)
end

Customizing Phauxth

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

You can also find more information at the Phauxth wiki.

Link to this section Summary

Types

ok_or_error()

Callbacks

authenticate(map, module, keyword)

Authenticates the user based on the user params.

report(ok_or_error, keyword)

Logs the result of the verification and returns {:ok, user} or {:error, message}.

verify(map, keyword)

Verifies the user based on the user params.

Link to this section Types

ok_or_error()

Specs

ok_or_error() :: {:ok, map()} | {:error, String.t() | atom()}

Link to this section Callbacks

authenticate(map, module, keyword)

Specs

authenticate(map(), module(), keyword()) :: ok_or_error()

Authenticates the user based on the user params.

After performing the relevant checks, this function also gets the user data (if available).

report(ok_or_error, keyword)

Specs

report(
  ok_or_error(),
  keyword()
) :: ok_or_error()

Logs the result of the verification and returns {:ok, user} or {:error, message}.

verify(map, keyword)

Specs

verify(
  map(),
  keyword()
) :: ok_or_error()

Verifies the user based on the user params.

In the default implementations - Confirm.Base and Login.Base, this function calls the authenticate function with the user params and pipes the output to the report function.