Part 2: Adding Guardian Authentication

Now we're going to add authentication to our app. As this is going to be a JSON REST API we are going to use a token that needs to be passed as a header in each request made to the API. We are going to use Guardian to do the authentication.
This is NOT complete solution, as it is not saving the tokens to a DB, nor checking if they are still valid. But IT IS checking that the security token is valid and that is enough for now.

Series

1. Part 1 - Elixir App creation
2. Part 2 - Adds Guardian Authentication
3. Part 3: Elm App creation and Routing setup
4. Part 4: Adding Login and Register pages
5. Part 5: Persisting session data to localStorage

Add the Guardian dependency

First let's add the guardian dependency to the mix.exs file

  defp deps do
    [
      {:phoenix, "~> 1.3.0"},
      {:phoenix_pubsub, "~> 1.0"},
      {:phoenix_ecto, "~> 3.2"},
      {:postgrex, ">= 0.0.0"},
      {:gettext, "~> 0.11"},
      {:cowboy, "~> 1.0"},
      {:comeonin, "~> 4.0"},
      {:argon2_elixir, "~> 1.2"},
      {:guardian, "~> 1.0"}
    ]
  end

And retrieve the dependencies

mix deps.get

Lets configure Guardian. There are a couple of things you need to do before Guardian can be used to generate tokens for you. The first thing is to create a module that will be used by Guardian as a set of callbacks for the things it doesn't know how to do and depends completely on your app.

Create a new file named guardian.ex in a new folder lib/toltec/auth/

# /lib/toltec/auth/guardian.ex

defmodule Toltec.Auth.Guardian do
  use Guardian, otp_app: :toltec

  def subject_for_token(resource, _claims) do
    sub = to_string(resource.id)
    {:ok, sub}
  end

  def resource_from_claims(claims) do
    case Toltec.Accounts.get_user(claims["sub"]) do
      nil -> {:error, "User not found"}
      user -> {:ok, user}
    end
  end
end

This file responsibility is to convert between a token an a resource (a user) and between a resource (our user) and a unique identifier to be encoded in the token that will be passed all over the place.

The idea is simple, generate a unique, random, unpredictable string, that will represent our user (the subject). This string is the token, and will be given to the frontend so that in future interactions (requests) we know that a user is who it says it is.

Going back to the guardian module, you see that:

• we use the resource id (the user id) as the thing that uniquely identifies a user of our app and
• that from that user id (encoded in the claims["sub"], the subject) we can unequivocally know which user in our app corresponds to

Pay attention the the get_user method. This is different than the one we created on part 1. So go to accounts.ex and change this:

# lib/toltec/accounts/accounts.ex

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

to this

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

Let's continue. Now we need to configure the library to correctly generate the tokens.
As this tokens are cryptographically generated, the strength of the tokens will depend directly on the seed we use to initialise the crypto algorithm. So we need to generate a strong seed to be used by Guardian to generate the tokens.
Please, don't use this example key. Use a new one generated on your side.

# this is an example, don't use it in your app
mix guardian.gen.secret
TJD5jd2uGqrOO3zDb/pU85DhH9yzj5cy0WPjKQV6nz3d+XWS+RY5ff8hvhnfK2Dk

Now use this key to configure Guardian. Add this to config/dev.exs

config :toltec, Toltec.Auth.Guardian,
  issuer: "toltec",
  secret_key: "TJD5jd2uGqrOO3zDb/pU85DhH9yzj5cy0WPjKQV6nz3d+XWS+RY5ff8hvhnfK2Dk"

If you're going to commit this file to your repo, anyone who has access to that repo can generate valid tokens. So I'd suggest instead to use environment vars to assign a secret key, but that's your call.

Anyway, now that it is configured, let's use Guardian to create tokens when the user correctly logs in and starts a session.

Generate the JWT tokens

Add a new file named session_controller.ex. Its responsibilities are to create new sessions, delete them and refresh them.

# lib/toltec_web/controllers/session_controller.ex

defmodule ToltecWeb.SessionController do
  use ToltecWeb, :controller

  alias Toltec.Accounts
  alias Toltec.Auth.Guardian

  def create(conn, params) do
    case authenticate(params) do
      {:ok, user} ->
        new_conn = Guardian.Plug.sign_in(conn, user)
        jwt = Guardian.Plug.current_token(new_conn)

        new_conn
        |> put_status(:created)
        |> render("show.json", user: user, jwt: jwt)

      :error ->
        conn
        |> put_status(:unauthorized)
        |> render("error.json", error: "User or email invalid")
    end
  end

  def delete(conn, _) do
    conn
    |> Guardian.Plug.sign_out()
    |> put_status(:no_content)
    |> render("delete.json")
  end

  def refresh(conn, _params) do
    user = Guardian.Plug.current_resource(conn)
    jwt = Guardian.Plug.current_token(conn)

    case Guardian.refresh(jwt, ttl: {30, :days}) do
      {:ok, _, {new_jwt, _new_claims}} ->
        conn
        |> put_status(:ok)
        |> render("show.json", user: user, jwt: new_jwt)

      {:error, _reason} ->
        conn
        |> put_status(:unauthorized)
        |> render("error.json", error: "Not Authenticated")
    end
  end

  defp authenticate(%{"email" => email, "password" => password}) do
    Accounts.authenticate(email, password)
  end

  defp authenticate(_), do: :error
end

As you can see, there are three methods, mapping the session operations: create, terminate and refresh. They use the Guardian.Plug functions to generate a JWT (JSON Web Token) when the user correctly gives an email and a password.

We have a helper authenticate() function that takes an email and password and checks in the database if a users exists for that combination. If it exists, it returns a {:ok, user} tuple. If it doesn't, it will return error. With that contract we can understand the create() function. If it is a valid email/password, we get a user that we can pass to the Guardian.Plug.sign_ing function to put the user in the conn struct. We then generate a token for that user and we finish by sending a JSON response that includes both the user and the token.
In case the email/password combination doesn't exist, we render a JSON error response.

The delete/2 function is simpler. What it does is to call the Guardian sing_out/0 method to remove the resource (our user, remember) from the connection struct.

The refresh method, is not going to be used yet, but what it does is to take a valid, existing token, get a new one with 30 more days of validity and send that new token as the response to substitute the old one.

Let's see how the authenticate/2 method in Accounts will look like:

# lib/toltec/accounts/accounts.ex

  def authenticate(email, password) do
    user = Repo.get_by(User, email: String.downcase(email))

    case check_password(user, password) do
      true -> {:ok, user}
      _ -> :error
    end
  end

  defp check_password(user, password) do
    case user do
      nil -> Comeonin.Argon2.dummy_checkpw()
      _ -> Comeonin.Argon2.checkpw(password, user.password_hash)
    end
  end

This is quite simple, it tries to retrieve a user from the DB by the email. Then delegates to the check_password/2 to either do a dummy password check in case the user doesn't exist or check the password against the hash stored in DB, in case it exists.

Ok, the session controller is ready. Before moving to the views, lets add a user_controller, that will be responsible for creating new uses for our app. It will be very similar to the session_contoller.ex.

One point to notice is that the user creation is immediate, that is, as soon as the user creation request is finished, the user exists and is valid in the system. In a production system you'll need to add additional verification steps, like sending a confirmation email with a link to verify the email, before activating a user in the system. That's outside the scope of this tutorial.

Create a file name user_controller in lib/toltec_web/controllers/

# lib/toltec_web/controllers/user_controller.ex

defmodule ToltecWeb.UserController do
  use ToltecWeb, :controller

  alias Toltec.Accounts
  alias Toltec.Accounts.User
  alias Toltec.Auth.Guardian

  action_fallback(ToltecWeb.FallbackController)

  def create(conn, params) do
    with {:ok, %User{} = user} <- Accounts.create_user(params) do
      new_conn = Guardian.Plug.sign_in(conn, user)
      jwt = Guardian.Plug.current_token(new_conn)

      new_conn
      |> put_status(:created)
      |> render(ToltecWeb.SessionView, "show.json", user: user, jwt: jwt)
    end
  end
end

This controller receives a set of params (name, email, password) and pass it to the Accounts create_user/1 to create a new user. If that is successful, then automatically signs ing the user and creates a JWT. The user and token will be sent to the front end as JSON through the show.json view. Nothing complicated here, right?

Let's move to the views that render the JSON.

First the easy one. Create a user_view.ex file in lib/toltec_web/views like this:

# lib/toltec_web/views

defmodule ToltecWeb.UserView do
  use ToltecWeb, :view

  def render("user.json", %{user: user}) do
    %{
      id: user.id,
      name: user.name,
      email: user.email
    }
  end
end

Nothing unexpected. The render method receives a user and returns a map with the properties that we want to expos to the clients. Elixir will convert it to JSON for us. For this, we only expose the id, name and email.

Now create a new file named session_view.ex inside lib/toltec_web/views

# lib/toltec_web/views/session_view.ex

defmodule ToltecWeb.SessionView do
  use ToltecWeb, :view

  def render("show.json", %{user: user, jwt: jwt}) do
    %{
      data: render_one(user, ToltecWeb.UserView, "user.json"),
      meta: %{token: jwt}
    }
  end

  def render("delete.json", _) do
    %{ok: true}
  end

  def render("error.json", %{error: error}) do
    %{errors: %{error: error}}
  end
end

This is similar although a bit more complex. The show.json view renders the user and the token to the client. It does it by delegating to the user.json view in UserView. Nice, right?

Configure the routes to our Users API

We're almost finished. We're only missing one simple but crucial step, the router. Without it, the app won't know what to do when it receives a request. So let's configure our router.

Open router.ex and make it look like this:

# lib/toltec_web/router.ex

defmodule ToltecWeb.Router do
  use ToltecWeb, :router

  pipeline :api do
    plug(:accepts, ["json"])
  end

  pipeline :api_auth do
    plug(Toltec.Auth.Pipeline)
  end

  scope "/api", ToltecWeb do
    pipe_through(:api)

    post("/sessions", SessionController, :create)
    post("/users", UserController, :create)
  end

  scope "/api", ToltecWeb do
    pipe_through([:api, :api_auth])

    delete("/sessions", SessionController, :delete)
    post("/sessions/refresh", SessionController, :refresh)
  end
end

This is descriptive enough. It adds several new routes inside the /api scope. A couple ones are more restricted than the others.

If the request is a POST request to /sessions or /users, it will be allowed without authorization. But if the request is a DELETE to /sessions or a POST to /sessions/refresh, we require them to be authenticated. This is logical, as we expect that only authenticated logged in users can log out or refresh the session (that it, to refresh the token that represents a user in a session).
To do this authentication we are using a new pipeline: :api_auth. This pipeline will use Guardian to check if the connection has a valid token already in it or not.

Lets add this Guardian Pipeline helper. Create a file named pipeline.ex inside lib/toltec/auth/

# lib/toltec/auth/pipeline.ex

defmodule Toltec.Auth.Pipeline do
  use Guardian.Plug.Pipeline,
    otp_app: :toltec,
    module: Toltec.Auth.Guardian,
    error_handler: Toltec.Auth.ErrorHandler

  plug(Guardian.Plug.VerifyHeader)
  plug(Guardian.Plug.EnsureAuthenticated)
  plug(Guardian.Plug.LoadResource)
end

Essentially checks that a request made to our app has a header with the token, ensure that the token is valid and, if it is, loads the resource automatically (that is, loads the user corresponding to the token's claims["sub"] value in the encrypted token).

The Guardian Pipeline will need a module to handle the error it may found. So add a error_handler.ex file in lib/toltec/auth like this:

# lib/toltec/auth/error_handler.ex

defmodule Toltec.Auth.ErrorHandler do
  import Plug.Conn

  def auth_error(conn, {:invalid_token, _reason}, _opts),
    do: response(conn, :unauthorized, "Invalid Token")

  def auth_error(conn, {:unauthenticated, _reason}, _opts),
    do: response(conn, :unauthorized, "Not Authenticated")

  def auth_error(conn, {:no_resource_found, _reason}, _opts),
    do: response(conn, :unauthorized, "No Resource Found")

  def auth_error(conn, {type, _reason}, _opts), do: response(conn, :forbidden, to_string(type))

  defp response(conn, status, message) do
    body = Poison.encode!(%{error: message})

    conn
    |> put_resp_content_type("application/json")
    |> send_resp(status, body)
  end
end

Consume the API

Let's try our API. This is hard as the app has no web rendering at all. All the interaction is through REST calls and both the requests and response will be encoded in JSON. So we need a client to connect and use our API.
There are extensions for Chrome browser to consume REST APIs, like Advanced REST client. Surely there are native Window apps to do the same. For macOS I'm using the amazing Insomnia app. For this tutorial we'll just use curl to do the requests.

First, ensure the app is running

mix phx.server
[info] Running ToltecWeb.Endpoint with Cowboy using http://0.0.0.0:4000

Now, let's do a login request. This needs to be a POST request to the /api/sessions route. And we need to pass the email and password as parameters. We already have one user in our app inserted in our seeds.exs. Use that one

curl --request POST \
  --url http://localhost:4000/api/sessions \
  --header 'authorization: Bearer ' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data 'email=user%40toltec&password=user%40toltec'
{
    "meta":{
        "token":"eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJ0b2x0ZWMiLCJleHAiOjE1MzEzNTEzMzAsImlhdCI6MTUyODkzMjEzMCwiaXNzIjoidG9sdGVjIiwianRpIjoiMjQ1ZjUyMjAtZWRmMi00OWM5LThiZmMtYWJkNTU4ZTRlYjU4IiwibmJmIjoxNTI4OTMyMTI5LCJzdWIiOiIxIiwidHlwIjoiYWNjZXNzIn0.AMtC7MyvkMqXKyMyV3oBvkVBgnWNTPxDAKaFx0xgfq_ubQ9XbUJH2ZqoRKCxWE0BUUEPq_GYxNdGXPzi72W_Tg"
    },
    "data":{
        "name":"some user",
        "id":1,
        "email":"user@toltec"
    }
}

Great, we got a response that includes the user and the token value.

Let's try now the logout request. This is a DELETE request that only needs to include the token as a header. I haven't metioned the format of the header but it needs to be in the format

authorization: Bearer <jwt_value>

So for this logout request, let's use curl like this, using the JWT value from the previous step

curl --request DELETE \
  --url http://localhost:4000/api/sessions \
  --header 'authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJ0b2x0ZWMiLCJleHAiOjE1MzEzNTEzMzAsImlhdCI6MTUyODkzMjEzMCwiaXNzIjoidG9sdGVjIiwianRpIjoiMjQ1ZjUyMjAtZWRmMi00OWM5LThiZmMtYWJkNTU4ZTRlYjU4IiwibmJmIjoxNTI4OTMyMTI5LCJzdWIiOiIxIiwidHlwIjoiYWNjZXNzIn0.AMtC7MyvkMqXKyMyV3oBvkVBgnWNTPxDAKaFx0xgfq_ubQ9XbUJH2ZqoRKCxWE0BUUEPq_GYxNdGXPzi72W_Tg' --verbose
*   Trying ::1...
* TCP_NODELAY set
* Connection failed
* connect to ::1 port 4000 failed: Connection refused
*   Trying 127.0.0.1...
* TCP_NODELAY set
* Connected to localhost (127.0.0.1) port 4000 (#0)
> DELETE /api/sessions HTTP/1.1
> Host: localhost:4000
> User-Agent: curl/7.54.0
> Accept: */*
> authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJ0b2x0ZWMiLCJleHAiOjE1MzEzNTEzMzAsImlhdCI6MTUyODkzMjEzMCwiaXNzIjoidG9sdGVjIiwianRpIjoiMjQ1ZjUyMjAtZWRmMi00OWM5LThiZmMtYWJkNTU4ZTRlYjU4IiwibmJmIjoxNTI4OTMyMTI5LCJzdWIiOiIxIiwidHlwIjoiYWNjZXNzIn0.AMtC7MyvkMqXKyMyV3oBvkVBgnWNTPxDAKaFx0xgfq_ubQ9XbUJH2ZqoRKCxWE0BUUEPq_GYxNdGXPzi72W_Tg
>
< HTTP/1.1 204 No Content
< server: Cowboy
< date: Wed, 13 Jun 2018 23:23:27 GMT
< content-length: 11
< content-type: application/json; charset=utf-8
< cache-control: max-age=0, private, must-revalidate
< x-request-id: 2krtnfgdqhj1inb4jg0000r5
<
* Excess found in a non pipelined read: excess = 11 url = /api/sessions (zero-length body)
* Connection #0 to host localhost left intact

As you can see, the API returned a 204 response (no content), just as we specified on the session_controller.ex.

Finally let's try the new user creation. Let's do a POST request to /api/users/

curl --request POST \
  --url http://localhost:4000/api/users \
  --header 'authorization: Bearer ' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data 'email=miguel%40toltec&password=miguel%40toltec&name=Miguel%20Coba'
{
    "meta":{
        "token":"eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJ0b2x0ZWMiLCJleHAiOjE1MzE1NjUxODYsImlhdCI6MTUyOTE0NTk4NiwiaXNzIjoidG9sdGVjIiwianRpIjoiNTYxODY1MzQtNGZhNi00YWJkLWEwOTUtZTEyZTgzN2QzMmM4IiwibmJmIjoxNTI5MTQ1OTg1LCJzdWIiOiIyIiwidHlwIjoiYWNjZXNzIn0.CzZO0LgfqxwZ7S1Qy6lgVNrrjqacdl7fdEhVOnmt6LoXEBdN1muK1xRBDQOlll8h_lWV7PIJoZMFWUTzmcPuLg"
    },
    "data":{
        "name":"Miguel Coba",
        "id":2,
        "email":"miguel@toltec"
    }
}

You can find the source code, with tests, in the repo here in the branch part-02.

After cloning it, run the tests and verify that everything is alright:

mix test
......................................

Finished in 0.6 seconds
38 tests, 0 failures

That's it. We have added a router that accepts request to create new users, login and logout them and extend their sessions. There is no html responded, only JSON.

In part 3 we'll start with the frontend Elm app.