API Authentication with Phoenix and React - part 1

Scenario: you just wrote a cool web app using React for the frontend part and Phoenix as the API server. Then you realize everybody can poke around your stuff and you decide it’s time to restrict the access to known users, how to do it?

I’ll configure a Phoenix server to manage access tokens, used by a React app to make authenticated calls.

This blog post only deals with the backend part and consists of these steps:

  • add users and give them the ability to sign in
  • manage authentication tokens for the users
  • define a pipeline to grant access to restricted routes only to authenticated requests

I’m not going to cover the SSL configuration here, but it’s fundamental to only serve the endpoints over HTTPS. You can check out this article which explains how to force SSL in Phoenix.

Create the Users

Let’s create the schemas for the User:

$ mix phx.gen.schema User users email:string:unique password_hash:string

The mix command doesn’t accept any option to avoid null values, so the migration files must be edited. This is the final version of the migration file (only the relevant parts):

create table(:users) do
  add :email, :string, null: false
  add :password_hash, :string, null: false
create unique_index(:users, [:email])

We’re going to save hashed password, not clear-text passwords, so our schema will have a virtual password field which, behind the scenes, will be hashed and saved.

To crypt passwords we’re going to use the Comeonin lib, that must be added to the dependencies, together with BCrypt (don’t forget to run mix deps.get after you made the changes):

# mix.exs
defp deps do
  {:comeonin, "~> 4.0"},
  {:bcrypt_elixir, "~> 1.0"}

Let’s now see the User module:

defmodule MyApp.User do
  use Ecto.Schema
  import Ecto.Changeset
  alias MyApp.User

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

  def changeset(%User{} = user, attrs) do
    |> cast(attrs, [:email, :password])
    |> validate_required([:email, :password])
    |> unique_constraint(:email, downcase: true)
    |> put_password_hash()

  defp put_password_hash(changeset) do
    case changeset do
      %Ecto.Changeset{valid?: true, changes: %{password: pass}} ->
      _ ->

At this point we can create new users:

$ iex -S mix
iex(1)> MyApp.repo.insert!(MyApp.User.changeset(
  %MyApp.User{}, %{
    email: “”,
    password: “s3cr3t”
  __meta__: #Ecto.Schema.Metadata<:loaded, "users">,
  email: "",
  id: 1,
  inserted_at: ~N[2018-03-24 22:47:37.981969],
  password: "s3cr3t",
  password_hash: "<cut>",
  updated_at: ~N[2018-03-24 22:47:37.984213]

User tokens

Ok, now that we have users, we must generate tokens for them, so that they can access restricted routes.

The first step is to create the schema:

$ mix phx.gen.schema AuthToken auth_tokens user_id:references:users token:text:unique revoked:boolean revoked_at:utc_datetime

As before, we must edit the migration to add missing null: false:

create table(:auth_tokens) do
  add :user_id, references(:users, on_delete: :nothing), null: false
  add :token, :text, null: false
  add :revoked, :boolean, default: false, null: false
  add :revoked_at, :utc_datetime
create unique_index(:auth_tokens, [:token])
create index(:auth_tokens, [:user_id])

The schema is the following:

defmodule MyApp.AuthToken do
  use Ecto.Schema
  import Ecto.Changeset
  alias MyApp.AuthToken
  alias MyApp.User

  schema "auth_tokens" do
    belongs_to :user, User
    field :revoked, :boolean, default: false
    field :revoked_at, :utc_datetime
    field :token, :string

  def changeset(%AuthToken{} = auth_token, attrs) do
    |> cast(attrs, [:token])
    |> validate_required([:token])
    |> unique_constraint(:token)

We’ve added the belongs_to relationship there, we must also edit the User schema adding:

schema "users" do
  has_many :auth_tokens, MyApp.AuthToken

We’re going to need a bunch of methods to deal with authorization headers and tokens, so a service could be useful. Let’s create an Authenticator service with the first methods we’ll use to generate and verify tokens with Phoenix.Token:

defmodule MyApp.Services.Authenticator do
  # These values must be moved in a configuration file
  @seed "user token"
  # good way to generate:
  # :crypto.strong_rand_bytes(30)
  # |> Base.url_encode64
  # |> binary_part(0, 30)
  @secret "CHANGE_ME_k7kTxvFAgeBvAVA0OR1vkPbTi8mZ5m"

  def generate_token(id) do
    Phoenix.Token.sign(@secret, @seed, id, max_age: 86400)

  def verify_token(token) do
    case Phoenix.Token.verify(@secret, @seed, token, max_age: 86400) do
      {:ok, id} -> {:ok, token}
      error -> error

Sign in and out the users

We now need to let the users sign in (create a token for the user) and sign out (delete the token).

We’ll manage the logic inside the User module:

defmodule MyApp.User do
  alias MyApp.Services.Authenticator

  def sign_in(email, password) do
    case Comeonin.Bcrypt.check_pass(Repo.get_by(User, email: email), password) do
      {:ok, user} ->
        token = Authenticator.generate_token(user)
        Repo.insert(Ecto.build_assoc(user, :auth_tokens, %{token: token}))
      err -> err

  def sign_out(conn) do
    case Authenticator.get_auth_token(conn) do
      {:ok, token} ->
        case Repo.get_by(AuthToken, %{token: token}) do
          nil -> {:error, :not_found}
          auth_token -> Repo.delete(auth_token)
      error -> error

The first line of the sign_in function looks for the user in the Repo then passes it to Bcrypt.check_pass together with the provided password, to verify it.

In the case the user can’t be found, check_pass receives a wrong user and returns {:error, "invalid user-identifier"} while in the case the password verification fails it returns {:error, "invalid password"}. So, in both cases, we return a {:error, reason} tuple (we’ll later use this in the controller).

If the user is found and the password is valid, we create a token for the user and return it.

The sign_out function looks for the token in the header and deletes it if found.

The function that extracts the token is based on a simple regexp:

defmodule MyApp.Services.Authenticator do
  def get_auth_token(conn) do
    case extract_token(conn) do
      {:ok, token} -> verify_token(token)
      error -> error

  defp extract_token(conn) do
    case Plug.Conn.get_req_header(conn, "authorization") do
      [auth_header] -> get_token_from_header(auth_header)
       _ -> {:error, :missing_auth_header}

  defp get_token_from_header(auth_header) do
    {:ok, reg} = Regex.compile("Bearer\:?\s+(.*)$", "i")
    case, auth_header) do
      [_, match] -> {:ok, String.trim(match)}
      _ -> {:error, "token not found"}

At this point all the underground pieces are in place, but we need to create the endpoints to let the user make the actions.

First, add the required routes:

scope "/sessions" do
  post "/sign_in", SessionsController, :create
  delete "/sign_out", SessionsController, :delete

We can check the result with mix phx.routes:

sessions_path  POST    /sessions/sign_in    MyApp.SessionsController :create
sessions_path  DELETE  /sessions/sign_out    MyApp.SessionsController :delete

We must then create the SessionsController:

defmodule MyAppWeb.SessionsController do
  use MyAppWeb, :controller
  alias MyApp.User

  def create(conn, %{"email" => email, "password" => password}) do
    case User.sign_in(email, password) do
      {:ok, auth_token} ->
        |> put_status(:ok)
        |> render("show.json", auth_token)
      {:error, reason} ->
        |> send_resp(401, reason)

  def delete(conn, _) do
    case User.sign_out(conn) do
      {:error, reason} -> conn |> send_resp(400, reason)
      {:ok, _} -> conn |> send_resp(204, "")

and its view:

defmodule MyAppWeb.SessionsView do
  use MyAppWeb, :view
  def render("show.json", auth_token) do
    %{data: %{token: auth_token.token}}

Done, it’s now time to make some tests calling these endpoints. I personally use Advanced Rest Client (aka ARC), a Chrome extension to make HTTP calls.

To test sign in, we must make a POST call to http://localhost:4000/sessions/sign_in with the following JSON body:

  "password": "s3cr3t"

If we didn’t make any error we’ll get back the token in a json structure as we defined in show.json:

  "data": {
    "token": "SFMyNTY.g3QAAAAC[...cut...]"

Now make a DELETE call against http://localhost:4000/sessions/sign_out, adding an authorization header in the form: Authorization: Bearer SFMyNTY.g3QAAAAC[…cut…]. You should receive a 204 response.

Take a look at the database for further feedback. A new token for the user must be created at sign in and it must be deleted at sign out.

Require the token to access restricted routes

We’re almost there: users are able to sign in and receive an authentication token, we should now restrict the access to private routes requiring an authorization token.

The key is a basic component of Phoenix: the Plug.

To apply one or more plugs to routes, we need to create a pipeline and pipe the routes through it:

defmodule MyAppWeb.Router do
  pipeline :authenticate do
    plug MyAppWeb.Plugs.Authenticate
  scope "/restricted", Restricted do
    pipe_through :authenticate
    resources "/private"
    # more routes

The Authenticate plug will look for the authorization token in the request headers and will validate it. Only requests with valid tokens will go through. Invalid requests will get a 401 response.

This is the plug file:

defmodule MyAppWeb.Plugs.Authenticate do
  import Plug.Conn
  def init(default), do: default

  def call(conn, _default) do
    case MyApp.Services.Authenticator.get_auth_token(conn) do
      {:ok, token} ->
        case MyApp.Repo.get_by(MyApp.AuthToken, %{token: token, revoked: false})
        |> Repo.preload(:user) do
          nil -> unauthorized(conn)
          auth_token -> authorized(conn, auth_token.user)
      _ -> unauthorized(conn)

  defp authorized(conn, user) do
    # If you want, add new values to `conn`
    assign(conn, :signed_in, true)
    assign(conn, :signed_user, user)

  defp unauthorized(conn) do
    conn |> send_resp(401, "Unauthorized") |> halt()

Revoke a compromised token

In the case a token is somehow “compromised”, the user can revoke it.

We need a new restricted route which updates the compromised token setting the revoked=true and revoked_at=<current timestamp>.

I’m going to leave this as an exercise for the readers.

Consume the APIs with React

In the next part of this guide, I’ll show how to use what done here in a frontend app built using React. Read it here.

Note: JWT and why I didn’t use it

In the first iteration of the code I decided to use Guardian and JWT (JSON Web Tokens) but then I realized I couldn’t revoke tokens without store them in the db and actually make a query at each API call (and avoiding a query was the main reason that lead me to use JWT), so I decided it was a over-engineered solution and moved to the integrated Phoenix.Token.

If you’re interested in the JWT revoke topic, check the GuardianDB README which has a good explanation:

In other words, once you have reached a point where you think you need Guardian.DB, it may be time to take a step back and reconsider your whole approach to authentication!