Add authentication to your Rails app without all the icky-ness of passwords. Magic link authentication, if you will. We call it passwordless.
Add to your bundle and copy over the migrations:
$ bundle add passwordless
$ bin/rails passwordless_engine:install:migrations
See Upgrading to Passwordless 1.0 for more details.
Passwordless creates a single model called Passwordless::Session
. It doesn't come with its own User
model, it expects you to create one:
$ bin/rails generate model User email
Then specify which field on your User
record is the email field with:
class User < ApplicationRecord
validates :email,
presence: true,
uniqueness: { case_sensitive: false },
format: { with: URI::MailTo::EMAIL_REGEXP }
passwordless_with :email # <-- here!
end
Finally, mount the engine in your routes:
Rails.application.routes.draw do
passwordless_for :users
# other routes
end
Passwordless doesn't give you current_user
automatically. Here's how you could add it:
class ApplicationController < ActionController::Base
include Passwordless::ControllerHelpers # <-- This!
# ...
helper_method :current_user
private
def current_user
@current_user ||= authenticate_by_session(User)
end
def require_user!
return if current_user
save_passwordless_redirect_location!(User) # <-- optional, see below
redirect_to root_path, flash: { error: 'You are not worthy!' }
end
end
Et voilà:
class VerySecretThingsController < ApplicationController
before_action :require_user!
def index
@things = current_user.very_secret_things
end
end
To make Passwordless look like your app, override the bundled views by adding your own. You can manually copy the specific views that you need or copy them to your application with rails generate passwordless:views
.
Passwordless has 2 action views and 1 mailer view:
# the form where the user inputs their email address
app/views/passwordless/sessions/new.html.erb
# the form where the user inputs their just received token
app/views/passwordless/sessions/show.html.erb
# the email with the token and magic link
app/views/passwordless/mailer/sign_in.text.erb
See the bundled views.
Because your User
record is like any other record, you create one like you normally would. Passwordless provides a helper method to sign in the created user after it is saved – like so:
class UsersController < ApplicationController
include Passwordless::ControllerHelpers # <-- This!
# (unless you already have it in your ApplicationController)
def create
@user = User.new(user_params)
if @user.save
sign_in(build_passwordless_session(@user)) # <-- This!
redirect_to(@user, flash: { notice: 'Welcome!' })
else
render(:new)
end
end
# ...
end
By default, Passwordless uses the resource name given to passwordless_for
to generate its routes and helpers.
passwordless_for :users
# <%= users_sign_in_path %> # => /users/sign_in
passwordless_for :users, at: '/', as: :auth
# <%= auth_sign_in_path %> # => /sign_in
Also be sure to
specify ActionMailer's default_url_options.host
.
To customize Passwordless, create a file config/initializers/passwordless.rb
.
The default values are shown below. It's recommended to only include the ones that you specifically want to modify.
Passwordless.configure do |config|
config.default_from_address = "[email protected]"
config.parent_mailer = "ActionMailer::Base"
config.restrict_token_reuse = false # Can a token/link be used multiple times?
config.token_generator = Passwordless::ShortTokenGenerator.new # Used to generate magic link tokens.
config.expires_at = lambda { 1.year.from_now } # How long until a signed in session expires.
config.timeout_at = lambda { 10.minutes.from_now } # How long until a token/magic link times out.
config.redirect_back_after_sign_in = true # When enabled the user will be redirected to their previous page, or a page specified by the `destination_path` query parameter, if available.
config.redirect_to_response_options = {} # Additional options for redirects.
config.success_redirect_path = '/' # After a user successfully signs in
config.failure_redirect_path = '/' # After a sign in fails
config.sign_out_redirect_path = '/' # After a user signs out
end
By default, Passwordless sends emails. See Providing your own templates. If you need to customize this further, you can do so in the after_session_save
callback.
In config/initializers/passwordless.rb
:
Passwordless.configure do |config|
config.after_session_save = lambda do |session, request|
# Default behavior is
# Passwordless::Mailer.sign_in(session).deliver_now
# You can change behavior to do something with session model. For example,
# SmsApi.send_sms(session.authenticatable.phone_number, session.token)
end
end
By default Passwordless generates short, 6-digit, alpha numeric tokens. You can change the generator using Passwordless.config.token_generator
to something else that responds to call(session)
eg.:
Passwordless.configure do |config|
config.token_generator = lambda do |session|
"probably-stupid-token-#{session.user_agent}-#{Time.current}"
end
end
Passwordless will keep generating tokens until it finds one that hasn't been used yet. So be sure to use some kind of method where matches are unlikely.
The timeout is the time by which the generated token and magic link is invalidated. After this the token cannot be used to sign in to your app and the user will need to request a new token.
The expiry is the expiration time of the session of a logged in user. Once this is expired, the user is signed out.
Note: Passwordless' session relies on Rails' own session and so will never live longer than that.
To configure your Rails session, in config/initializers/session_store.rb
:
Rails.application.config.session_store :cookie_store,
expire_after: 1.year,
# ...
By default Passwordless will redirect back to where the user wanted to go if it knows where that is -- so you'll have to help it. Passwordless::ControllerHelpers
provide a method:
class ApplicationController < ActionController::Base
include Passwordless::ControllerHelpers # <-- Probably already have this!
# ...
def require_user!
return if current_user
save_passwordless_redirect_location!(User) # <-- this one!
redirect_to root_path, flash: {error: 'You are not worthy!'}
end
end
This can also be turned off with Passwordless.config.redirect_back_after_sign_in = false
.
By default Passwordless uses the passwordless_with
column to case insensitively fetch the user resource.
You can override this by defining a class method fetch_resource_for_passwordless
in your user model. This method will be called with the down-cased, stripped email
and should return an ActiveRecord
instance.
class User < ApplicationRecord
def self.fetch_resource_for_passwordless(email)
find_or_create_by(email: email)
end
end
By default, a token/magic link can be used more than once.
To change, in config/initializers/passwordless.rb
:
Passwordless.configure do |config|
config.restrict_token_reuse = true
end
To help with testing, a set of test helpers are provided.
If you are using RSpec, add the following line to your spec/rails_helper.rb
:
require "passwordless/test_helpers"
If you are using TestUnit, add this line to your test/test_helper.rb
:
require "passwordless/test_helpers"
Then in your controller, request, and system tests/specs, you can utilize the following methods:
passwordless_sign_in(user) # signs you in as a user
passwordless_sign_out # signs out user
There's no reason that this approach should be less secure than the usual username/password combo. In fact this is most often a more secure option, as users don't get to choose the horrible passwords they can't seem to stop using. In a way, this is just the same as having each user go through "Forgot password" on every login.
But be aware that when everyone authenticates via emails, the way you send those mails becomes a weak spot. Email services usually provide a log of all the mails you send so if your email delivery provider account is compromised, every user in the system is as well. (This is the same for "Forgot password".) Reddit was once compromised using this method.
Ideally you should set up your email provider to not log these mails. And be sure to turn on non-SMS 2-factor authentication if your provider supports it.
- OTP JWT -- Passwordless JSON Web Tokens
MIT