Getting started

This page looks at using the Phauxth installer to add authentication / authorization to your app.

The installer provides a basic starting point for your app and examples of how you can use Phauxth. It also provides examples of how you can authorize users based on the information that Phauxth.Authenticate adds to the conn (connection) struct.

Create new phoenix project

Run the following commands (replace alibaba with the name of your project):

mix phx.new alibaba
cd alibaba

To create an api, change the mix phx.new command to:

mix phx.new alibaba --no-html --no-brunch

Run the Phauxth installer

N.B. if you are not using Erlang 20, you might have to build the installer yourself. You can find the instructions in the README in the installer/new directory.

Download and install the phauxth_new installer.

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

For a basic setup, run the following command:

mix phauxth.new

If you want to add email / phone confirmation and password resetting, add the --confirm option:

mix phauxth.new --confirm

If you want to add 'remember me' support, add the --remember option:

mix phauxth.new --remember

If you want to create authentication files for an api, use the --api option:

mix phauxth.new --api

And for an api with user confirmation:

mix phauxth.new --api --confirm

There is also a backups option, which creates a backup file if any file already exists. This is true by default, and so if you do not want these files created, run:

mix phauxth.new --no-backups

Add phauxth to the app's dependencies

Make sure you are using Elixir 1.4 or above.

Add phauxth and one of the following password hashing libraries (argon2_elixir, bcrypt_elixir or pbkdf2_elixir) to your mix.exs dependencies (also add bamboo if you are using it for email confirmation) and then run mix deps.get.

defp deps do
  [
    {:phauxth, "~> 1.0"},
    {:argon2_elixir, "~> 1.2"},
    {:bamboo, "~> 0.8"},
  ]
end

If you are using argon2_elixir or pbkdf2_elixir to hash passwords, you also need to edit the user.ex file, in the accounts directory, and the session_controller.ex file.

In the user.ex file, change the Comeonin.Bcrypt.add_hash function to Comeonin.Argon2.add_hash or Comeonin.Pbkdf2.add_hash.

In the session_controller.ex file, add the crypto option to the Login.verify call, as in the following example:

Phauxth.Login.verify(params, MyApp.Accounts, crypto: Comeonin.Argon2)

Configure your app to use Phauxth

Phauxth uses the user context module (normally MyApp.Accounts) to communicate with the underlying database. This module needs to have the get(id) and get_by(attrs) functions defined (see the examples below).

def get(id), do: Repo.get(User, id)

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

Create the database, run the migration and seed data

Edit the priv/repo/seeds.exs file. This file contains an example of how to create user(s) at this stage.

Run the mix ecto.setup command.

Customize the Phoenix app

If you ran the mix phauxth.new command with the --confirm option, user confirmation is handled by bamboo (using the Mandrill adapter), but you are free to use any email / phone library you like. See this page for information about using a different adapter, or a different library.

For authorization, there are several helper functions defined in the authorize.ex file, in the controllers directory, and you can see how some of them are used in the user_controller.ex file. For more information, see Authorization.

Useful Phoenix commands

• mix phx.routes - see what routes are defined
• mix phx.server - run the server
• mix test - run the tests
• mix ecto.setup - create the database, run migrations and seed data
• mix ecto.reset - drop the database and then run ecto.setup