Elixir: Account Management

We'll begin our Elixir journey with the account management system. Stay tuned, more are comings :)

Our project use a PostgreSQL database as datastore. We do not need any temporary datastore for now, but if we needed to we could use Mnesia for temporary persisted data.

Our authentication system is totally based upon Elixir Guardian library. Uberauth that made the previous package, also provides another library allowing us to follow the OAuth 2 standard seamlessly. We also needed the JWT token management provided by the library for our mobile device clients.

So how did we implement it ? As shown in the quick tutorial Guardian offers some modules that we used. One is Guardian.Plug allowing us to plug the authentication and authorization system directly into Phoenix. Another is Guardian.DB allowing us to store emitted tokens in a database and invalidate them if necessary. The last one that we’ll use is Guardian.Permissions for roles based authorization system.

So let’s have a look to our router.ex :

use MyAppWeb, :router

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

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

  plug(
    Guardian.Plug.Pipeline,
    module: MyApp.Account.Guardian,
    error_handler: MyApp.Account.AuthErrorHandler
  )

  plug(Guardian.Plug.VerifySession, claims: %{"typ" => "access"})

  plug(Guardian.Plug.VerifyHeader, claims: %{"typ" => "access"})

  plug(Guardian.Plug.EnsureAuthenticated)

  plug(Guardian.Plug.LoadResource)
end

pipeline :api_admin do
  plug(Guardian.Permissions.Bitwise, ensure: %{admin: [:all]})
end

pipeline :api_user do
  plug(Guardian.Permissions.Bitwise, ensure: %{user: [:all]})
end

pipeline :api_admin_or_user do
  plug(
    Guardian.Permissions.Bitwise,
    one_of: [
      %{admin: [:all]},
      %{user: [:all]}
    ]
  )
end

As you can see we defined 5 pipelines based on the required rights that our customers will need. First the :api is a simple pipeline for public routes like our health check URL. Next the :api_auth defines the protected pipeline based on our specific authentication system as of the error handler or how we should receive and parse the JWT Token. The next 3 other pipelines define the roles and actions available in our application. The last pipeline is interesting because it combines the preceding 2 roles so the user is part of the user group or the admin group.

Let’s have a closer look to our account management module that will manage our token and authorizations.

For that we’ll need to take a step back and understand how the token authentication works.

As you can see the token is generated after credentials validation (sign in) by the server. To check credentials we use a basic hash algorithm with salt so we store safely the user password. When we generate the token we also store the user role defined permissions in it so we can check in the router if the user does have the correct rights (actually this step is managed by Guardian).

defmodule MyApp.Account.Guardian do
  use Guardian,
    otp_app: :gi_api,
    permissions: %{
      default: [:all],
      admin: [:all],
      user: [:all]
    }

  use Guardian.Permissions.Bitwise

  import Ecto.Query

  alias MyApp.Repo

  alias MyApp.Account.User

  def subject_for_token(%{id: id}, _claims) do
    sub = to_string(id)

    {:ok, sub}
  end

  def subject_for_token(_, _) do
    {:error, :reason_for_error}
  end

  def resource_from_claims(%{"sub" => id}) do
    resource =
      User
      |> where(id: ^id)
      |> Repo.one!()

    {:ok, resource}
  end

  def resource_from_claims(_claims) do
    {:error, :reason_for_error}
  end

  def after_encode_and_sign(resource, claims, token, _options) do
    with {:ok, _} <- Guardian.DB.after_encode_and_sign(resource, claims["typ"], claims, token) do
      {:ok, token}
    end
  end

  def on_verify(claims, token, _options) do
    with {:ok, _} <- Guardian.DB.on_verify(claims, token) do
      {:ok, claims}
    end
  end

  def on_revoke(claims, token, _options) do
    with {:ok, _} <- Guardian.DB.on_revoke(claims, token) do
      {:ok, claims}
    end
  end

  def build_claims(claims, _resource, opts) do
    claims =
      claims
      |> encode_permissions_into_claims!(Keyword.get(opts, :permissions))

    {:ok, claims}
  end
end

defmodule MyApp.Account.AuthErrorHandler do
  use MyAppWeb, :controller

  def auth_error(conn, {_type, _reason}, _opts) do
    conn
    |> put_resp_header("content-type", "application/json")
    |> put_status(:unauthorized)
    |> render(MyAppWeb.ErrorView, "401.json")
  end
end

The AuthErrorHandler will just show a 401 Unauthorized when unable to authenticate. We could add some Logging there for debug purposes as of the reason is provided. Guardian allows us to define some custom hooks in the module to manage token serialization and deserialization. So we used it to encode the use id in the token and to get it back from database on deserialization (subject_for_token/2 and resource_from_claims/1)

We also use the default handlers provided by Guardian.DB to store the token on sign in and remove it on sign out from our database. As you can see we have a pretty customizable authentication and authorization system, so let’s see how to use it.

Next we see the defined routes for the authentication system we’ll use. We followed the Uberauth recommendations for a local login.

scope "/auth", MyAppWeb do
  pipe_through([:api])

  post("/signup", AuthController, :signup)

  get("/:provider/callback", AuthController, :callback)

  post("/:provider/callback", AuthController, :callback)
end

scope "/auth", MyAppWeb do
  pipe_through([:api_auth])

  delete("/signout", AuthController, :signout)
end

So the only protected route here is the signout which will only call the Guardian.revoke/1 function that will execute the on_revoke/3 hook defined earlier in our Account.Guardian module.

Let’s have a look to our sign in internal code to see how we generate the token and store it in the connection struct returned to clients.

def sign_in(conn, %User{email: email}, password) do
  with {:ok, %User{} = user} <- get_by_email(email) do
    case authenticate(user, password) do
      true ->
        perms =
          Enum.reduce(user.roles, %{}, fn role, acc ->
            Map.put(acc, role.name, Guardian.max())
          end)

        auth_conn = Guardian.Plug.sign_in(conn, user, %{}, ttl: {1, :day}, permissions: perms)

        {:ok, auth_conn}

      _error ->
        {:error, :not_found}
    end
  end
end

defp authenticate(user, password) when not is_nil(user) do
  Comeonin.Bcrypt.checkpw(password, user.password)
end

This is how we store the user attached roles in the token with max permissions when we authenticate successfully based on the provided password. We could add some extra information in the token using the third argument of Guardian.Plug.sign_in/4.

Now that we have an authentication system we need to define our authentication protocol to work with any client. This is where OAuth 2 is useful because it’s a known standard for authentication and resources access. For reminding, there is a simplified diagram of how it works.

In our application to be able to manage various authentication providers as presented in the diagram, we need to have a route as access redirect URL, in our example it is named: /:provider/callback.

For our local signing feature we’ll use the default provider called identity which is used for a simple login, password sign in.

def callback(%{assigns: %{ueberauth_auth: auth}} = conn, params) do
  sign_in_user(conn, basic_info(auth), params)
end

defp basic_info(%Auth{} = auth) do
  %User{email: auth.info.email, password: auth.credentials.other.password}
end

The interesting part is how is structured the uberauth object that we get from the library. It contains an info field with the provided email and a credentials field with the password. Then we call our sign_in_user/3 function showed a little earlier to attach the token to the connection.

Annnd that’s it, you should have a working Authentication/Authorization manager following the principles of OAuth 2 protocol specification. You can go much further on the subject by looking to what is a refresh token and how to manage this in your client or searching more informations on how to implement other providers like Facebook or Google auth in your application.

Next we'll see how to add a Forgot Password feature using Elixir and Phoenix.

Elixir Journey

I’ve been working on a blockchain oriented project for some months now, and I wanted to share with you this exciting journey I’m in working on a Phoenix, Elixir, Erlang stack.

For those who do not knows what the Elixir programming language is, we’ll do a real quick recap. Elixir is a programming language created on top of Erlang by a Ruby core developers. The syntax is purposely Ruby oriented, but follows the Functional Oriented Erlang programming paradigm. Erlang was created in the 90’s for telecommunication systems, thus it was designed to be concurrency oriented and offers some error recovery. On top of that we use the Phoenix framework for industry oriented development and to ease maintainability.

This story will be about how we made our system using some useful Elixir packages available on Hex package manager. It is not a tutorial about Elixir programming but I’ll try to explain as much as possible the under-layers of our choices.

So let’s begin by some of the functionalities we needed for our system. First of all we need a way for users to create an account and sign in. Then, of course, we’ve seen that we needed a forgot password feature because a password not lost is not a good password :)

Then we needed user to add, edit and delete data in the system but with the special feature of logging every modifications done to the data. The purpose is to save these modifications as a signed timestamped log stored in our datastore to keep track of them. This way everyone should be able to access the data information and check what and when was the data modified.

We also needed a notification system allowing users to be informed of administrative notifications. This particular problem is very well solved with Elixir/Phoenix as it propose a standardized Websocket implementation for communication between clients and server.

As said, we had some administrative resources to manage how the system work and to communicate with customers. So we added a role management system to protect these resources.

Because our application should be available on web browsers and mobile devices we provided a JSON API as Restful as possible :)

As you’d expect for a block chain based project we rely on some cryptography to secure our stored information data.

On top of this we also wanted to have some media attached to these resources, it could be documents or images. Of course, a thumbnail preview feature was required too.

These are the main features that were expected for the product, now we’ll dive into each one and see how we made it in Elixir. Be aware that because of time limits the proposed solutions are not always the best it could be so use this information carefully.

So stay tuned for the next post, we'll begin with account management.