NoPassword
NoPassword is a toolkit that makes it easy to implement temporary, secure login codes initiated from peoples' web browsers so they can login via email, SMS, CLI, QR Codes, or any other side-channel. NoPassword also comes with a pre-built "Login with Email" flow so you can start using it right away in your Rails application.
Installation
Add this line to your Rails application's Gemfile by executing:
$ bundle add nopassword
Next copy over the migrations, controllers, and views that you'll customize later:
$ bundle exec rails generate nopassword:install
Then run the migrations:
$ rake db:migrate
Finally, restart the development server and head to http://localhost:3000/email_authentication/new
.
Usage
Once NoPassword is installed, it can be customized directly from the controller and views that were installed. Start by openining the app/controllers/email_authentications_controller.rb
file and you'll see code that looks like:
class EmailAuthenticationsController < NoPassword::EmailAuthenticationsController
# Override with your own logic to do something with the valid data. For
# example, you might setup the current user session here via:
#
# ```
# def verification_succeeded(email)
# self.current_user = User.find_or_create_by! email: email
# redirect_to dashboard_url
# end
# ```
def verification_succeeded(email)
redirect_to root_url
end
# ...
end
You'll want to customize this for your application. For example, if you already have an application that uses a library like devise
, you could setup a login-by-email flow like this:
class EmailAuthenticationsController < NoPassword::EmailAuthenticationsController
def verification_succeeded(email)
self.current_user = User.find_or_create_by! email: email
redirect_to root_url
end
# ...
end
Why bother?
Passwords are a huge pain. How you ask?
People choose weak passwords - Most people choose weak passwords that are easy to remember and type. In a stupid game of cat and mouse, the world has fought back with password complexity validations that drive people insane and make passwords really hard to remember.
People forget passwords - When people forget their passwords they have to go through a whole reset process that sends people some sort of code via Email, SMS, or any other side-channel. Why not just authenticate this way?
Password fatigue - People get tired of creating passwords for a website. Its a breath of fresh air when they can plugin an email address, get a code, and not have to manage yet another password.
Security
It's paramount to understand how your authentication systems are working so you can assess whether or not the risks they present are worth it. NoPassword is no different; it makes certain trade-offs that you need to assess for your application.
How it works
User requests a code by entering an email address. The email address is validated based on if its well-formed or not. No other validations take place.
If the email address is well-formed, Rails generates a random 6 digit number and a salt. The 6 digit number is emailed to the end-user and the salt is persisted in the browser they're using to login to the application.
Rails also encrypts the email address via a
NoPassword::Secret
, The combination of the code and the salt, provided by the user, is what's needed to unlock the secret.The user receives the email, views the code, and enters it into the open browser window.
- If they enter the wrong code, the
remaining_attempts
field is decremented. If they exhaust all attempts, they have to request a new code and start the process over. - If the end-user waits until after the
expires_at
field to enter the, they have to request a new code and start the process over. - If the user enters the correct code within the alloted
remaining_attempts
andexpires_at
, thedata
from theSecret
is decrypted and made available to your application.
- If they enter the wrong code, the
Worth noting; none of the steps above require a cookie to function properly.
Features
NoPassword deploys the following features to mitigate brute force attacks:
Limit the number of times a code can be entered
NoPassword ships with NoPassword::Secret#remaining_attempts
, which is decremented each time the user enters a code. When there's 0 remaining attempts, the secret is destroyed and the user has to request a new, uniquely generated code. By default, NoPassword gives end-users 3 attempts to try the code.
A randomly generated salt must also be provided with the code
The salt is hidden from the user by embedding it into the form payload that's posted back to the server with the code. This means an attack would have to somehow get this salt, in addition to the code, to successfully verify the secret.
The salt is not emailed or distributed to the end-user: it is kept in the browser they're using to authenticate. If an attacker intercepted the code from the side-channel, they would also need access to the salt.
Secrets expire
In addition to the salt and remaining attempts, a secret also has NoPassword::Secret#expires_at
, which limits the amount of time a user has to guess the secret. By default, NoPassword gives end-users 5 minutes to enter the code.
Does not store personally identifying information ("PII")
NoPassword makes a best effort to prevent PII from being stored on the server during the authentication & authorization process. Instead the data is persisted on the client via a data
key, and is verified on each request to ensure the client did not tamper with the orignal PII for the final authentication request. The PII is revealed after the user successfully verifies their email address.
NoPassword does not prevent other pieces of your infrastructure from logging PII, so you'll need to do your dilligence to ensure nothing is logged if your goal is to provide your users with strong privacy garauntees.
No session or cookies required
NoPassword persists its state on the client and in an encrypted format on the server; thus a session or cookie is not required for the verification process. This serves two purposes:
Privacy - The initial authorization and verification process doesn't use cookies, so in theory if you run a tight ship, you won't have to display cookie banners during the authorization and verification process.
API compatibility - The main reason NoPassword doesn't use cookies or sessions is so it can be used to authenticate via an API. This is useful for hybrid mobile app scenarios where a user may request a login code via a native UI.
Architecture
NoPassword takes a PORO approach to its architecture, meaning you can extend its behavior via compositions and inheritence. Because of this PORO approach, most of the configuration happens on the objects themselves via inheritance instead of a configuration file. This is a similar approach to how authologic implements their authentication framework for users.
Because of this modular approach, NoPassword can be used out of the box for many use cases including:
- Login via Email
- Verify emails for logged in users
- Reset passwords for logged in users
NoPassword could be extended to work for other side-channel use cases too like login via SMS, QR code, etc.
OAuth Authorizations
NoPassword has OAuth controllers that are designed to be the smallest possible integration with providers. To use them, create a controller in your Rails project and inherit from NoPassword::OAuth::GoogleAuthorizationsController
# ./app/controllers/google_authorizations_controller.rb
class GoogleAuthorizationsController < NoPassword::OAuth::GoogleAuthorizationsController
CLIENT_ID = ENV["GOOGLE_CLIENT_ID"]
CLIENT_SECRET = ENV["GOOGLE_CLIENT_SECRET"]
SCOPE = "openid email profile"
protected
# Here's what the callback returns.
# {"sub"=>"117509553887278399680",
# "name"=>"Brad Gessler",
# "given_name"=>"Brad",
# "family_name"=>"Gessler",
# "picture"=>"https://lh3.googleusercontent.com/a/AAcHTtcA4Mc7yx4ABlghdRp7GzkssdmccudQu6MhlItL259oTiJs=s96-c",
# "email"=>"[email protected]",
# "email_verified"=>true,
# "locale"=>"en"}
def (user_info)
user = User.find_or_create_by(email: user_info.fetch("email"))
user ||= user_info.fetch("name")
self.current_user = user
redirect_to root_url
end
def
# Handle the error, perhaps redirect to a different login screen.
end
end
Then in routes.rb
add the following:
# ./config/routes.rb
resource :google_authorization
From your application, you'll need to kick off authorization flows by firing a non-Turbo POST request to /google_authorization
. In this example, I create a /google_authorization/new
page that is accessible via a GET
request. In practice you'd probably make this a partial that you'd include on a /sign-in
page.
<!-- ./app/views/google_authorization/new.html.erb -->
<h1>Login with Google</h1>
<% form_tag action: google_authorization_path do %>
<%= submit_tag "Login with Google" %>
<% end %>
Don't forget to login to the Google Developer Console at https://code.google.com/apis/console/ and get your API keys for the ENV vars above and add the /google_authorization
URL to the domains Google is authorized to redirect back to.
Motivations
Understanding why something was created is important to understanding it better.
Why was NoPassword created?
The gems I evaluated all did more than I wanted them to:
passwordless - Same idea as this gem, but it tries to do too much by including
current_user
and all of the before_action callbacks. Ultimately this gem wasn't suitable for me because I found they way its architected makes it difficult to extend or plug into existing application code.devise-passwordless - This would be a good solution if you're already using devise, but like passwordless, I didn't want a gem that got into the business of
current_user
. Additionally, for new passwordless-only applications, it doesn't make sense to start with devise since it makes many assumptions about requiring a username and password.
NoPassword only worries about generating codes and creating a secure environment for end-users to validate the codes.
Additionally, as I was using OmniAuth in my projects to handle OAuth authorizations, I noticed it felt more difficult than it should be, so I started creating OAuth controllers to simplify the process. I've included them here in case you find them useful.
Why was it not built on devise, warden, or ominauth?
I initially thought this would make for a great OmniAuth strategy, but quickly realized OmniAuth has a goal of being agnostic to rails and ships Rack middleware. I needed something more integrated into Rails controllers and views so that I could more easily extend in various projects.
Additionally, I found OmniAuth was more difficult to configure for OAuth in Rails than it should be. OmniAuth required a ./config/initializers/omniauth.rb
file that builds a Rack middleware. This Rack middleware then had some hard coded URLs that would be intercepted from Rails, which made it difficult to reason between controller routes and Rack middleware routes. The NoPassword::OAuth controllers solve that problem by having both configuration and logic live in a single controller file.
Devise already has devise-passwordless, but it tries to do too much for my purposes by managing user authorization. I needed something that stopped short of managing user authorization.
Contributing
I'd like to build out a set of controllers, views, etc. for common use cases for codes, like SMS, QRCode, and email. If you'd like to contribute, lets talk about it at https://github.com/rocketshipio/nopassword/discussions/categories/ideas before you code anything and go over architectural principals, how to distribute, etc.
License
The gem is available as open source under the terms of the MIT License.