simple_token_authentication 1.0.0.beta.5

data/README.md

@@ -0,0 +1,134 @@
+Simple Token Authentication
+===========================
+
+[![Gem Version](https://badge.fury.io/rb/simple_token_authentication.png)](http://badge.fury.io/rb/simple_token_authentication)
+[![Build Status](https://secure.travis-ci.org/gonzalo-bulnes/simple_token_authentication?branch=master)](http://travis-ci.org/gonzalo-bulnes/simple_token_authentication)
+
+Token authentication support has been removed from [Devise][devise] for security reasons. In [this gist][original-gist], Devise's [José Valim][josevalim] explains how token authentication should be performed in order to remain safe.
+
+This gem packages the content of the gist.
+
+  [devise]: https://github.com/plataformatec/devise
+  [original-gist]: https://gist.github.com/josevalim/fb706b1e933ef01e4fb6
+
+
+> **DISCLAIMER**: I am not José Valim, nor has he been involved in the gem bundling process. Implementation errors, if any, are mine; and contributions are welcome. -- [GB][gonzalo-bulnes]
+
+  [josevalim]: https://github.com/josevalim
+  [gonzalo-bulnes]: https://github.com/gonzalo-bulnes
+
+Installation
+------------
+
+Install [Devise][devise] with any modules you want, then add the gem to your `Gemfile`:
+
+```ruby
+# Gemfile
+
+gem 'simple_token_authentication'
+```
+
+Define which controller will handle authentication (typ. `ApplicationController`):
+
+```ruby
+# app/controllers/application_controller.rb
+
+class ApplicationController < ActionController::Base
+  # ...
+  acts_as_token_authentication_handler
+
+  # ...
+end
+```
+
+Define which model or models will be token authenticatable (typ. `User`):
+
+```ruby
+# app/models/user.rb
+
+class User < ActiveRecord::Base
+  acts_as_token_authenticatable
+
+  # Note: you can include any module you want. If available,
+  # token authentication will be performed before any other
+  # Devise authentication method.
+  #
+  # Include default devise modules. Others available are:
+  # :confirmable, :lockable, :timeoutable and :omniauthable
+  devise :invitable, :database_authenticatable,
+         :recoverable, :rememberable, :trackable, :validatable,
+         :lockable
+
+  # ...
+end
+```
+
+If the model or models you chose have no `:authentication_token` attribute, add them one (with an index):
+
+```bash
+rails g migration add_authentication_token_to_users authentication_token:string:index
+rake db:migrate
+```
+
+Usage
+-----
+
+### Tokens Generation
+
+Assuming `user` is an instance of `User`, which is _token authenticatable_: each time `user` will be saved, and `user.authentication_token.is_blank?` it receives a new and unique authentication token (via `Devise.friendly_token`).
+
+### Authentication Method 1: Query Params
+
+You can authenticate passing the `user_email` and `user_token` params as query params:
+
+```
+GET https://secure.example.com?user_email=alice@example.com&user_token=1G8_s7P-V-4MGojaKD7a
+```
+
+The _token authentication handler_ (e.g. `ApplicationController`) will perform the user sign in if both are correct.
+
+### Authentication Method 2: Request Headers
+
+You can also use request headers (which may be simpler when authenticating against an API):
+
+```
+X-User-Email alice@example.com
+X-User-Token 1G8_s7P-V-4MGojaKD7a
+```
+
+In fact, you can mix both methods and provide the `user_email` with one and the `user_token` with the other, even if it would be a freak thing to do.
+
+### Integration with other authentication methods
+
+If sign-in is successful, no other authentication method will be run, but if it doesn't (the authentication params were missing, or incorrect) then Devise takes control and tries to `authenticate_user!` with its own modules.
+
+Credits
+-------
+
+It may sound a bit redundant, but this gem wouldn't exist without [this gist][original-gist].
+
+Help Wanted
+-----------
+
+Hi, thanks for having kept reading! You can probably help me to bump this gem version to `1.0.0`: I want it to be tested before removing the `beta` flag. If you can provide some help, please make yourself at home at the [issue #1][1].
+
+  [1]: https://github.com/gonzalo-bulnes/simple_token_authentication/issues/1
+
+License
+-------
+
+    Simple Token Authentication
+    Copyright (C) 2013 Gonzalo Bulnes Guilpain
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with this program.  If not, see <http://www.gnu.org/licenses/>.

data/Rakefile

@@ -0,0 +1,32 @@
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rdoc/task'
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'SimpleTokenAuthentication'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+
+
+
+Bundler::GemHelper.install_tasks
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+
+task default: :test

data/lib/simple_token_authentication.rb

@@ -0,0 +1,5 @@
+require 'simple_token_authentication/acts_as_token_authenticatable'
+require 'simple_token_authentication/acts_as_token_authentication_handler'
+
+module SimpleTokenAuthentication
+end

data/lib/simple_token_authentication/acts_as_token_authenticatable.rb

@@ -0,0 +1,33 @@
+module SimpleTokenAuthentication
+  module ActsAsTokenAuthenticatable
+    extend ActiveSupport::Concern
+
+    # Please see https://gist.github.com/josevalim/fb706b1e933ef01e4fb6
+    # before editing this file, the discussion is very interesting.
+
+    included do
+      private :generate_authentication_token
+    end
+
+    def ensure_authentication_token
+      if authentication_token.blank?
+        self.authentication_token = generate_authentication_token
+      end
+    end
+
+    def generate_authentication_token
+      loop do
+        token = Devise.friendly_token
+        break token unless User.where(authentication_token: token).first
+      end
+    end
+
+    module ClassMethods
+      def acts_as_token_authenticatable(options = {})
+        include SimpleTokenAuthentication::ActsAsTokenAuthenticatable
+        before_save :ensure_authentication_token
+      end
+    end
+  end
+end
+ActiveRecord::Base.send :include, SimpleTokenAuthentication::ActsAsTokenAuthenticatable

data/lib/simple_token_authentication/acts_as_token_authentication_handler.rb

@@ -0,0 +1,68 @@
+module SimpleTokenAuthentication
+  module ActsAsTokenAuthenticationHandlerMethods
+    extend ActiveSupport::Concern
+
+    # Please see https://gist.github.com/josevalim/fb706b1e933ef01e4fb6
+    # before editing this file, the discussion is very interesting.
+
+    included do
+      private :authenticate_user_from_token!
+      # This is our new function that comes before Devise's one
+      before_filter :authenticate_user_from_token!
+      # This is Devise's authentication
+      before_filter :authenticate_user!
+    end
+
+    # For this example, we are simply using token authentication
+    # via parameters. However, anyone could use Rails's token
+    # authentication features to get the token from a header.
+    def authenticate_user_from_token!
+      # Set the authentication token params if not already present,
+      # see http://stackoverflow.com/questions/11017348/rails-api-authentication-by-headers-token
+      if user_token = params[:user_token].blank? && request.headers["X-User-Token"]
+        params[:user_token] = user_token
+      end
+      if user_email = params[:user_email].blank? && request.headers["X-User-Email"]
+        params[:user_email] = user_email
+      end
+
+      user_email = params[:user_email].presence
+      # See https://github.com/ryanb/cancan/blob/1.6.10/lib/cancan/controller_resource.rb#L108-L111
+      if User.respond_to? "find_by"
+        user = user_email && User.find_by(email: user_email)
+      elsif User.respond_to? "find_by_email"
+        user = user_email && User.find_by_email(user_email)
+      end
+
+      # Notice how we use Devise.secure_compare to compare the token
+      # in the database with the token given in the params, mitigating
+      # timing attacks.
+      if user && Devise.secure_compare(user.authentication_token, params[:user_token])
+        # Notice we are passing store false, so the user is not
+        # actually stored in the session and a token is needed
+        # for every request. If you want the token to work as a
+        # sign in token, you can simply remove store: false.
+        sign_in user, store: false
+      end
+    end
+  end
+
+  module ActsAsTokenAuthenticationHandler
+    extend ActiveSupport::Concern
+
+    # I have insulated the methods into an additional module to avoid before_filters
+    # to be applied by the `included` block before acts_as_token_authentication_handler was called.
+    # See https://github.com/gonzalo-bulnes/simple_token_authentication/issues/8#issuecomment-31707201
+
+    included do
+      # nop
+    end
+
+    module ClassMethods
+      def acts_as_token_authentication_handler(options = {})
+        include SimpleTokenAuthentication::ActsAsTokenAuthenticationHandlerMethods
+      end
+    end
+  end
+end
+ActionController::Base.send :include, SimpleTokenAuthentication::ActsAsTokenAuthenticationHandler

data/lib/simple_token_authentication/version.rb

@@ -0,0 +1,3 @@
+module SimpleTokenAuthentication
+  VERSION = "1.0.0.beta.5"
+end

data/lib/tasks/simple_token_authentication_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :simple_token_authentication do
+#   # Task goes here
+# end

data/test/dummy/README.rdoc

@@ -0,0 +1,28 @@
+== README
+
+This README would normally document whatever steps are necessary to get the
+application up and running.
+
+Things you may want to cover:
+
+* Ruby version
+
+* System dependencies
+
+* Configuration
+
+* Database creation
+
+* Database initialization
+
+* How to run the test suite
+
+* Services (job queues, cache servers, search engines, etc.)
+
+* Deployment instructions
+
+* ...
+
+
+Please feel free to use a different markup language if you do not plan to run
+<tt>rake doc:app</tt>.

data/test/dummy/Rakefile

@@ -0,0 +1,6 @@
+# Add your own tasks in files placed in lib/tasks ending in .rake,
+# for example lib/tasks/capistrano.rake, and they will automatically be available to Rake.
+
+require File.expand_path('../config/application', __FILE__)
+
+Dummy::Application.load_tasks

data/test/dummy/app/assets/javascripts/application.js

@@ -0,0 +1,13 @@
+// This is a manifest file that'll be compiled into application.js, which will include all the files
+// listed below.
+//
+// Any JavaScript/Coffee file within this directory, lib/assets/javascripts, vendor/assets/javascripts,
+// or vendor/assets/javascripts of plugins, if any, can be referenced here using a relative path.
+//
+// It's not advisable to add code directly here, but if you do, it'll appear at the bottom of the
+// compiled file.
+//
+// Read Sprockets README (https://github.com/sstephenson/sprockets#sprockets-directives) for details
+// about supported directives.
+//
+//= require_tree .

data/test/dummy/app/assets/javascripts/posts.js

@@ -0,0 +1,2 @@
+// Place all the behaviors and hooks related to the matching controller here.
+// All this logic will automatically be available in application.js.

data/test/dummy/app/assets/javascripts/private_posts.js

@@ -0,0 +1,2 @@
+// Place all the behaviors and hooks related to the matching controller here.
+// All this logic will automatically be available in application.js.

data/test/dummy/app/assets/stylesheets/application.css

@@ -0,0 +1,13 @@
+/*
+ * This is a manifest file that'll be compiled into application.css, which will include all the files
+ * listed below.
+ *
+ * Any CSS and SCSS file within this directory, lib/assets/stylesheets, vendor/assets/stylesheets,
+ * or vendor/assets/stylesheets of plugins, if any, can be referenced here using a relative path.
+ *
+ * You're free to add application-wide styles to this file and they'll appear at the top of the
+ * compiled file, but it's generally better to create a new file per style scope.
+ *
+ *= require_self
+ *= require_tree .
+ */

data/test/dummy/app/assets/stylesheets/posts.css

@@ -0,0 +1,4 @@
+/*
+  Place all the styles related to the matching controller here.
+  They will automatically be included in application.css.
+*/

data/test/dummy/app/assets/stylesheets/private_posts.css

@@ -0,0 +1,4 @@
+/*
+  Place all the styles related to the matching controller here.
+  They will automatically be included in application.css.
+*/

data/test/dummy/app/assets/stylesheets/scaffold.css

@@ -0,0 +1,56 @@
+body { background-color: #fff; color: #333; }
+
+body, p, ol, ul, td {
+  font-family: verdana, arial, helvetica, sans-serif;
+  font-size:   13px;
+  line-height: 18px;
+}
+
+pre {
+  background-color: #eee;
+  padding: 10px;
+  font-size: 11px;
+}
+
+a { color: #000; }
+a:visited { color: #666; }
+a:hover { color: #fff; background-color:#000; }
+
+div.field, div.actions {
+  margin-bottom: 10px;
+}
+
+#notice {
+  color: green;
+}
+
+.field_with_errors {
+  padding: 2px;
+  background-color: red;
+  display: table;
+}
+
+#error_explanation {
+  width: 450px;
+  border: 2px solid red;
+  padding: 7px;
+  padding-bottom: 0;
+  margin-bottom: 20px;
+  background-color: #f0f0f0;
+}
+
+#error_explanation h2 {
+  text-align: left;
+  font-weight: bold;
+  padding: 5px 5px 5px 15px;
+  font-size: 12px;
+  margin: -7px;
+  margin-bottom: 0px;
+  background-color: #c00;
+  color: #fff;
+}
+
+#error_explanation ul li {
+  font-size: 12px;
+  list-style: square;
+}

data/test/dummy/app/controllers/application_controller.rb

@@ -0,0 +1,21 @@
+class ApplicationController < ActionController::Base
+  # Prevent CSRF attacks by raising an exception.
+  # For APIs, you may want to use :null_session instead.
+  protect_from_forgery with: :exception
+
+  # While `acts_as_token_authentication_handler` was not called,
+  # neither should be `authenticate_user!`.
+  # See https://github.com/gonzalo-bulnes/simple_token_authentication/issues/8
+  #
+  # Yet once `acts_as_token_authentication_handler` was called, `authenticate_user!`
+  # should also be called. Run `rspec` to ensure that's being true.
+  # If called, the `authenticate_user!` method will raise an exception, that
+  # allows both cases to be covered by their own spec example.
+  #
+  # See test/dummy/app/controllers/posts_controller.rb and
+  # test/dummy/app/controllers/private_posts_controller.rb
+
+  def authenticate_user!
+    raise "`authenticate_user!` was called."
+  end
+end