authkit 0.2.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e32d463ccc3d5bbb3291b087ddb3c51a4341a2c0
-  data.tar.gz: 16ce8e2e4b53acf18863c454c9def5d1e7a26818
+  metadata.gz: 8a50e83ce52b25ebf0d07f9582f6d58485ff4b67
+  data.tar.gz: 1f817df72d8bbcde3524b5da618c00ccaa48b8b3
 SHA512:
-  metadata.gz: 144e524bb9384e402ef0d0c942e46ce23469858226a354f327cd9ffeaa52b0749a29850a8eb1dac6a4d7d60eb0c7d1e952d958a67e42bb170171961080fe56c3
-  data.tar.gz: 9f9f94acc22505797557a18fd69ef532aefae1b57cc38f47bf8287f58e6b26a2f08595eaed136296fba001f798cf1f4972b6c921aa89a3adb44b4c0278139a0d
+  metadata.gz: 78a53378ab13f476cb291fdc648114a3dc0500f8e92a541e6f8f253e4f35ce0732aafe0de35b953729ec9580f49e957cb793193405512c71fdc1e6f801e794f7
+  data.tar.gz: bfa4d0d452bc397d2c8fc5c206182d1bbad95eece55250ad646b53faaf1d26eecf33f6285a41fa28f64178579a8ce879062f35a7093749449bbff165a0bbe1d4

data/README.md

@@ -4,21 +4,15 @@ A gem for installing auth into you app.
 
 ## Why?
 
-There are lots of great authentication gems out there; devise? clearance? restful_auth?
-All of these seek to solve the problem of adding authentication to your application but they all share
-one philosophy: you shouldn't need to think about authentication to build your app. For me, I find I
-spend way more time trying to figure out how to customize the tools for the few cases when my
-application needs to do something different.
+There are lots of great authentication gems out there; devise? clearance? restful_auth? All of these seek to solve the problem of adding authentication to your application but they all share one philosophy: you shouldn't need to think about authentication to build your app. For me, I find I spend way more time trying to figure out how to customize the tools for the few cases when my application needs to do something different.
 
-Authkit takes the opposite stance: auth belongs in your app. It is important and it is specific to your
-app. It only includes generators and installs itself with some specs. You customize it. Everything
-is right where you would expect it to be.
+Authkit takes the opposite stance: auth belongs in your app. It is important and it is specific to your app. It only includes generators and installs itself with some specs. You customize it. Everything is right where you would expect it to be.
+
+Of course, this stance can be very dangerous a it relies on the application developer to not interfere with the authentication mechanisms, and it makes introducing security patches difficult. This is the trade-off. Generally speaking the approaches taken within authkit are designed for the early life-cycle of a small to medium application. It can support much larger platforms, but it is likely that larger platforms will need centralized authentication mechanisms that go beyond the scope of this project.
 
 ## Features
 
-Authkit supports Ruby down to version 1.9 but targets 2.0. It is built for Rails 4. It is possible
-that it could support Rails 3.x (currently it relies on strong parameters and the Rails 4
-message verifier and `secret_key_base`). Some of the features include:
+Authkit supports Ruby down to version 1.9 but targets 2.0. It is built for Rails 4. It is possible that it could support Rails 3.x (currently it relies on strong parameters and the Rails 4 message verifier and `secret_key_base`). Some of the features include:
 
   * Signup (username or email)
   * Login/Logout
@@ -42,8 +36,7 @@ Some possible features include:
   * Third party accounts
   * Installer options (test framework, security bulletins, modules)
 
-If there is a feature you don't want to use, you just have to go and delete the generated code.
-It is your application to customize.
+If there is a feature you don't want to use, you just have to go and delete the generated code. It is your application to customize.
 
 More information is available in [FEATURES](FEATURES.md).
 
@@ -136,21 +129,150 @@ And will add some gems to your Gemfile:
     gemfile  shoulda-matchers, :test, :development
     gemfile  factor_girl_rails, :test, :development
 
-Once you have this installed you can remove the gem, however you may want to
-keep the gem installed in development as you will be able to update it
-and check for security bulletins.
+Once you have this installed you can remove the gem, however you may want to keep the gem installed in development as you will be able to update it and check for security bulletins.
 
 You'll need to migrate your database (check the migrations before you do):
 
     rake db:migrate
 
-You'll also need to connect your mailers for sending password reset instructions
-and email confirmations. (See the TODO in `user.rb`)
+You'll also need to connect your mailers for sending password reset instructions and email confirmations. (See the TODO in `user.rb`)
+
+## NOTES
+
+Authkit has a number of conventions and requirements that should be noted.
+
+* SSL expected
+* secure cookies
+* password complexity is not robust
+* username resrictions are not implemented
+* users do not need to confirm their email address to proceed
+* need a root route
+
+### SSL
+
+It is expected that your application be protected by SSL. Though it is possible to segregate your application into SSL/non-SSL areas, Authkit utilizes cookies to store remember token information and assumes that sessions are backed by a cookie store. Because of this you must use SSL to protect against Session Hijacking attacks. Cookies are marked as secure only in the production environment (see `ApplicationController#set_remember_cookie`). If you are using Authkit in a staging environment you might need to adjust this.
+
+### Password and username validation
+
+There is only a minimal amount of validation on the password. Because of this users can choose poor passwords (which are not complex or are overly common). To improve this you can adjust the validation in `user.rb`:
+
+    validates :password, presence: true, confirmation: true, length: {minimum: 6}, if: :password_set?
+
+Likewise, there are no restrictions on `username`. If you want to use this field within the URL you will need to constrain the format of the `username` field. Additionally, there may be some user names you want to explicitly disallow based on your routing setup.
+
+### Confirmation not required by default
+
+By default, users can begin using the system without confirming their email address. This simplifies the onboarding process, however it means that malicious users may be operating under false pretense. You can change this by adding a check to `ApplicationController#require_login`:
+
+    def require_login
+      deny_user(nil, login_path) unless logged_in?
+      deny_user("You need to confirm your email address before proceeding", root_path) unless current_user.email_confirmed?
+    end
+
+And then in `user.rb`:
+
+    def email_confirmed?
+      self.confirmation_token.blank?
+    end
+
+### Root route
+
+Additionally, there are several redirects that occur within Authkit (when you have successfully logged in or logged out, etc.). By default the user is redirected to the root_path in these cases. Because of this, you must define a `root` route in your `config/routes.rb`.
+
+## Tokens
+
+Authkit makes use of several kinds of tokens:
+
+* remember tokens
+* reset password tokens
+* confirmation tokens (email)
+* unlock tokens
+* one time use password tokens
+* api tokens
+
+All of the tokens are generated using `SecureRandom.urlsafe_base64(32)`. Each token has a unique index within the database to prevent conflicts but collisions are very unlikely (1/64^32). In the event that a conflict does occur an `ActiveRecord::StatementInvalid` or `ActiveRecord::RecordNotUnique` exeception will be raised.
+
+It has been suggested that tokens are essentially passwords (though quite complex ones) and that they should not be stored directly in the database. Instead tokens should be stored using Bcrypt (and stored as a token_digest) to prevent someone with read access from gaining control of an account. This is not currently implemented.
+
+Failed attempts are not currently tracked for tokens. Token misses could be used to contribute to `failed_attempts`, however in certain circumstances this could be used to disrupt service by locking accounts. Ideally, invalid tokens would be logged centrally and an existing tool like `fail2ban` could be used to restrict access.
+
+You can adjust the default token expiry in `user.rb`.
+
+Each of these tokens utilizes a different strategy to protect it from attacks.
+
+### Remember tokens
+
+Remember tokens are re-generated every-time a user logs in and the resulting token is stored in a cookie on the user's device (i.e., the browser). The cookie is encrypted, signed and only delivered over secure connections (see SSL above).
+
+Because the token is regenerated on every login, any existing remember cookies (for instance, on another device) will be immediately invalidated.
+
+Because the cookie mechanism uses `ActiveSupport#MessageVerifier` it is dependent on the security of that class. By default that class securely compares strings and decrypts using strong secret keys (the Rails `secret_key_base` specifically). This protects against timing attacks. Once the verified token is obtained, it can be safely used as part of a database query.
+
+Changing your `secret_key_base` will invalidate all existing cookies including all remember cookies. This may be a feature as it is likely that you would want to invalidate all sessions in the event your secret key was compromised.
+
+Because the token is not used directly (it must be included in the cookie), even with read access to the database an attacker cannot login without also having the ability to sign the remember cookie.
+
+Once the user logs out the token is cleared and is no longer available.
+
+### Reset password tokens
+
+When a user forgets their password they can request a password reset so that they can change their password. A new `reset_password_token` is generated when a request is made and an email is sent to the corresponding email address.
+
+It is possible to encode the resulting token using the message verifier which could later be used to validate that the token really was generated by the system.
+
+Instead the system employs a two-token approach, using both the corresponding email address and the `reset_password_token`. The token is paired with an email parameter so that the user can be found in the database. Once found the tokens can be securely compared to prevent timing attacks. The email address is chosen over the user id because the reset request was generated using the email address and thus is already known. Using the id would increase information leakage.
+
+Again, if you are not using SSL this means that the email address and token will be visible in the path information of requests.
+
+Once the password is changed, the token is cleared and is no longer available.
+
+### Confirmation tokens
+
+When a user signs up or changes their email address an email is sent to the specified address to confirm that the user really controls the email. This is done to ensure that users didn't mistype the address and also protects against malicious users impersonating well known accounts.
+
+Like password resets, these tokens are sent directly in email. In the case of email confirmation, however it is possible to require that the user be logged in to utilize the token. Because of this the tokens can easily be compared securely to prevent timing attacks.
+
+Once the email is confirmed, the token is cleared and is no longer available.
+
+### Unlock tokens
+
+Currently unlock tokens are not implemented. Once implemented unlocks will be sent to logged out users using their email address. Because of this, it is likely that any implementation of unlock tokens will function similar to password reset tokens.
+
+### API tokens
+
+Currently API tokens are not implemented. An API token implementation will not have access to a current user. Because of this the API token system can take one of two approaches:
+
+1. Using a `ActiveSupport::MessageVerifier` to generate verified tokens.
+2. Using a two token approach in the form of `api_access_key` (which is used for database lookups) and `api_secret_token` (which is compared securely).
+
+Any implementation of token authentication will likely need to support multiple tokens per account (i.e. a Tokens model). This also allows the user to directly revoke keys.
+
+In the case of API access, storing a digest of the token is not practical. Bcrypt digesting is slow and would add a significant amount of overhead if used on every request (on average 90ms with the default 10 stretches).
+
+Additionally, storing only the digest means that a user cannot login to see their API tokens. They would need to be regenerated. This might be considered a feature.
+
+## What's missing
+
+There is a significant amount of functionality that is currently unimplemented:
+
+* Use Bcrypt and token digests instead of storing actual tokens in the database (defense in depth).
+* Full name option (instead of first name and last name)
+* Notification for changes to account (security settings changed)
+* Ability to re-auth for sensitive changes (available for the current session only)
+* API token support
+* OAuth2 client support (but not logging in?) in the form of Facebook support, Twitter support, Google support
+* OAuth2 server support
+* One time password support completed
+* Add Authy or Google Authenticator support
+* Avatars (possibly this should be within uploadkit)
+* User session tracking and revoking
+* Audit logs
+* No internationalization (i18n)
+* JavaScript validation for username and email availability and password complexity
 
 ## Testing
 
-The files generated using the installer include specs. To test these you should be
-able to:
+The files generated using the installer include specs. To test these you should be able to:
 
     $ bundle install
 
@@ -158,21 +280,9 @@ Then run the default task:
 
     $ rake
 
-This will run the specs, which by default will generate a new Rails application,
-run the installer, and execute the specs in the context of that temporary
-application.
-
-The specs that are generated utilize a generous amount of mocking and stubbing in
-an attempt to keep them fast. However, they use vanilla `rspec-rails`, meaning
-they are not using mocha. The two caveats are shoulda-matchers and FactoryGirl which
-are required. It is pretty easy to remove these dependencies, it just turned out
-that more people were using them than not.
-
-## TODO
+This will run the specs, which by default will generate a new Rails application, run the installer, and execute the specs in the context of that temporary application.
 
-* Add oauth2 support (but not logging in?) in the form of facebook support, twitter support, google support
-* Add avatar support (maybe that should be uploadkit)
-* Add full name option (instead of first name and last name)name
+The specs that are generated utilize a generous amount of mocking and stubbing in an attempt to keep them fast. However, they use vanilla `rspec-rails`, meaning they are not using mocha. The two caveats are shoulda-matchers and FactoryGirl which are required. It is pretty easy to remove these dependencies, it just turned out that more people were using them than not.
 
 ## Contributing
 

data/Rakefile

@@ -16,6 +16,11 @@ namespace :spec do
   end
 end
 
+# When using sed to replace in place, don't rely on -i for POSIX compatibility
+def sed(command, filename)
+  system "sed '#{command}' #{filename} > #{filename}.tmp && mv #{filename}.tmp #{filename}"
+end
+
 namespace :generator do
   desc "Cleans up the sample app before running the generator"
   task :cleanup do
@@ -37,6 +42,9 @@ namespace :generator do
     system "cd spec/tmp/sample && bundle install"
     system "cd spec/tmp/sample && rails g rspec:install"
 
+    # Open up the root route for specs
+    sed("s/# root/root/", "spec/tmp/sample/config/routes.rb")
+
     # Make a thing
     system "cd spec/tmp/sample && rails g scaffold thing name:string mood:string"
   end

data/lib/authkit/version.rb

@@ -1,3 +1,3 @@
 module Authkit
-  VERSION = "0.2.1"
+  VERSION = "0.4.0"
 end

data/lib/generators/authkit/install_generator.rb

@@ -70,9 +70,6 @@ module Authkit
 
       insert_at_end_of_file "config/initializers/filter_parameter_logging.rb", "config/initializers/filter_parameter_logging.rb"
 
-      # Need a temp root
-      route "root 'welcome#index'"
-
       # Setup the routes
       route "get   '/email/confirm/:token', to: 'email_confirmation#show', as: :confirm"
 

data/lib/generators/authkit/templates/app/controllers/application_controller.rb

@@ -4,19 +4,22 @@
   helper_method :logged_in?, :current_user
 
   # It is very unlikely that this exception will be created under normal
-  # circumstances. Unique validations are handled in Rails, but they are
-  # also enforced at the database level to guarantee data integrity. In
-  # certain cases (double-clicking a save link, multiple distributed servers)
-  # it is possible to get past the Rails validation in which case the
-  # database throws an exception.
+  # circumstances. Unique validations are handled in Rails, but they are also
+  # enforced at the database level to guarantee data integrity. In certain
+  # cases (double-clicking a save link, multiple distributed servers) it is
+  # possible to get past the Rails validation in which case the database throws
+  # an exception.
   rescue_from ActiveRecord::RecordNotUnique, with: :record_not_unique
 
   protected
 
+  # The user is fetched using id or remember token but these come from a
+  # verified cookie (verified using secure compare) so these database calls do
+  # not need to protect against timing attacks.
   def current_user
     return @current_user if defined?(@current_user)
     @current_user ||= User.where(id: session[:user_id]).first if session[:user_id]
-    @current_user ||= User.user_from_remember_token(cookies.signed[:remember]) unless cookies.signed[:remember].blank?
+    set_current_user_from_remember_token unless @current_user
     session[:user_id] = @current_user.id if @current_user
     session[:time_zone] = @current_user.time_zone if @current_user
     set_time_zone
@@ -36,16 +39,12 @@
     deny_user(nil, login_path) unless logged_in?
   end
 
-  def require_token
-    deny_user("Invalid token", root_path) unless @user = User.user_from_token(params[:token])
-  end
-
-  def login(user)
+  def login(user, remember=false)
     reset_session
     @current_user = user
     current_user.track_sign_in(request.remote_ip) if allow_tracking?
-    current_user.set_token(:remember_token)
-    set_remember_cookie
+    current_user.set_remember_token if remember
+    set_remember_cookie if remember
     session[:user_id] = current_user.id
     session[:time_zone] = current_user.time_zone
     set_time_zone
@@ -63,6 +62,14 @@
     Time.zone = session[:time_zone] if session[:time_zone].present?
   end
 
+  def set_current_user_from_remember_token
+    token = cookies.signed[:remember]
+    return if token.blank?
+    @current_user = User.where(remember_token: token).first
+    @current_user = nil if @current_user && @current_user.remember_token_expired?
+    @current_user
+  end
+
   def set_remember_cookie
     cookies.permanent.signed[:remember] = {
       value: current_user.remember_token,

data/lib/generators/authkit/templates/app/controllers/email_confirmation_controller.rb

@@ -1,19 +1,21 @@
 class EmailConfirmationController < ApplicationController
+  before_filter :require_login
   before_filter :require_token
 
   respond_to :html
 
   def show
-    if @user.email_confirmed
-      login(@user)
+    if current_user.email_confirmed
+      # Do not automatically log in the user
       flash[:notice] = "Thanks for confirming your email address"
+
       respond_to do |format|
         format.json { head :no_content }
         format.html { redirect_to root_path }
       end
     else
       respond_to do |format|
-        format.json { render json: { status: 'error', errors: @user.errors }.to_json, status: 422 }
+        format.json { render json: { status: 'error', errors: current_user.errors }.to_json, status: 422 }
         format.html {
           flash[:error] = "Could not confirm email address because it is already in use"
           redirect_to root_path
@@ -21,5 +23,21 @@ class EmailConfirmationController < ApplicationController
       end
     end
   end
+
+  protected
+
+  # Confirmation tokens confirm an email address. It is conceivable
+  # that an attacker might choose an address out of their control and attempt to
+  # brute-force a confirmation. By default this gains the attacker nothing.
+  #
+  # It is possible to consider failed confirmation tokens failed attempts and
+  # lock the account.
+  def require_token
+    verifier = ActiveSupport::MessageVerifier.new(Rails.application.config.secret_key_base)
+    valid = params[:token].present?
+    valid = valid && verifier.send(:secure_compare, params[:token], current_user.confirmation_token)
+    valid = valid && !current_user.confirmation_token_expired?
+    deny_user("Invalid token", root_path) unless valid
+  end
 end
 

data/lib/generators/authkit/templates/app/controllers/password_change_controller.rb

@@ -1,4 +1,6 @@
 class PasswordChangeController < ApplicationController
+  before_filter :require_no_user
+  before_filter :require_email_user
   before_filter :require_token
 
   def show
@@ -9,21 +11,51 @@ class PasswordChangeController < ApplicationController
   end
 
   def create
-    if @user.change_password(params[:password], params[:password_confirmation])
-      login(@user)
-
+    if email_user.change_password(params[:password], params[:password_confirmation])
+      # Do not automatically log in the user
       respond_to do |format|
         format.json { head :no_content }
         format.html {
           flash.now[:notice] = "Password updated successfully"
-          redirect_to(root_path)
+          redirect_to(login_path)
         }
       end
     else
       respond_to do |format|
-        format.json { render json: { status: 'error', errors: @user.errors }.to_json, status: 422 }
+        format.json { render json: { status: 'error', errors: email_user.errors }.to_json, status: 422 }
         format.html { render :show }
       end
     end
   end
+
+  protected
+
+  # Any existing user should be logged out to prevent session leakage
+  def require_no_user
+    logout
+  end
+
+  # The token is paired with an email parameter so that the user can be
+  # found in the database. Once found the tokens can be securely compared
+  # to prevent timing attacks. The email address is chosen over the id
+  # because the reset was generated using the email address and thus is
+  # already known. Using the id would increase information leakage.
+  def require_email_user
+    deny_user("Invalid email address", root_path) if params[:email].blank? || email_user.blank?
+  end
+
+  def email_user
+    return @user if defined?(@user)
+    @user = User.where(email: params[:email]).first || raise(ActiveRecord::RecordNotFound)
+  end
+
+  # Reset password tokens expire after 1 day
+  def require_token
+    verifier = ActiveSupport::MessageVerifier.new(Rails.application.config.secret_key_base)
+    valid = params[:token].present?
+    valid = valid && verifier.send(:secure_compare, params[:token], email_user.reset_password_token)
+    valid = valid && !email_user.reset_password_token_expired?
+    deny_user("Invalid token", root_path) unless valid
+  end
+
 end

data/lib/generators/authkit/templates/app/controllers/sessions_controller.rb

@@ -4,8 +4,10 @@ class SessionsController < ApplicationController
   end
 
   def create
+    remember = params[:remember_me] == "1"
+
     if user && user.authenticate(params[:password])
-      login(user)
+      login(user, remember)
       respond_to do |format|
         format.json { head :no_content }
         format.html { redirect_back_or_default }