Well hello there! I've recently been doing more and more in Hanami and wanted to share some of my experiences and thoughts about it. So here I am with a blog post about authentication in Hanami (made on version 2.1.1).
Current State of Authentication in Hanami and Rails
There is no Hanami specific authentication library. Rails has a plethora of solutions, but nothing was created for Hanami (at least for the current version). There are framework agnostic tools though. OAuth solutions are like that, JWT, libraries like Rodauth.
The last one is particularly interesting for Hanami since it is very much in the same "spirit" in terms of design and it is also the most advanced solution on the ruby market.
However for smaller apps it might be an overkill. In "real-life" production systems, overengineering is one of the biggest crimes. This is true any framework and technology, so in Rails you might want to use Rodauth since it is big and interesting and challenging, but then again, if you are building a simple greenfield MVP you do not have the time or need, for a big, complex solution. In those cases Rails developers usually go for Devise. It is one of the most known Rails gems, in multiple Rails surveys it was both number 1 in popularity, likability and "most frustrating" rankings.
It is no surprise, since the gem makes some things really, really simple, but some other things... well let's just say it can get in the way. This is the thing with libs that do a lot. There comes a time where they stop helping, and the time saved, dwindles away when trying to bypass their limitations.
Devise is build on top of another library and if you ever had to customize Devise, you probably saw that underlying lib. It is called Warden
Warden
Warden is a general Rack authentication framework that provides a mechanism to hook into any Rack application and handle authentication. It is a simple and flexible framework that allows you to use a wide range of authentication strategies in your applications.
If the times of last updates to the repo worry you, rest assured. It is well maintained, and there is no need for constant updates. It is a mature library that does not need to be updated every week. It is an interesting case for conversation about maintainability of open source. Often we are taken back by the timestamps of last updates on certain gems, libs. We rarely think that they are not getting updated cause there is no need for it. But that is a big topic, for another time.
Right now just keep in mind that Devise depends on Warden so as long as it does, and Devise is maintained, Warden will be too.
We will be using it, since it is a low level lib, requires us to do a lot of things ourselves. Something that Hanami encourages a lot (and enforces). It gives us just enough to boost our work on authentication features, but does not hold us back, by giving us too many things we do not need, does not hide implementations and is very explicit. So it is very inline with Hanami philosophy and design.
Our task
We will be adding a simple authentication (email + password) to a basic Hanami application. This will include handling secure password storage, registering, logging in.
Existing setup
We have a Hanami 2.1 application ready, with persistence added (ROM-RB) and a frontend with daisyUI (TailwindCSS extension). If you want more links to those, check out my previous post about Hanami. In general a new Hanami 2.1 app is enough, as long as you got persistence in it.
Adding Warden
After adding it to our gemfile and running bundle install (I'll skip those for brevity), we need to add few pieces of setup. First we go to our config
# config/app.rb
require "hanami"
require "warden"
module Libus
class App < Hanami::App
config.actions.sessions = :cookie, {
key: "libus.session",
secret: settings.session_secret,
expire_after: 60*60*24*365
}
config.middleware.use Warden::Manager do |manager|
manager.default_strategies :password
manager.failure_app =
lambda do |env|
Libus::Actions::AuthFailure::Show.new.call(env)
end
end
end
end
Also add a line to settings
# config/settings.rb
setting :session_secret, constructor: Types::String
First thing we do in settings is enabling sessions, those are disabled in Hanami by default. Enabling them requires generating a random key. You can use SecureRandom.base64(64) to generate one quickly, then put in the .env file under SESSION_SECRET key. settings.rb will read it from there and app.rb takes it from settings. Simple and very clear, something that I really love about Hanami is how it handles setting things up, like plugins, extensions, gems etc.
Another thing we added here is a failure_app which is a key concept in Warden. Devise does that part for you if you use it, so it is likely you never had to delve into it. Here we need to handle it ourselves, and we will do it by having a simple Hanami Action. This will handle failures on authentication. It requires a special app so it can do whatever you desire with a failure. Usually it is just a redirect back, but maybe some extra logic is required, like tracking attempts. If so, then the failure app is a place to use for it.
But before we implement our failure app, we should register Warden as a provider and add our first strategy. After all we cant test out failure if we do not have a system to log in.
# config/providers/warden.rb
Hanami.app.register_provider(:warden) do
prepare do
require "bcrypt"
require "warden"
end
start do
target.start(:persistence)
Warden::Strategies.add(:password) do
def valid?
params['email'] || params['password']
end
def authenticate!
user_repo = Main::Repositories::Users.new(Hanami.app["persistence.rom"])
user = user_repo.by_email(params["email"])
if user && user.password_hash == BCrypt::Engine.hash_secret(request.params["password"], user.password_salt)
return success!(user)
end
fail!("Could not log in")
end
end
Warden::Manager.serialize_into_session{|user| user.id }
Warden::Manager.serialize_from_session{|id| Main::Repositories::Users.new(Hanami.app["persistence.rom"]).by_id(id) }
end
end
This sets us up with a second most important part of Warden setup. Strategies. We are using a simple password strategy here. We check if the username and password are present, and if they are, we try to authenticate the user. If we fail, we have the failure app kicking in. If we succeed, we return the user, save his data to the session to later reuse.
This is also something that Devise does for you. It has a lot of strategies built in, and you can still add your own on top of it. Here we are doing it ourselves, it really is not that much work to get it working and we avoid a lot of middleware from Devise
Failure App
The most basic way to handle a failed attempt to enter a forbidden place is to show a simple message. Usually most apps just redirect to login page. For now we will just display a simple message for brevity, but it is a regular Hanami Action, so you can redirect here or do whatever, just showcasing that there is no magic here.
module Libus
module Actions
module AuthFailure
class Show < Main::Action
def handle(request, response)
response.body = "STRANGER DANGER"
response.status = 401
end
end
end
end
end
An important distinction is that the failure app is not the same as handling, for example, a missing current_user, on an endpoint that requires it. It is responsible for handling failed logging only, not for user trying to access an endpoint that requires a signed in user.
Database
We need to setup a Users table. Lets run a migration for that.
rake db:create_migration[create_users]
ROM::SQL.migration do
change do
create_table :users do
primary_key :id
column :name, String, null: false
column :email, String, null: false
column :password_hash, String, null: false
column :password_salt, String, null: false
end
end
end
Easy as that. We store a password hash and salt, we need Bcrypt in our app to ensure our password take bazillion years to crack if someone attempts to do it.
Lets setup our User relation and repository.
# lib/libus/persistence/relations/users.rb
module Libus
module Persistence
module Relations
class Users < ROM::Relation[:sql]
schema(:users, infer: true) do
end
end
end
end
end
# lib/libus/persistence/relations/users.rb
module Main
module Repositories
class Users < Main::Repo[:users]
commands :create, update: :by_pk, delete: :by_pk
def query(conditions)
users.where(conditions)
end
def email_taken?(email)
users.exist?(email: email)
end
def by_id(id)
users.by_pk(id).one!
end
end
end
end
Simple relations and repository is all we need to get started.
Specs
Would be nice to test all our authentication features, so lets handle setup for using Warden in our specs.
# spec/support/requests.rb
RSpec.shared_context "Rack::Test" do
# Define the app for Rack::Test requests
let(:app) do
Hanami.boot
Hanami.app
end
end
RSpec.configure do |config|
config.include Rack::Test::Methods, type: :request
config.include_context "Rack::Test", type: :request
config.include Warden::Test::Helpers, type: :request
config.after(:each, type: :request) { Warden.test_reset! }
end
# spec/requests/auth_spec.rb
RSpec.describe 'AuthenticationSpec', :db, type: :request do
context 'when action inherits from authenticated action' do
context "when user is logged in" do
let!(:user) { factory[:user, name: "Guy", email: "my@guy.com"] }
it 'succeeds' do
login_as user
get "/search/isbn", { isbn: "978-0-306-40615-7" }
expect(last_response.status).to be(200)
end
end
context "when there is no user" do
it "rejects the request, redirects" do
get "/search/isbn", { isbn: "978-0-306-40615-7" }
expect(last_response.status).to be(302)
end
end
end
end
Quite simple. The '/search/isbn' request is gonna be validated for user presence, if it fails (user is missing) we will get redirected. For now this test is red since we don't have any routes available only for current users.
Routes
We won't need much, this is how I structured my routes (only showing the relevant ones)
# New user registration
get '/register', to: 'register.new'
post "/users", to: "users.create"
# Session management
get '/login', to: 'login.new'
post "/sessions", to: "sessions.create"
delete "/logout", to: "sessions.destroy"
Actions
Lets start with a basic registration action and spec for it:
RSpec.describe Main::Actions::Users::Create, :db do
it "works with the right params" do
params = {
email: "some@email.com",
name: "John Doe",
password: "password",
password_confirmation: "password"
}
response = subject.call(params)
expect(response).to be_successful
end
context "with bad params" do
let(:params) { Hash[] }
it "fails with missing params" do
response = subject.call({})
expect(response).not_to be_successful
end
end
context "with password missmatch" do
let(:params) {
{ email: "good@email.com", name: "John Doe", password: "somepassword", password_confirmation: "differentthing" }
}
it "fails with password missmatch" do
response = subject.call(params)
expect(response).not_to be_successful
end
end
context "with email already taken" do
let!(:user) { factory[:user, name: "Guy", email: "my@guy.com"] }
let(:params) { { email: "my@guy.com", name: "John Doe", password: "password", password_confirmation: "password" } }
it "fails with" do
response = subject.call(params)
expect(response).not_to be_successful
end
end
end
Basic tests and here is how we can make them pass.
require 'bcrypt'
module Main
module Actions
module Users
class Create < Main::Action
include Deps[users_repo: "repositories.users"]
params do
required(:email).filled(:string)
required(:name).filled(:string)
required(:password).filled(:string)
required(:password_confirmation).filled(:string)
end
def handle(request, response)
halt 422, {errors: request.params.errors}.to_json unless request.params.valid?
halt 422, { errors: "Password must match the confirmation" }.to_json unless request.params[:password] == request.params[:password_confirmation]
halt 422, { errors: "This email is already taken" }.to_json if users_repo.email_taken?(request.params[:email])
password_salt = BCrypt::Engine.generate_salt
password_hash = BCrypt::Engine.hash_secret(request.params[:password], password_salt)
users_repo.create(
name: request.params[:name],
email: request.params[:email],
password_hash: password_hash,
password_salt: password_salt
)
end
end
end
end
end
I've put everything in Action object, instead of separating it into validator object and maybe some user service object, since there is very little logic, and it makes it more readable in blog post form. Once this logic expands, we will need a different abstraction layer.
With this, you just got to get yourself a registration view, with the standard email, name, password, password confirmation fields, and you are good to go. You will get a new user in the database.
To this we can add login and retrieving the current user from session.
module Main
module Actions
module Sessions
class Create < Main::Action
include Deps[users_repo: "repositories.users"]
params do
required(:email).filled(:string)
required(:password).filled(:string)
end
def handle(request, response)
halt 422, {errors: request.params.errors}.to_json unless request.params.valid?
request.env['warden'].authenticate!
user = users_repo.by_email(request.params[:email])
if user && user.password_hash == BCrypt::Engine.hash_secret(request.params[:password], user.password_salt)
request.session[:user_id] = user.id
response.redirect "/"
else
halt 401, "Unauthorized"
end
end
end
end
end
end
If you pair this up with a simple login view, you can normally enter email and password and log in into the app.
We can add a parent action for actions that require authentication that will have
before :authenticate_user
private
def authenticate_user(request, response)
response.redirect_to("/login") unless request.env['warden'].user # request.env['warden'].user is also where you get the current user from. It will be a ROM struct cause of our warden setup from before
end
An examplery action, that will make the previous red spec (the one with redirection) green
module Main
module Actions
module IsbnSearch
class Show < Libus::Actions::AuthenticatedAction
params do
required(:isbn).filled(:string)
end
def handle(request, response)
halt 422, {errors: request.params.errors}.to_json unless request.params.valid?
Main::Workers::IsbnSearch.perform_async(request.params[:isbn])
response.render(view, isbn: request.params[:isbn])
end
end
end
end
end
Log out
Logging out is the simplest part of it all.
In my navbar I have a bit that goes like this:
<% if warden.user %>
<li class="justify-center">
<%= form_for :logout, 'logout', method: :delete do %>
<button type="submit">Logout</button>
<% end %>
</li>
<% else %>
<li class="justify-center"><a href="/login">Login</a></li>
<% end %>
Which I handle with:
module Main
module Actions
module Sessions
class Destroy < Main::Action
def handle(request, response)
request.env['warden'].logout
response.redirect_to("/")
end
end
end
end
end
Conclusion
Warden requires very little to start working, and in some parts of the code presented, you might have seen, or thought, that Devise does not really add that much there, other than some convenience. It is not exactly true, since Devise gives us (in Rails) the whole emailing system, views, resetting password, flash messages setting, password handling etc. We often modify a lot of those things and most of them rarely become an actually relevant time saver. Building an email system on your own does not take a lot of time. Modifying an existing one, that you did not wrote, and that has its code hidden in lib source code, can be far more time consuming.
Using Devise has often been a gamble for me. I either save a lot of time, or waste a bit of it. When working on Rails I have no problems using it anyway, since I have also become somewhat proficient in modifying it, but in Hanami, when I have no access to it I can better see what are the drawbacks and benefits of it. Also going on level lower in terms of libs used, gives a better understanding of systems and technologies used (sessions, password storing etc).
I am convinced that every RoR developer should at least once build their own authentication system without Devise since it makes certain things too easy and hides a lot of implementation details, that lead to better understanding of cookies, session and using those stuff, understanding where they are available are where they come from. What really happens when you call current_user and how was it set up? What can we do with data stored in session and what is stored there for the authorization purposes?
The system presented here by me is a skeleton, a starting point, to potentially complex and robust system. Feel free to fork the repo from this point and see how difficult it is to connect emails and better views, flash messages (it really isn't). It does not cost a lot of time, but gives you far better control and understanding of what you actually have in your system, while also cutting your dependencies short (devise uses more than just warden), and making your codebase generally smaller, easier to go through, expand, modify.
