stn-simple_token_authentication 1.7.1

data/README.md

@@ -0,0 +1,270 @@
+Simple Token Authentication
+===========================
+
+[![Gem Version](https://badge.fury.io/rb/simple_token_authentication.svg)](http://badge.fury.io/rb/simple_token_authentication)
+[![Build Status](https://travis-ci.org/gonzalo-bulnes/simple_token_authentication.svg?branch=master)](https://travis-ci.org/gonzalo-bulnes/simple_token_authentication)
+[![Code Climate](https://codeclimate.com/github/gonzalo-bulnes/simple_token_authentication.svg)](https://codeclimate.com/github/gonzalo-bulnes/simple_token_authentication)
+[![Dependency Status](https://gemnasium.com/gonzalo-bulnes/simple_token_authentication.svg)](https://gemnasium.com/gonzalo-bulnes/simple_token_authentication)
+[![security](https://hakiri.io/github/gonzalo-bulnes/simple_token_authentication/master.svg)](https://hakiri.io/github/gonzalo-bulnes/simple_token_authentication/master)
+[![Inline docs](http://inch-ci.org/github/gonzalo-bulnes/simple_token_authentication.svg?branch=master)](http://inch-ci.org/github/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', '~> 1.0' # see semver.org
+```
+
+### Make models token authenticatable
+
+#### ActiveRecord
+
+First 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
+```
+
+#### Mongoid
+
+Define which model or models will be token authenticatable (typ. `User`):
+
+```ruby
+# app/models/user.rb
+
+class User
+  include Mongoid::Document
+  # Include default devise modules. Others available are:
+  # :confirmable, :lockable, :timeoutable and :omniauthable
+  devise :database_authenticatable, :registerable,
+         :recoverable, :rememberable, :trackable, :validatable
+
+  ## Token Authenticatable
+  acts_as_token_authenticatable
+  field :authentication_token
+
+  # ...
+end
+```
+
+### Allow controllers to handle token authentication
+
+Finally define which controllers will handle token authentication (typ. `ApplicationController`) for which _token authenticatable_ models:
+
+```ruby
+# app/controllers/application_controller.rb
+
+class ApplicationController < ActionController::Base # or ActionController::API
+  # ...
+
+  acts_as_token_authentication_handler_for User
+
+  # Security note: controllers with no-CSRF protection must disable the Devise fallback,
+  # see #49 for details.
+  # acts_as_token_authentication_handler_for User, fallback_to_devise: false
+
+  # The token authentication requirement can target specific controller actions:
+  # acts_as_token_authentication_handler_for User, only: [:create, :update, :destroy]
+  # acts_as_token_authentication_handler_for User, except: [:index, :show]
+
+  # Several token authenticatable models can be handled by the same controller.
+  # If so, for all of them except the last, the fallback_to_devise should be disabled.
+  #
+  # Please do notice that the order of declaration defines the order of precedence.
+  #
+  # acts_as_token_authentication_handler_for Admin, fallback_to_devise: false
+  # acts_as_token_authentication_handler_for SpecialUser, fallback_to_devise: false
+  # acts_as_token_authentication_handler_for User # the last fallback is up to you
+
+  # ...
+end
+```
+
+Configuration
+-------------
+
+Some aspects of the behavior of _Simple Token Authentication_ can be customized with an initializer.
+Below is an example with reasonable defaults:
+
+```ruby
+# config/initializers/simple_token_authentication.rb
+
+SimpleTokenAuthentication.configure do |config|
+
+  # Configure the session persistence policy after a successful sign in,
+  # in other words, if the authentication token acts as a signin token.
+  # If true, user is stored in the session and the authentication token and
+  # email may be provided only once.
+  # If false, users must provide their authentication token and email at every request.
+  # config.sign_in_token = false
+
+  # Configure the name of the HTTP headers watched for authentication.
+  #
+  # Default header names for a given token authenticatable entity follow the pattern:
+  #   { entity: { authentication_token: 'X-Entity-Token', email: 'X-Entity-Email'} }
+  #
+  # When several token authenticatable models are defined, custom header names
+  # can be specified for none, any, or all of them.
+  #
+  # Examples
+  #
+  #   Given User and SuperAdmin are token authenticatable,
+  #   When the following configuration is used:
+  #     `config.header_names = { super_admin: { authentication_token: 'X-Admin-Auth-Token' } }`
+  #   Then the token authentification handler for User watches the following headers:
+  #     `X-User-Token, X-User-Email`
+  #   And the token authentification handler for SuperAdmin watches the following headers:
+  #     `X-Admin-Auth-Token, X-SuperAdmin-Email`
+  #
+  # config.header_names = { user: { authentication_token: 'X-User-Token', email: 'X-User-Email' } }
+
+end
+```
+
+Usage
+-----
+
+### Tokens Generation
+
+Assuming `user` is an instance of `User`, which is _token authenticatable_: each time `user` will be saved, and `user.authentication_token.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. That behaviour can however be modified for any controller through the **fallback_to_devise** option.
+
+**Important**: Please do notice that controller actions whithout CSRF protection **must** disable the Devise fallback for [security reasons][csrf]. Since Rails enables CSRF protection by default, this configuration requirement should only affect controllers where you have disabled it, which may be the case of API controllers.
+
+  [csrf]: https://github.com/gonzalo-bulnes/simple_token_authentication/issues/49
+
+Documentation
+-------------
+
+### Frequently Asked Questions
+
+Any question? Please don't hesitate to open a new issue to get help. I keep questions tagged to make possible to [review the open questions][open-questions], while closed questions are organized as a sort of [FAQ][faq].
+
+  [open-questions]: https://github.com/gonzalo-bulnes/simple_token_authentication/issues?labels=question&page=1&state=open
+  [faq]: https://github.com/gonzalo-bulnes/simple_token_authentication/issues?direction=desc&labels=question&page=1&sort=comments&state=closed
+
+### Changelog
+
+Releases are commented to provide a brief [changelog][changelog].
+
+  [changelog]: https://github.com/gonzalo-bulnes/simple_token_authentication/releases
+
+Development
+-----------
+
+### Testing and documentation
+
+This gem development has been test-driven since `v1.0.0`. Until `v1.5.1`, the gem behaviour was described using [Cucumber][cucumber] and [RSpec][rspec] in a dummy app generated by [Aruba][aruba]. Since `v1.5.2` it is described using Rspec alone.
+
+RSpec [tags][tags] are used to categorize the spec examples.
+
+Spec examples that are tagged as `public` describe aspects of the gem public API, and MAY be considered as the gem documentation.
+
+The `private` or `protected` specs are written for development purpose only. Because they describe internal behaviour which may change at any moment without notice, they are only executed as a secondary task by the [continuous integration service][travis] and SHOULD be ignored.
+
+Run `rake spec:public` to print the gem public documentation.
+
+  [aruba]: https://github.com/cucumber/aruba
+  [cucumber]: https://github.com/cucumber/cucumber-rails
+  [rspec]: https://www.relishapp.com/rspec/rspec-rails/docs
+  [tags]: https://www.relishapp.com/rspec/rspec-core/v/3-1/docs/command-line/tag-option
+  [travis]: https://travis-ci.org/gonzalo-bulnes/simple_token_authentication/builds
+
+### Contributions
+
+Contributions are welcome! I'm not personally maintaining any [list of contributors][contributors] for now, but any PR which references us all will be welcome.
+
+  [contributors]: https://github.com/gonzalo-bulnes/simple_token_authentication/graphs/contributors
+
+Please be sure to [review the open issues][open-questions] and contribute with your ideas or code in the issue best suited to the topic. Keeping discussions in a single place makes easier to everyone interested in that topic to keep track of the contributions.
+
+Credits
+-------
+
+It may sound a bit redundant, but this gem wouldn't exist without [this gist][original-gist], nor without the [comments][issues] and [contributions][pulls] of many people. Thank them if you see them!
+
+  [issues]: https://github.com/gonzalo-bulnes/simple_token_authentication/issues
+  [pulls]: https://github.com/gonzalo-bulnes/simple_token_authentication/pulls
+
+License
+-------
+
+    Simple Token Authentication
+    Copyright (C) 2013, 2014 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,61 @@
+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
+
+
+begin
+  require 'inch/rake'
+
+  Inch::Rake::Suggest.new(:inch) do |suggest|
+    suggest.args << "--private"
+    suggest.args << "--pedantic"
+  end
+rescue LoadError
+  desc 'Inch rake task not available'
+  task :inch do
+  abort 'Inch rake task is not available. Be sure to install inch as a gem or plugin'
+  end
+end
+
+begin
+  require 'rspec/core/rake_task'
+
+  desc 'Provide private interfaces documentation'
+  RSpec::Core::RakeTask.new(:spec)
+
+  namespace :spec do
+    desc 'Provide public interfaces documentation'
+    RSpec::Core::RakeTask.new(:public) do |t|
+      t.rspec_opts = "--tag public"
+    end
+  end
+
+  namespace :spec do
+    desc 'Provide private interfaces documentation for development purpose'
+    RSpec::Core::RakeTask.new(:development) do |t|
+      t.rspec_opts = "--tag protected --tag private"
+    end
+  end
+rescue LoadError
+  desc 'RSpec rake task not available'
+  task :spec do
+  abort 'RSpec rake task is not available. Be sure to install rspec-core as a gem or plugin'
+  end
+end
+
+task default: ['spec:public', 'spec:development', :inch]

data/doc/README.md

@@ -0,0 +1,18 @@
+Documentation
+=============
+
+**Looking for the HTML features decription?**
+
+The Cucumber features that documented the gem behaviour until `v1.5.1` constituted a robust tests suite, but they were slow and writting them was difficult enough to become a continuous bottleneck.
+
+I decided to tackle the issue by replacing most scenarios by unit tests (see [#104][issue]), and since `v1.5.2` the gem behaviour is documented using RSpec only.
+
+I liked the [executable documentation][exec-doc] idea, and I do not discard using Cucumber again to test _Simple Token Authentication_.
+However, truth is that neither the somewhat intricated [Cucumber][cucumber] - [Aruba][aruba] - [RSpec][rspec] setup or the steps I wrote were exemplary enough to make justice to the great tool Cucumber is. So I decided to stop maintaining  the features and to remove them. The RSpec test suite provides a nice [documentation][doc], and sometimes the best is a fresh start.
+
+  [exec-doc]: https://github.com/gonzalo-bulnes/simple_token_authentication/tree/v1.5.1#executable-documentation
+  [doc]: #testing-and-documentation
+  [issue]: https://github.com/gonzalo-bulnes/simple_token_authentication/issues/104
+  [aruba]: https://github.com/cucumber/aruba
+  [cucumber]: https://github.com/cucumber/cucumber-rails
+  [rspec]: https://www.relishapp.com/rspec/rspec-rails/docs

data/lib/simple_token_authentication.rb

@@ -0,0 +1,58 @@
+require 'simple_token_authentication/acts_as_token_authenticatable'
+require 'simple_token_authentication/acts_as_token_authentication_handler'
+require 'simple_token_authentication/configuration'
+
+module SimpleTokenAuthentication
+  extend Configuration
+
+  NoAdapterAvailableError = Class.new(LoadError)
+
+  private
+
+  def self.ensure_models_can_act_as_token_authenticatables model_adapters
+    model_adapters.each do |model_adapter|
+      model_adapter.base_class.send :include, SimpleTokenAuthentication::ActsAsTokenAuthenticatable
+    end
+  end
+
+  def self.ensure_controllers_can_act_as_token_authentication_handlers controller_adapters
+    controller_adapters.each do |controller_adapter|
+      controller_adapter.base_class.send :extend, SimpleTokenAuthentication::ActsAsTokenAuthenticationHandler
+    end
+  end
+
+  # Private: Load the available adapters.
+  #
+  # adapters_short_names - Array of names of the adapters to load if available
+  #
+  # Example
+  #
+  #    load_available_adapters ['unavailable_adapter', 'available_adapter']
+  #    # => [SimpleTokenAuthentication::Adapters::AvailableAdapter]
+  #
+  # Returns an Array of available adapters
+  def self.load_available_adapters adapters_short_names
+    available_adapters = adapters_short_names.collect do |short_name|
+      adapter_name = "simple_token_authentication/adapters/#{short_name}_adapter"
+      if adapter_dependency_fulfilled?(short_name) && require(adapter_name)
+        adapter_name.camelize.constantize
+      end
+    end
+    available_adapters.compact!
+
+    # stop here if dependencies are missing or no adequate adapters are present
+    raise SimpleTokenAuthentication::NoAdapterAvailableError if available_adapters.empty?
+
+    available_adapters
+  end
+
+  def self.adapter_dependency_fulfilled? adapter_short_name
+    Object.qualified_const_defined?(SimpleTokenAuthentication.adapters_dependencies[adapter_short_name])
+  end
+
+  available_model_adapters = load_available_adapters SimpleTokenAuthentication.model_adapters
+  ensure_models_can_act_as_token_authenticatables available_model_adapters
+
+  available_controller_adapters = load_available_adapters SimpleTokenAuthentication.controller_adapters
+  ensure_controllers_can_act_as_token_authentication_handlers available_controller_adapters
+end

data/lib/simple_token_authentication/acts_as_token_authenticatable.rb

@@ -0,0 +1,49 @@
+require 'active_support/concern'
+require 'simple_token_authentication/token_generator'
+
+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
+      private :token_suitable?
+      private :token_generator
+    end
+
+    # Set an authentication token if missing
+    #
+    # Because it is intended to be used as a filter,
+    # this method is -and should be kept- idempotent.
+    def ensure_authentication_token
+      if authentication_token.blank?
+        self.authentication_token = generate_authentication_token(token_generator)
+      end
+    end
+
+    def generate_authentication_token(token_generator)
+      loop do
+        token = token_generator.generate_token
+        break token if token_suitable?(token)
+      end
+    end
+
+    def token_suitable?(token)
+      self.class.where(authentication_token: token).count == 0
+    end
+
+    # Private: Get one (always the same) object which behaves as a token generator
+    def token_generator
+      @token_generator ||= TokenGenerator.new
+    end
+
+    module ClassMethods
+      def acts_as_token_authenticatable(options = {})
+        before_save :ensure_authentication_token
+      end
+    end
+  end
+end