In the first part of this post I've shown how to configure the API server to let the user authenticate, return an authentication token, and request it to access protected routes.
Now I'm going to configure a React app to consume that API and manage authentication.

The app uses React Router to manage routes and Redux for the state of the app.

Protect private routes

I'm going to define a PrivateRoute component as a wrapper around Route. The component will check the user authentication.

The router configuration will have a standard Route component for the Login page and will use PrivateRoute for the rest of the routes:

<Router>
    <Switch>
        <Route path='/login' component={Login} />
        <PrivateRoute path='/private' component={PrivateComponent}/>
    </Switch>
</Router>

The PrivateRoute component will check the isAuthenticated flag in the state and will redirect back to login if false or will render the private component otherwise:

import React from 'react';
import { Route, Redirect } from 'react-router-dom';
import { connect } from 'react-redux';

const mapStateToProps = state => {
    return {
        isAuthenticated: state.isAuthenticated,
    };
};

class PrivateRoute extends React.Component {
    render() {
        if (!this.props.isAuthenticated) {
            return (
                <Redirect
                    to={{
                    pathname: "/login",
                    state: { from: this.props.location }
                    }}
                />
            );
        }

        return (
            <Route component={this.props.Component} {...this.props} />
        );
    }
}

export default connect(mapStateToProps)(PrivateRoute);

Sign in and receive the token from the server

The Login component will simply show a form and will manage the initial authentication, saving the token in a cookie for later use:

import React from 'react';
import { connect } from 'react-redux';

import {
    signIn,
} from '../actions';

const mapStateToProps = state => {
    return {
        isAuthenticated: state.isAuthenticated,
    };
};

const mapDispatchToProps = dispatch => {
    return {
        onSignIn: (email, password) => dispatch(signIn(email, password)),
    };
};

class Login extends React.Component {
    constructor(props) {
        super(props);
        this.onSignIn = this.onSignIn.bind(this);
        this.state = {email: "", password: ""};
    }

    render() {
        return (
            <div className="container">
                <h1 className="title">Login</h1>
                {this.props.isAuthenticated ? this.alreadyAuthenticated() : this.form()}
            </div>
        );
    }

    alreadyAuthenticated() {
        return ("You're already authenticated.")
    }

    form() {
        return (
            <form>
                <div className="field">
                    <label className="label">Email</label>
                    <div className="control">
                        <input
                            className="input"
                            type="email"
                            placeholder="Your email address"
                            value={this.state.email}
                            autoFocus={true}
                            onChange={(e) => this.setState({...this.state, email: e.target.value})}
                        />
                    </div>
                </div>

                <div className="field">
                    <label className="label">Password</label>
                    <div className="control">
                        <input
                            className="input"
                            type="password"
                            placeholder="Your password"
                            value={this.state.password}
                            onChange={(e) => this.setState({...this.state, password: e.target.value})}
                        />
                    </div>
                </div>

                <button
                    className="button is-primary"
                    onClick={this.onSignIn}
                >Sign in</button>
            </form>
        );
    }

    onSignIn() {
        this.props.onSignIn(this.state.email, this.state.password);
    }
}

export default connect(
    mapStateToProps,
    mapDispatchToProps
)(Login);

The signIn action is where the "magic" happens:

export const signIn = (email, password) => ((dispatch) => {
    return fetch(`http://<server_url>/api/sessions/sign_in}`, {
        method: "POST",
        headers: {
            'Accept': 'application/json',
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({email, password}),
      }).then(
        response => {
            if (!response.ok) {
                // Manage error
                return dispatch(errorOnFetch(response.statusText));
            }
            return response.json().then(response => dispatch(signInSuccessfull(response.data)));
        },
        error => {
            return dispatch(errorOnFetch(error))
        }
    );
});

const signInSuccessfull = (data) => {
    setAuthToken(data.token);
    return {
        type: AUTHENTICATION_SUCCEDED,
    }
};

Two main things happen in the signInSuccessfull method: the token returned by the server is passed to the setAuthToken method and the AUTHENTICATION_SUCCEEDED action is returned to the redux reducer.

The reducer sets the isAuthenticated flag to true (do you remember the check in the PrivateRoute component?):

const mainReducer = (state = initialState, action) => {
    switch (action.type) {
        case AUTHENTICATION_SUCCEDED:
            return ({...state,
                isAuthenticated: true,
            });
        case AUTHENTICATION_SIGNOUT:
            return ({...state,
                isAuthenticated: false,
            });
    }
}

The setAuthToken method saves the token in a cookie, so that it will be then available for the next requests:

const setAuthToken = (token) => {
    const cookies = new Cookies();
    cookies.set('my_auth_token', token, {
        path: '/'
    });
};

I'm using the universal-cookie package here, so we need to install it:

yarn add universal-cookie

Other useful methods will permit to get the cookie or delete it:

export const getAuthToken = () => {
    const cookies = new Cookies();
    return cookies.get('my_auth_token');
};

const removeAuthToken = () => {
    const cookies = new Cookies();
    cookies.remove('my_auth_token', {
        path: '/',
    });
};

Use the token for private routes

At this point we have a valid token saved in a cookie. We just need to use it when making a request for a private API endpoint.

I'll use a wrapper function around fetch to add the Authorization header to the requests:

const authFetch = (url, options) => (
    fetch(url, mergeAuthHeaders(options)).then(
        response => {
            // Sign out if we receive a 401!
            if (response.status === 401) {
                store.dispatch(signOut());
                throw new Error("Unauthorized");
            }
            return response;
        },
        error => error
    )
);

const mergeAuthHeaders = (baseOptions) => {
    const options = _.isUndefined(baseOptions) ? {} : baseOptions;
    if (!_.has(options, 'headers')) {
        options.headers = {};
    }
    options.headers = {
        ...options.headers,
        'Authorization': `Bearer ${getAuthToken()}`,
    };
    return options;
}

The authFetch method receives a URL to fetch and the options for the fetch method. It merges the authentication header in the options and makes the request.
If it receives a 401 response, then it makes the sign out, deleting the cookie and setting the isAuthenticated flag to false:

export const signOut = () => {
    removeAuthToken();
    return {
        type: AUTHENTICATION_SIGNOUT,
    }
};

That's it, you should probably add more logic to manage side cases and errors, but this is enough to consume the APIs we built.

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
  timestamps()
end
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"}
end

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
    timestamps()
  end
  
  def changeset(%User{} = user, attrs) do
    user
    |> cast(attrs, [:email, :password])
    |> validate_required([:email, :password])
    |> unique_constraint(:email, downcase: true)
    |> put_password_hash()
  end
  
  defp put_password_hash(changeset) do
    case changeset do
      %Ecto.Changeset{valid?: true, changes: %{password: pass}} ->
        put_change(
            changeset, 
            :password_hash, 
            Comeonin.Bcrypt.hashpwsalt(pass)
        )
      _ ->
        changeset
    end
  end
end

At this point we can create new users:

$ iex -S mix
iex(1)> MyApp.repo.insert!(MyApp.User.changeset(
  %MyApp.User{}, %{
    email: “my_email@provider.com”, 
    password: “s3cr3t”
  }
))
[..]
%MyApp.User{
  __meta__: #Ecto.Schema.Metadata<:loaded, "users">,
  email: "my_email@provider.com",
  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
  timestamps()
end
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
    timestamps()
  end
  
  def changeset(%AuthToken{} = auth_token, attrs) do
    auth_token
    |> cast(attrs, [:token])
    |> validate_required([:token])
    |> unique_constraint(:token)
  end
end

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
  [...]
end

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)
  end
  
  def verify_token(token) do
    case Phoenix.Token.verify(@secret, @seed, token, max_age: 86400) do
      {:ok, id} -> {:ok, token}
      error -> error
    end
  end
end

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
    end
  end
  
  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)
        end
      error -> error
    end
  end
end

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

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
end

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} ->
        conn
        |> put_status(:ok)
        |> render("show.json", auth_token)
      {:error, reason} ->
        conn
        |> send_resp(401, reason)
    end
  end
  
  def delete(conn, _) do
    case User.sign_out(conn) do
      {:error, reason} -> conn |> send_resp(400, reason)
      {:ok, _} -> conn |> send_resp(204, "")
    end
  end
end

and its view:

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

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:

{
  "email":"my_email@provider.com",
  "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
  end
  scope "/restricted", Restricted do
    pipe_through :authenticate
    resources "/private"
    # more routes
  end
  [...]
end

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)
        end
      _ -> unauthorized(conn)
    end
  end
  
  defp authorized(conn, user) do
    # If you want, add new values to `conn`
    assign(conn, :signed_in, true)
    assign(conn, :signed_user, user)
    conn
  end
  
  defp unauthorized(conn) do
    conn |> send_resp(401, "Unauthorized") |> halt()
  end
end

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!

References

• http://learningwithjb.com/posts/authenticating-users-using-a-token-with-phoenix
• https://dennisreimann.de/articles/phoenix-passwordless-authentication-magic-link.html
• http://whatdidilearn.info/2018/02/18/authentication-in-phoenix.html
• https://itnext.io/authenticating-absinthe-graphql-apis-in-phoenix-with-guardian-d647ea45a69a
• https://medium.freecodecamp.org/authentication-using-elixir-phoenix-f9c162b2c398

If you’re playing with Elixir and Phoenix you’ll probably already know that Phoenix uses Brunch.io to build the assets pipeline.
I initially started building my app with React / Redux + SASS and I was quite happy, but when I decided to add Typescript to the recipe, I found Brunch.io wasn’t very helpful!

I’ve already used these tools using Webpack as building tool, so I decided to switch to it.
I had a working Webpack configuration I was using in other projects, so I only had to find out how to apply it to Phoenix.

When I initially generated the Phoenix app, I didn’t use the --no-brunch command line flag to generate it without Brunch, and the app itself was alreadyt working. So I wanted to replace the existing Brunch config with the new one without nuking any existing feature.

Below you can find the (few) steps required for this upgrade.

Remove Brunch and install Webpack

To remove Brunch, just remove the assets/brunch-config.js file and uninstall all brunch-related packages. In my case:

yarn remove brunch babel-brunch clean-css-brunch sass-brunch uglify-js-brunch

In the assets/package.json file you can also see that Brunch is mentioned in the scripts commands:

"scripts": {
  "deploy": "brunch build --production",
  "watch": "brunch watch --stdin"
},

Replace them with the Webpack commands (to run the webpack command you’d probably need to globally install it with yarn global add webpack):

"scripts": {
  "deploy": "webpack -p",
  "compile": "webpack --progress --color",
  "watch": "webpack --watch-stdin --progress --color"
},

You’re now ready to install the webpack ecosystem we’re going to use:

yarn add -D webpack babel-core babel-loader babel-preset-es2015 copy-webpack-plugin css-loader extract-text-webpack-plugin file-loader node-sass sass-loader style-loader webpack-notifier

Add Typescript to the project

To add Typescript support we need some more packages too:

yarn add -D typescript ts-loader tslint tslint-react @types/phoenix @types/react @types/react-dom @types/react-redux

The Typescript configuration file is assets/tsconfig.json:

{
  "compilerOptions": {
    "target": "es2015",
    "module": "es2015",
    "jsx": "preserve",
    "moduleResolution": "node",
    "baseUrl": "js",
    "outDir": "ts-build",
    "allowJs": true
  },
  "exclude": [
    "node_modules",
    "priv",
    "ts-build"
  ]
}

As you probably noticed in the previous command, I also installed TSLint support for linting features. Add the related package to your editor (like vscode-tslint for VSCode) to have (almost-)real-time linting warnings.
You also need a configuration file, here’s mytslint.json file:

{
  "extends": ["tslint:recommended", "tslint-react"],
  "rules": {
    "no-console": [false]
  }
}

Webpack configuration

Before configuring Webpack, let’s configure Babel, using the assets/.babelrc file:

{
  "presets": ["es2015", "react"]
}

And now, finally, the big part, the Webpack configuration file, assets/webpack.config.js:

const env = process.env.NODE_ENV
const path = require("path")
const ExtractTextPlugin = require("extract-text-webpack-plugin");
const CopyWebpackPlugin = require("copy-webpack-plugin")
const config = {
  entry: ["./css/app.scss", "./js/app.js"],
  output: {
    path: path.resolve(__dirname, "../priv/static"),
    filename: "js/app.js"
  },
  resolve: {
    extensions: [".ts", ".tsx", ".js", ".jsx"],
    modules: ["deps", "node_modules"]
  },
  module: {
    rules: [{
      test: /\.tsx?$/,
      use: ["babel-loader", "ts-loader"]
    }, {
      test: /\.jsx?$/,
      use: "babel-loader"
    }, {
      test: /\.scss$/,
      use: ExtractTextPlugin.extract({
        use: [{
          loader: "css-loader",
          options: {
            minimize: true,
            sourceMap: env === 'production',
          },
        }, {
          loader: "sass-loader",
          options: {
            includePaths: [path.resolve('node_modules')],
          }
        }],
        fallback: "style-loader"
      })
    }, {
      test: /\.(ttf|otf|eot|svg|woff(2)?)(\?[a-z0-9]+)?$/,
      // put fonts in assets/static/fonts/
      loader: 'file-loader?name=/fonts/[name].[ext]'
    }]
  },
  plugins: [
    new ExtractTextPlugin({
      filename: "css/[name].css"
    }),
    new CopyWebpackPlugin([{ from: "./static" }])
  ]
};
module.exports = config;

Final polishing and tests

The final step is to update the main template file app.html.eex to use the generated files (that you can find in the priv/static folder once compiled):

[..]
<link rel="stylesheet" href="<%= static_path(@conn, "/css/main.css") %>">
[..]
<script src="<%= static_path(@conn, "/js/app.js") %>"></script>

The whole pipeline is now ready, except we must tell Phoenix to run Webpack when the server is launched.
At the moment you can already test the pipeline running, from the assets/ folder, the command: yarn run compile

To configure Phoenix, update the config/dev.exs file replacing Brunch command with Webpack:

watchers: [
  node: [
    "node_modules/webpack/bin/webpack.js", "--watch-stdin", "--progress", "--color",
    cd: Path.expand("../assets", __DIR__)
  ]
]

That’s it.
Run mix phx.server and you’ll have both the Phoenix server running and the assets pipeline compiled and watching for file updates.