devise_token_auth 0.1.16 → 0.1.17

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7d5d45596f8f30bd6b931a282f8f204892ea575a
-  data.tar.gz: 7666d30af08d983a82461a6a98d6af6b5cb26c71
+  metadata.gz: d6fddec01685e543399f2fa156c7c5b3a1a00cc8
+  data.tar.gz: d51505ea9e19cac45f566c8a0159202363d34062
 SHA512:
-  metadata.gz: 9b75f68a2fb8ec69db145524b383938458640daf1e4beea25ee24c04d9a028e848c5eadc227cc47e70a4c501c0d6c6924848c7c464529aa9d20af09fc49157a3
-  data.tar.gz: 386781828692d7ccbb847b43915622c9c2406ac496c157b2364f98ef479121eacade9841ae6b5a4ecc415c76636c8ccb30e467951add3ae2d2d4831a3b22180e
+  metadata.gz: bf7d4346373fab8211fb5b09aaf7671178d17630a2ee7a496baa5fd528d0f10977acc64e1e28baa42103a371c3044f13ec606bec96caec69dc98824c22143818
+  data.tar.gz: 1812e0973a0bff3a54567b38cc862669b6cc7990383b9b48245ff6c38c0f2198934b4925e5305a88c3fa91adee221137f88af529fb7e1d26d5105e0bd9b713e9

data/README.md

@@ -31,19 +31,25 @@ Then install the gem using bundle:
 bundle install
 ~~~
 
-## Migrations
-You will need to create a user model. Run the following to generate and run the `User` model migration:
+## Configuration
+You will need to create a user model, and you may want to alter some of the default settings. Run the following to generate the migrations and initializer files:
 
 ~~~bash
-rake devise_token_auth:install:migrations
+rails g devise_token_auth:install
 ~~~
 
-Then run the migration:
+This will create a migrations file in the `db/migrate` directory. Inspect the migrations file and add additional columns if necessary, then run the migration:
 
 ~~~bash
 rake db:migrate
 ~~~
 
+An initializer will also be created at `config/initializers/devise_token_auth.rb`. The following settings are available for configuration:
+
+* **`change_headers_on_each_request`** _Default: true_. By default the authorization headers will change after each request. The client is responsible for keeping track of the changing tokens. The [ng-token-auth](https://github.com/lynndylanhurley/ng-token-auth) module for angular.js does this out of the box. While this implementation is more secure, it can be difficult to manage. Set this to false to prevent the `Authorization` header from changing after each request.
+*  **`token_lifespan`** _Default: 2.weeks_. Set the length of your tokens' lifespans. Users will need to re-authenticate after this duration of time has passed since their last login.
+*  **`batch_request_buffer_throttle`** _Default: 2.seconds_. Sometimes it's necessary to make several requests to the API at the same time. In this case, each request in the batch will need to share the same auth token. This setting determines how far apart the requests can be while still using the same auth token.
+
 ## Omniauth authentication
 
 If you wish to use omniauth authentication, add all of your desired authentication provider gems as well.
@@ -165,19 +171,34 @@ The following routes are available for use by your client. These routes live rel
 
 If you're using [ng-token-auth](https://github.com/lynndylanhurley/ng-token-auth) for angular.js, then your client is ready to go.
 
+
 ## Identifying users in controllers
 
 The authentication information should be included by the client in the `Authorization` header of each request. The header should follow this format:
 
+##### Authorization header example:
 ~~~
-token=xxxxx client=yyyyy uid=zzzzz
+token=wwwww client=xxxxx expiry=yyyyy uid=zzzzz
 ~~~
 
-Replace `xxxxx` with the user's `auth_token` and `zzzzz` with the user's `uid`. The `client` field exists to allow for multiple simultaneous sessions per user. The client field defaults to `default` if omitted.
+The `Authorization` header is made up of the following components:
+
+* **`token`**: This serves as the user's password for each request. A hashed version of this value is stored in the database for later comparison. This value should be changed on each request.
+* **`client`**: This enables the use of multiple simultaneous sessions on different clients. (For example, a user may want to be authenticated on both their phone and their laptop at the same time.)
+* **`expiry`**: The date at which the current session will expire. This can be used by clients to invalidate expired tokens without the need for an API request.
+* **`uid`**: A unique value that is used to identify the user. This is necessary because searching the DB for users by their access token will open the API up to timing attacks.
+
+The `Authorization` header required for each request will be available in the response from the previous request. If you are using the [ng-token-auth](https://github.com/lynndylanhurley/ng-token-auth) module for angular.js, this functionality is already provided.
+
+
+## The `User` model
 
-This all happens effortlessly and invisibly when using [ng-token-auth](https://github.com/lynndylanhurley/ng-token-auth).
+The user model will contain the following public methods (read the above section for context on `token` and `client`):
+* **`valid_token?`**: check if an authentication token is valid. Accepts `token` and `client` as arguments. Returns a boolean.
+* **`create_new_auth_token`**: creates a new auth token with all of the necessary metadata. Accepts `client` as an optional argument. Will generate a new `client` if none is provided. Returns the `Authorization` header that should be sent by the client as a string.
+* **`build_auth_header`**: generates the auth header that should be sent to the client with the next request. Accepts `token` and `client` as arguments. Returns a string.
 
-### DeviseTokenAuth::Concerns::SetUserByToken
+## DeviseTokenAuth::Concerns::SetUserByToken
 
 This gem includes a [Rails concern](http://api.rubyonrails.org/classes/ActiveSupport/Concern.html) that can be used to identify users by the `Authorization` header.
 

data/app/controllers/devise_token_auth/auth_controller.rb

@@ -45,7 +45,7 @@ module DeviseTokenAuth
 
       @user.tokens[@client_id] = {
         token: BCrypt::Password.create(@token),
-        expiry: Time.now + 2.weeks
+        expiry: Time.now + DeviseTokenAuth.token_lifespan
       }
 
       # sync user info with provider, update/generate auth token

data/app/controllers/devise_token_auth/concerns/set_user_by_token.rb

@@ -6,6 +6,7 @@ module DeviseTokenAuth::Concerns::SetUserByToken
     after_action :update_auth_header
   end
 
+
   # user auth
   def set_user_by_token
     auth_header = request.headers["Authorization"]
@@ -13,35 +14,56 @@ module DeviseTokenAuth::Concerns::SetUserByToken
     # missing auth token
     return false unless auth_header
 
-    token      = auth_header[/token=(.*?) /,1]
+    # parse header for values necessary for authentication
     uid        = auth_header[/uid=(.*?)$/,1]
+    @token     = auth_header[/token=(.*?) /,1]
     @client_id = auth_header[/client=(.*?) /,1]
 
+    # client_id isn't required, set to 'default' if absent
     @client_id ||= 'default'
 
     # mitigate timing attacks by finding by uid instead of auth token
     @user = @current_user = uid && User.find_by_uid(uid)
 
-    if @user && @user.valid_token?(@client_id, token)
+    if @user && @user.valid_token?(@token, @client_id)
       sign_in(:user, @user, store: false, bypass: true)
+
+      # check this now so that the duration of the request itself doesn't eat
+      # away the buffer
+      @is_batch_request = is_batch_request?(@user, @client_id)
+
     else
-      @user = @current_user = nil
+      # zero all values previously set values
+      @user = @current_user = @is_batch_request = nil
     end
   end
 
+
   def update_auth_header
-    if @user
-      # update user's auth token (should happen on each request)
-      token                    = SecureRandom.urlsafe_base64(nil, false)
-      token_hash               = BCrypt::Password.create(token)
-      @user.tokens[@client_id] = {
-        token:  token_hash,
-        expiry: Time.now + 2.weeks
-      }
-      @user.save
-
-      # update Authorization response header with new token
-      response.headers["Authorization"] = "token=#{token} client=#{@client_id} uid=#{@user.uid}"
+
+    auth_header = nil
+    if not DeviseTokenAuth.change_headers_on_each_request
+      auth_header = @user.build_auth_header(@token, @client_id)
+
+    # extend expiration of batch buffer to account for the duration of
+    # this request
+    elsif @is_batch_request and @client_id and @user
+      auth_header = @user.extend_batch_buffer(@token, @client_id)
+
+    # update Authorization response header with new token
+    elsif @user and @client_id
+      auth_header = @user.create_new_auth_token(@client_id)
     end
+
+    response.headers["Authorization"] = auth_header if auth_header
+  end
+
+
+  private
+
+  def is_batch_request?(user, client_id)
+    user.tokens[client_id] and
+    user.tokens[client_id]['updated_at'] and
+    user.tokens[client_id]['updated_at'] > Time.now - DeviseTokenAuth.batch_request_buffer_throttle
   end
 end

data/app/controllers/devise_token_auth/confirmations_controller.rb

@@ -12,7 +12,7 @@ module DeviseTokenAuth
         token_hash = BCrypt::Password.create(token)
         @user.tokens[client_id] = {
           token:  token_hash,
-          expiry: Time.now + 2.weeks
+          expiry: Time.now + DeviseTokenAuth.token_lifespan
         }
 
         @user.save!

data/app/controllers/devise_token_auth/registrations_controller.rb

@@ -22,7 +22,7 @@ module DeviseTokenAuth
           render json: {
             status: 'error',
             data:   @resource,
-            errors: ["An account already exists for #{@resource.email}"]
+            errors: @resource.errors
           }, status: 403
         end
       rescue ActiveRecord::RecordNotUnique

data/app/controllers/devise_token_auth/sessions_controller.rb

@@ -17,7 +17,7 @@ module DeviseTokenAuth
 
         @user.tokens[@client_id] = {
           token: BCrypt::Password.create(@token),
-          expiry: Time.now + 2.weeks
+          expiry: Time.now + DeviseTokenAuth.token_lifespan
         }
         @user.save
 

data/app/models/user.rb

@@ -7,36 +7,110 @@ class User < ActiveRecord::Base
 
   serialize :tokens, JSON
 
-  # only validate unique emails among email registration users
   validates_presence_of :email, if: Proc.new { |u| u.provider == 'email' }
   validates_presence_of :confirm_success_url, if: Proc.new {|u| u.provider == 'email'}
 
+  # only validate unique emails among email registration users
   validate :unique_email_user, on: :create
 
-  def valid_token?(client_id, token)
-    return false unless self.tokens[client_id]['expiry'] > 2.weeks.ago
-    return false unless BCrypt::Password.new(self.tokens[client_id]['token']) == token
+  def valid_token?(token, client_id='default')
+    client_id ||= 'default'
+
+    return true if (
+      # ensure that expiry and token are set
+      self.tokens[client_id]['expiry'] and
+      self.tokens[client_id]['token'] and
+
+      # ensure that the token was created within the last two weeks
+      self.tokens[client_id]['expiry'] > DeviseTokenAuth.token_lifespan.ago.to_f * 1000 and
+
+      # ensure that the token is valid
+      BCrypt::Password.new(self.tokens[client_id]['token']) == token
+    )
+
+    return true if (
+      # ensure that the last token and its creation time exist
+      self.tokens[client_id]['updated_at'] and
+      self.tokens[client_id]['last_token'] and
+
+      # ensure that previous token falls within the batch buffer throttle time of the last request
+      Time.parse(self.tokens[client_id]['updated_at']) > Time.now - DeviseTokenAuth.batch_request_buffer_throttle and
+
+      # ensure that the token is valid
+      BCrypt::Password.new(self.tokens[client_id]['last_token']) == token
+    )
+
+    # return false if none of the above conditions are met
+    return false
+  end
+
+
+  # update user's auth token (should happen on each request)
+  def create_new_auth_token(client_id=nil)
+    client_id  ||= SecureRandom.urlsafe_base64(nil, false)
+    last_token ||= nil
+    token        = SecureRandom.urlsafe_base64(nil, false)
+    token_hash   = BCrypt::Password.create(token)
+    expiry       = (Time.now.to_f + DeviseTokenAuth.token_lifespan).to_i * 1000
+
+    if self.tokens[client_id] and self.tokens[client_id]['token']
+      last_token = self.tokens[client_id]['token']
+    end
+
+    self.tokens[client_id] = {
+      token:      token_hash,
+      expiry:     expiry,
+      last_token: last_token,
+      updated_at: Time.now
+   }
+
+    self.save!
 
-    return true
+    return build_auth_header(token, client_id)
   end
 
+
+  def build_auth_header(token, client_id='default')
+    client_id ||= 'default'
+
+    # client may use expiry to prevent validation request if expired
+    expiry = self.tokens[client_id]['expiry']
+
+    return "token=#{token} client=#{client_id} expiry=#{expiry} uid=#{self.uid}"
+  end
+
+
+  def extend_batch_buffer(token, client_id)
+    self.tokens[client_id]['updated_at'] = Time.now
+    self.save!
+
+    return build_auth_header(token, client_id)
+  end
+
+
+  private
+
+
   def serializable_hash(options={})
     options ||= {}
     options[:except] ||= [:tokens]
     super(options)
   end
 
+
   # don't use default devise email validation
   def email_changed?
     false
   end
 
+
   def unique_email_user
     if provider == 'email' and User.where(provider: 'email', email: email).count > 0
-      errors.add(:email, "Your email address is already in use")
+      errors.add(:email, "This email address is already in use")
     end
   end
 
+
   def email_required?
     provider == 'email'
   end

data/lib/devise_token_auth/engine.rb

@@ -2,4 +2,16 @@ module DeviseTokenAuth
   class Engine < ::Rails::Engine
     isolate_namespace DeviseTokenAuth
   end
+
+  mattr_accessor :change_headers_on_each_request,
+                 :token_lifespan,
+                 :batch_request_buffer_throttle
+
+  self.change_headers_on_each_request = true
+  self.token_lifespan                 = 2.weeks
+  self.batch_request_buffer_throttle  = 2.seconds
+
+  def self.setup(&block)
+    yield self
+  end
 end

data/lib/devise_token_auth/version.rb

@@ -1,3 +1,3 @@
 module DeviseTokenAuth
-  VERSION = "0.1.16"
+  VERSION = "0.1.17"
 end

data/lib/generators/devise_token_auth/USAGE

@@ -1,8 +1,9 @@
 Description:
-    Explain the generator
+    This generator will install all the necessary configuration and migration files for the devies_token_auth gem
 
 Example:
-    rails generate devise_token_auth Thing
+    rails generate devise_token_auth:install
 
     This will create:
-        what/will/it/create
+        config/initializers/devise_token_auth.rb
+        db/migrate/xxxxxxxx_create_devise_token_auth_user.rb

data/lib/generators/devise_token_auth/install_generator.rb

@@ -0,0 +1,27 @@
+module DeviseTokenAuth
+  class InstallGenerator < Rails::Generators::Base
+    include Rails::Generators::Migration
+
+    source_root File.expand_path('../templates', __FILE__)
+
+    desc "This generator creates an initializer file at config/initializers/devise_token_auth.rb"
+    def create_initializer_file
+      copy_file("devise_token_auth.rb", "config/initializers/devise_token_auth.rb")
+    end
+
+    desc "This generator creates a user migration file at db/migrate/<%= migration_id %>_devise_token_auth_create_users.rb"
+    def copy_migrations
+      if self.class.migration_exists?("db/migrate", "devise_token_auth_create_users")
+        say_status("skipped", "Migration 'devise_token_auth' already exists")
+      else
+        migration_template("devise_token_auth_create_users.rb", "db/migrate/devise_token_auth_create_users.rb")
+      end
+    end
+
+    private
+
+    def self.next_migration_number(path)
+      Time.now.utc.strftime("%Y%m%d%H%M%S")
+    end
+  end
+end

data/lib/generators/devise_token_auth/templates/devise_token_auth.rb

@@ -0,0 +1,17 @@
+DeviseTokenAuth.setup do |config|
+  # By default the authorization headers will change after each request. The
+  # client is responsible for keeping track of the changing tokens. Change
+  # this to false to prevent the Authorization header from changing after
+  # each request.
+  #config.change_headers_on_each_request = true
+
+  # By default, users will need to re-authenticate after 2 weeks. This setting
+  # determines how long tokens will remain valid after they are issued.
+  #config.token_lifespan = 2.weeks
+
+  # Sometimes it's necessary to make several requests to the API at the same
+  # time. In this case, each request in the batch will need to share the same
+  # auth token. This setting determines how far apart the requests can be while
+  # still using the same auth token.
+  #config.batch_request_buffer_throttle = 2.seconds
+end

data/{db/migrate/20140628234942_devise_token_auth_create_users.rb → lib/generators/devise_token_auth/templates/devise_token_auth_create_users.rb}

@@ -41,7 +41,7 @@ class DeviseTokenAuthCreateUsers < ActiveRecord::Migration
       t.string :uid, :null => false, :default => ""
 
       ## Tokens
-      t.text :tokens, default: "{}"
+      t.string :tokens, default: "{}"
 
       t.timestamps
     end

data/test/controllers/demo_controller_test.rb

@@ -0,0 +1,233 @@
+require 'test_helper'
+
+#  was the web request successful?
+#  was the user redirected to the right page?
+#  was the user successfully authenticated?
+#  was the correct object stored in the response?
+#  was the appropriate message delivered in the json payload?
+
+class DemoControllerTest < ActionController::TestCase
+  describe DemoController, "Token access" do
+    setup do
+      @routes = Dummy::Application.routes
+    end
+
+    before do
+      @user = users(:confirmed_email_user)
+      @user.skip_confirmation!
+      @user.save!
+
+      @auth_header = @user.create_new_auth_token
+
+      @token       = @auth_header[/token=(.*?) /,1]
+      @client_id   = @auth_header[/client=(.*?) /,1]
+      @expiry      = @auth_header[/expiry=(.*?) /,1]
+    end
+
+    describe 'successful request' do
+      before do
+        # ensure that request is not treated as batch request
+        age_token(@user, @client_id)
+
+        request.headers['Authorization'] = @auth_header
+        xhr :get, :members_only
+
+        @resp_auth_header = response.headers['Authorization']
+        @resp_token       = @resp_auth_header[/token=(.*?) /,1]
+        @resp_client_id   = @resp_auth_header[/client=(.*?) /,1]
+        @resp_expiry      = @resp_auth_header[/expiry=(.*?) /,1]
+        @resp_uid         = @resp_auth_header[/uid=(.*?)$/,1]
+      end
+
+      it 'should return success status' do
+        assert_equal 200, response.status
+      end
+
+      it 'should receive new token after successful request' do
+        refute_equal @token, @resp_token
+      end
+
+      it 'should preserve the client id from the first request' do
+        assert_equal @client_id, @resp_client_id
+      end
+
+      it "should return the user's uid in the auth header" do
+        assert_equal @user.uid, @resp_uid
+      end
+
+      it 'should not treat this request as a batch request' do
+        refute assigns(:is_batch_request)
+      end
+
+      describe 'succesive requests' do
+        before do
+          @user.reload
+          # ensure that request is not treated as batch request
+          age_token(@user, @client_id)
+
+          request.headers['Authorization'] = @resp_auth_header
+
+          xhr :get, :members_only
+        end
+
+        it 'should not treat this request as a batch request' do
+          refute assigns(:is_batch_request)
+        end
+
+        it "should allow a new request to be made using new token" do
+          assert_equal 200, response.status
+        end
+      end
+    end
+
+    describe 'failed request' do
+      before do
+        request.headers['Authorization'] = "token=bogus client=#{@client_id} uid=#{@user.uid}"
+        xhr :get, :members_only
+      end
+
+      it 'should not return any auth headers' do
+        refute response.headers['Authorization']
+      end
+
+      it 'should return error: unauthorized status' do
+        assert_equal 401, response.status
+      end
+    end
+
+    describe 'disable change_headers_on_each_request' do
+      before do
+        DeviseTokenAuth.change_headers_on_each_request = false
+        @user.reload
+        age_token(@user, @client_id)
+
+        request.headers['Authorization'] = @auth_header
+        xhr :get, :members_only
+
+        @first_is_batch_request = assigns(:is_batch_request)
+        @first_user = assigns(:user).dup
+        @first_auth_headers = response.headers['Authorization'].clone
+        @first_response_status = response.status
+
+        @user.reload
+        age_token(@user, @client_id)
+
+        # use expired auth header
+        request.headers['Authorization'] = @auth_header
+        xhr :get, :members_only
+
+        @second_is_batch_request = assigns(:is_batch_request)
+        @second_user = assigns(:user)
+        @second_auth_headers = response.headers['Authorization']
+        @second_response_status = response.status
+      end
+
+      after do
+        DeviseTokenAuth.change_headers_on_each_request = true
+      end
+
+      it 'should allow the first request through' do
+        assert_equal 200, @first_response_status
+      end
+
+      it 'should allow the second request through' do
+        assert_equal 200, @second_response_status
+      end
+
+      it 'should return auth headers from the first request' do
+        assert @first_auth_headers
+      end
+
+      it 'should return auth headers from the second request' do
+        assert @second_auth_headers
+      end
+
+      it 'should define user during first request' do
+        assert @first_user
+      end
+
+      it 'should define user during second request' do
+        assert @second_user
+      end
+    end
+
+    describe 'batch requests' do
+      describe 'success' do
+        before do
+          request.headers['Authorization'] = @auth_header
+          xhr :get, :members_only
+
+          @first_is_batch_request = assigns(:is_batch_request)
+          @first_user = assigns(:user)
+          @first_auth_headers = response.headers['Authorization']
+
+          request.headers['Authorization'] = @auth_header
+          xhr :get, :members_only
+
+          @second_is_batch_request = assigns(:is_batch_request)
+          @second_user = assigns(:user)
+          @second_auth_headers = response.headers['Authorization']
+        end
+
+        it 'should allow both requests through' do
+          assert_equal 200, response.status
+        end
+
+        it 'should return the same auth headers for both requests' do
+          assert_equal @first_auth_headers, @second_auth_headers
+        end
+      end
+
+      describe 'time out' do
+        before do
+          @user.reload
+          age_token(@user, @client_id)
+
+          request.headers['Authorization'] = @auth_header
+          xhr :get, :members_only
+
+          @first_is_batch_request = assigns(:is_batch_request)
+          @first_user = assigns(:user).dup
+          @first_auth_headers = response.headers['Authorization'].clone
+          @first_response_status = response.status
+
+          @user.reload
+          age_token(@user, @client_id)
+
+          # use expired auth header
+          request.headers['Authorization'] = @auth_header
+          xhr :get, :members_only
+
+          @second_is_batch_request = assigns(:is_batch_request)
+          @second_user = assigns(:user)
+          @second_auth_headers = response.headers['Authorization']
+          @second_response_status = response.status
+        end
+
+        it 'should allow the first request through' do
+          assert_equal 200, @first_response_status
+        end
+
+        it 'should not allow the second request through' do
+          assert_equal 401, @second_response_status
+        end
+
+        it 'should return auth headers from the first request' do
+          assert @first_auth_headers
+        end
+
+        it 'should not return auth headers from the second request' do
+          refute @second_auth_headers
+        end
+
+        it 'should define user during first request' do
+          assert @first_user
+        end
+
+        it 'should not define user during second request' do
+          refute @second_user
+        end
+      end
+    end
+  end
+end