Phoenix is a web framework built on Elixir. Coherence is a fully featured, configurable authentication system for Phoenix. In this post we'll discuss how to get setup and running with Coherence.

If you'd like to follow along check out my Github project.

Why Coherence?

Coherence is not the only authentication package for Phoenix. There are several others. You may even have heard one called Guardian. Guardian is an authentication package for Elixir and Phoenix. I haven't used it much although from what I can tell it's is very different then Coherence. Guardian uses JWT tokens while Coherence uses several authentication plugs like Sessions, HTTP basics and database session persistence.

Coherence has several modules that makes authentication easier to implement. See the list below. (This was taken from the GitHub page)

  • Database Authenticatable: handles hashing and storing an encrypted password in the database.
  • Invitable: sends invites to new users with a sign-up link, allowing the user to create their account with their own password.
  • Registerable allows anonymous users to register a users email address and password.
  • Confirmable: new accounts require clicking a link in a confirmation email.
  • Recoverable: provides a link to generate a password reset link with token expiry.
  • Trackable: saves login statistics like login counts, timestamps, and IP address for each user.
  • Lockable: locks an account when a specified number of failed sign-in attempts has been exceeded.
  • Unlockable With Token: provides a link to send yourself an unlock email.
  • Rememberable: provides persistent login with 'Remember me?' check box on login page.

After the plugin is installed in the phoenix project you can install any or all of the modules with mix coherence.install command. Coherence will install name spaced templates and views to make this process even easier. To check out how to use coherence run mix help coherence.install to see all the options available.

One last thing to remember is that Coherence is very new and is changing. I'll try to keep this blog updated as new changes are added. If all else fails check out the official Github page if you need help or feel free to leave a comment below!

Setup

We'll assume before we start that you have Erlang, Elixir, Node and Phoenix installed. If not, you can check out my last Phoenix post where I describe how to get started with Phoenix. You can also check out the official documentation too.

Let's begin by creating a new application called authExample.

$ mix phoenix.new authexample #press 'Y' to install deps
$ cd authexample
$ mix ecto.create

Make sure the ecto.migrate command runs without errors. If you see errors you may want to check out the database setup in config/dev.exs. Verify the login and password is correct.

Phoenix can generate boilerplate files for us, to make creating an application quicker. The phoenix.gen.html command creates a resource. This resource will include the schema, view, controller, migration file, templates and test files.

$ mix phoenix.gen.html Post posts title:string body:text

This command will create a resource called posts. We'll use this basic route to create, edit and delete posts, as if we were creating a blog application. We will first set it up without authentication, then we'll add authentication and see how that works.

Creating a Basic Post

(Without Authentication)

We need to update the router for our new post route.

// web/router.ex
...
 scope "/", Authexample do   
    pipe_through :browser # Use the default browser stack 
    resources "/posts", PostController 
    get "/", PageController, :index 
  end
...

In the Authexample "/" scope add the resources line. The resources macro adds eight clauses of the match/3 function. This will add all the HTTP verbs (GET, POST, PUT, DELETE, etc) for this new post route.

Next you'll need to run the migration.

$ mix ecto.migrate

This will add the posts table.

Let's take a look at our routes by running mix phoenix.routes.

Compiling 9 files (.ex)  
Generated authexample2 app  
post_path  GET     /posts           Authexample.PostController :index  
post_path  GET     /posts/:id/edit  Authexample.PostController :edit  
post_path  GET     /posts/new       Authexample.PostController :new  
post_path  GET     /posts/:id       Authexample.PostController :show  
post_path  POST    /posts           Authexample.PostController :create  
post_path  PATCH   /posts/:id       Authexample.PostController :update  
           PUT     /posts/:id       Authexample.PostController :update
post_path  DELETE  /posts/:id       Authexample.PostController :delete  
page_path  GET     /                Authexample.PageController :index  

As you can see these were all added by the resources macro we added into the route.

Fire up the web server and let's take a look!

$ mix phoenix.server

Look at the new posts route at http://localhost:4000/posts. This was all generated by Phoenix without much additional effort. Very neat!

Adding Authentication With Coherence

To get Coherence running lets install it in our mix file.

We'll need to add it to the application array first.

// mix.exs
...
     applications: [:phoenix, :phoenix_pubsub, :phoenix_html, :cowboy, :logger, :gettext,
                    :phoenix_ecto, :postgrex, :coherence]]

...

Next add it to our list of dependencies.

// mix.exs
...
  defp deps do
    [{:phoenix, "~> 1.2.1"},
     {:phoenix_pubsub, "~> 1.0"},    
     {:phoenix_ecto, "~> 3.0"},
     {:postgrex, ">= 0.0.0"},
     {:phoenix_html, "~> 2.6"},
     {:coherence, "~> 0.3"},
     {:phoenix_live_reload, "~> 1.0", only: :dev},
     {:gettext, "~> 0.11"},
     {:cowboy, "~> 1.0"}]
  end
...

And now we can install our dependencies.

$ mix deps.get

At this point we have a choice. Ideally, we can just install the modules we want with coherence. For the purpose of this tutorial we'll use the --full-invitable argument. This will install all the modules except confirmable.

$ mix coherence.install --full-invitable

Let's create a protected route. In this example we want a protected route to redirect a user to the login page, if the user is not logged in. If the user logs in correctly they can then see the protected route. If they enter the incorrect password they get an error.

Let's make the posts route protected. Per the documentation we'll need to add the Coherence.Router, a few pipelines and some new scopes.

First let's add that Coherence router to the top of the file.

// web/router.ex
defmodule Authexample.Router do  
  use Authexample.Web, :router 
  use Coherence.Router        #new Coherence Router
...

Adding the Coherence.Router will give us access to the routes Coherence created for us.

In the same file, add in the browser and protected pipeline (Remember to delete the existing browser pipeline first, or just add the Coherence.Authentication.Session to the bottom of it)

// web/router.ex
...
pipeline :browser do  
    plug :accepts, ["html"]    
    plug :fetch_session        
    plug :fetch_flash          
    plug :protect_from_forgery 
    plug :put_secure_browser_headers
    plug Coherence.Authentication.Session  # Add this
  end

  pipeline :protected do
    plug :accepts, ["html"]
    plug :fetch_session
    plug :fetch_flash
    plug :protect_from_forgery
    plug :put_secure_browser_headers
    plug Coherence.Authentication.Session, protected: true
  end
...

Next add these scopes.

// web/router.ex
...
  # Add this block
  scope "/" do
    pipe_through :browser
    coherence_routes
  end

  # Add this block
  scope "/" do
    pipe_through :protected
    coherence_routes :protected
  end
...

Finally we can now add a new protected route to posts. Delete the resources macro out of the AuthExample "/" scope and add it to a new protected scope.

// web/router.ex
...
  scope "/", Authexample do    
    pipe_through :protected # Use the default browser stack 
    resources "/posts",PostController
  end
...

This will protect the posts route and by convention will redirect the user to one of the built in routes we just created with coherence if the user isn't logged in. (You can check out all the routes Coherence created by running mix phoenix.routes)

The home page will not be changed and will not require a login.

The last thing we need to do is seed our database. Since we are using database authentication let's add a new Test user.

// priv/repo/seeds.exs
Authexample.Repo.delete_all Authexample.User

Authexample.User.changeset(%Authexample.User{}, %{name: "Test User", email: "testuser@example.com", password: "secret", password_confirmation: "secret"})  
|> Authexample.Repo.insert!

Before we run this let's make sure that all our migrations have been run.

$ mix ecto.migrate

This will make sure that all our tables have been created, including the user one for authentication.

Run this command to seed the database with our new test user. (If you run into any errors make sure that you didn't change the application name otherwise the changeset will fail. The names must match)

$ mix run priv/repo/seeds.exs

There it is! Let's fire up the app and see if it works!

$ mix phoenix.server

Head over to http://localhost:4000/posts.

Now it wants us to login! Put in our test user information, and try to login. (Email: testuser@example.com Password: secret)

That's it we are in!

Conclusion

In this tutorial showed how easy it is getting started with Coherence. There is a lot more we could do. If you like, try to implement a logout button and try out the "Need An Account" button. See how it works!

Take care! If you like this post and you want to learn more, sign up below to get on my list. I'm constantly sending out tips and tricks on the latest frameworks! Thanks!