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.
Next we'll see how to add a Forgot Password feature using Elixir and Phoenix.
