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.