[v1.5] Multiple entities authentication (#72)

Multi model authentication

- Add multi model authentication
- Add JSON serialization to AuthToken
- Add token controller generator

Author: nsarno

CHANGELOG.md

@@ -2,10 +2,19 @@
 All notable changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](http://semver.org/).
 
-## Unreleased
-## Added
+## [Unreleased] - Unreleased
+### Added
+- Exception configuration option `Knock.not_found_exception_class_name`
+- Multiple entity authentication (e.g. User, Admin, etc)
 - Possibility to have permanent tokens
-- adding config options for exception class
+- Adding config options for exception class
+- Generator for token controller. E.g. `rails g knock:token_controller user`
+
+### Changed
+- Deprecated `Authenticable#authenticate` in favor of `Authenticable#authenticate_user`
+- Deprecated use of `Knock.current_user_from_token` in favor of `User.from_token_payload`
+- Deprecated use of direct route to `AuthTokenController` in favor of generating  a token controller
+- No need to mount the engine in `config/routes.rb` anymore
 
 ## [1.4.2] - 2016-01-29
 ### Fixed

CONTRIBUTING.md

@@ -1,7 +1,7 @@
 # Contributing Guidelines
 
 Contribution is always highly appreciated. Here are a few guidelines to make it
-easier and faster for pull requests to get merged and issues to get fixed. 
+easier and faster for pull requests to get merged and issues to get fixed.
 
 ### Issues
 

Gemfile

@@ -14,3 +14,4 @@ gemspec
 # gem 'byebug', group: [:development, :test]
 
 gem "codeclimate-test-reporter", group: :test, require: nil
+gem "simplecov", require: false, group: :test

README.md

@@ -26,13 +26,6 @@ Knock is an authentication solution for Rails API-only application based on JSON
 
 Yes.
 
-### Upcoming features & improvements
-
-- Easy way to authenticate multiple user types (User, Admin, ...)
-- Remove ActiveRecord dependency
-
-Really want some feature? Don't hesitate to open an issue :)
-
 ## Getting Started
 
 ### Installation
@@ -43,7 +36,7 @@ Add this line to your application's Gemfile:
 gem 'knock'
 ```
 
-And then execute:
+Then execute:
 
     $ bundle install
 
@@ -54,6 +47,13 @@ Finally, run the install generator:
 It will create the following initializer `config/initializers/knock.rb`.
 This file contains all the informations about the existing configuration options.
 
+If you don't use an external authentication solution like Auth0, you also need to provide a way for users to sign in:
+
+    $ rails generate knock:token_controller user
+
+This will generate the controller `user_token_controller.rb` and add the required route to your `config/routes.rb` file.
+You can also provide another entity instead of `user`. E.g. `admin`
+
 ### Requirements
 
 Knock makes one assumption about your user model:
@@ -70,30 +70,20 @@ Using `has_secure_password` is recommended, but you don't have to as long as you
 
 ### Usage
 
-Mount the `Knock::Engine` in your `config/routes.rb`
-
-```ruby
-Rails.application.routes.draw do
-  mount Knock::Engine => "/knock"
-
-  # your routes ...
-end
-```
-
-Then include the `Knock::Authenticable` module in your `ApplicationController`
+Include the `Knock::Authenticable` module in your `ApplicationController`
 
 ```ruby
 class ApplicationController < ActionController::API
   include Knock::Authenticable
 end
 ```
 
-You can now protect your resources by adding the `authenticate` before_action
-to your controllers like this:
+You can now protect your resources by calling `authenticate_user` as a before_action
+inside your controllers:
 
 ```ruby
-class MyResourcesController < ApplicationController
-  before_action :authenticate
+class SecuredController < ApplicationController
+  before_action :authenticate_user
 
   def index
     # etc...
@@ -103,33 +93,102 @@ class MyResourcesController < ApplicationController
 end
 ```
 
+You can access the current user in your controller with `current_user`.
+
 If no valid token is passed with the request, Knock will respond with:
 
 ```
 head :unauthorized
 ```
 
-If you just want to read the `current_user`, without actually authenticating, you can also do that:
+You also have access directly to `current_user` which will try to authenticate or return `nil`:
+
+```ruby
+def index
+  if current_user
+    # do something
+  else
+    # do something else
+  end
+end
+```
+
+Note: the `authenticate_user` method uses the `current_user` method. Overwriting `current_user` may cause unexpected behaviour.
+
+You can do the exact same thing for any entity. E.g. for `Admin`, use `authenticate_admin` and `current_admin` instead.
+
+### Customization
+
+#### Via the entity model
+
+The entity model (e.g. `User`) can implement specific methods to provide
+customization over different parts of the authentication process.
+
+- **Find the entity when creating the token (when signing in)**
+
+By default, Knock tries to find the entity by email. If you want to modify this
+behaviour, implement within your entity model a class method `from_token_request`
+that takes the request in argument.
+
+E.g.
+
+```ruby
+class User < ActiveRecord::Base
+  def self.from_token_request request
+    # Returns a valid user, `nil` or raise `Knock.not_found_exception_class_name`
+    # e.g.
+    #   email = request.params["auth"] && request.params["auth"]["email"]
+    #   self.find_by email: email
+  end
+end
+```
+
+- **Find the authenticated entity from the token payload (when authenticating a request)**
+
+By default, Knock assumes the payload as a subject (`sub`) claim containing the entity's id
+and calls `find` on the model. If you want to modify this behaviour, implement within
+your entity model a class method `from_token_payload` that takes the
+payload in argument.
+
+E.g.
 
 ```ruby
-class CurrentUsersController < ApplicationController
-  def show
-    if current_user
-      head :ok
-    else
-      head :not_found
-    end
+class User < ActiveRecord::Base
+  def self.from_token_payload payload
+    # Returns a valid user, `nil` or raise
+    # e.g.
+    #   self.find payload["sub"]
   end
 end
 ```
 
-Note that the `authenticate` method depends upon the `current_user` method. Overwriting `current_user` in the controller may break the `authenticate` method.
+- **Modify the token payload**
+
+By default the token payload contains the entity's id inside the subject (`sub`) claim.
+If you want to modify this behaviour, implement within your entity model an instance method
+`to_token_payload` that returns a hash representing the payload.
+
+E.g.
+
+```ruby
+class User < ActiveRecord::Base
+  def to_token_payload
+    # Returns the payload as a hash
+  end
+end
+```
+
+#### Via the initializer
+
+The initializer [config/initializers/knock.rb](https://github.com/nsarno/knock/blob/master/lib/generators/templates/knock.rb)
+is generated when `rails g knock:install` is executed. Each configuration variable is
+documented with comments in the initializer itself.
 
-### Authenticating from a web or mobile application:
+### Authenticating from a web or mobile application
 
 Example request to get a token from your API:
 ```
-POST /knock/auth_token
+POST /user_auth_token
 {"auth": {"email": "[email protected]", "password": "secret"}}
 ```
 
@@ -139,7 +198,7 @@ Example response from the API:
 {"jwt": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9"}
 ```
 
-To make an authenticated request to your API, you need to pass the token in the request header:
+To make an authenticated request to your API, you need to pass the token via the request header:
 ```
 Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9
 GET /my_resources
@@ -157,7 +216,7 @@ To authenticate within your tests:
 e.g.
 
 ```ruby
-class MyResourcesControllerTest < ActionController::TestCase
+class SecuredControllerTest < ActionController::TestCase
   def authenticate
     token = Knock::AuthToken.new(payload: { sub: users(:one).id }).token
     request.env['HTTP_AUTHORIZATION'] = "Bearer #{token}"

app/controllers/knock/auth_token_controller.rb

@@ -2,23 +2,48 @@
 
 module Knock
   class AuthTokenController < ApplicationController
-    before_action :authenticate!
+    before_action :authenticate
 
     def create
-      render json: { jwt: auth_token.token }, status: :created
+      render json: auth_token, status: :created
     end
 
   private
-    def authenticate!
-      raise Knock.not_found_exception_class unless user.authenticate(auth_params[:password])
+    def authenticate
+      unless entity.present? && entity.authenticate(auth_params[:password])
+        raise Knock.not_found_exception_class
+      end
     end
 
     def auth_token
-      AuthToken.new payload: { sub: user.id }
+      if entity.respond_to? :to_token_payload
+        AuthToken.new payload: entity.to_token_payload
+      else
+        AuthToken.new payload: { sub: entity.id }
+      end
     end
 
-    def user
-      Knock.current_user_from_handle.call auth_params[Knock.handle_attr]
+    def entity
+      @entity ||=
+        if self.class.name == "Knock::AuthTokenController"
+          warn "[DEPRECATION]: Routing to `AuthTokenController` directly is deprecated. Please use `<Entity Name>TokenController` inheriting from it instead. E.g. `UserTokenController`"
+          warn "[DEPRECATION]: Relying on `Knock.current_user_from_handle` is deprecated. Please implement `User#from_token_request` instead."
+          Knock.current_user_from_handle.call auth_params[Knock.handle_attr]
+        else
+          if entity_class.respond_to? :from_token_request
+            entity_class.from_token_request request
+          else
+            entity_class.find_by email: auth_params[:email]
+          end
+        end
+    end
+
+    def entity_class
+      entity_name.constantize
+    end
+
+    def entity_name
+      self.class.name.split('TokenController').first
     end
 
     def auth_params

app/model/knock/auth_token.rb

@@ -17,8 +17,21 @@ def initialize payload: {}, token: nil
       end
     end
 
-    def current_user
-      @current_user ||= Knock.current_user_from_token.call @payload
+    def entity_for entity_class
+      if entity_class.respond_to? :from_token_payload
+        entity_class.from_token_payload @payload
+      else
+        if entity_class.to_s == "User" && Knock.respond_to?(:current_user_from_token)
+          warn "[DEPRECATION]: `Knock.current_user_from_token` is deprecated. Please implement `User.from_token_payload` instead."
+          Knock.current_user_from_token.call @payload
+        else
+          entity_class.find @payload['sub']
+        end
+      end
+    end
+
+    def to_json options = {}
+      {jwt: @token}.to_json
     end
 
   private

lib/generators/knock/token_controller_generator.rb

@@ -0,0 +1,25 @@
+module Knock
+  class TokenControllerGenerator < Rails::Generators::Base
+    source_root File.expand_path("../../templates", __FILE__)
+    argument :name, type: :string
+
+    desc <<-DESC
+      Creates a Knock token controller for the given entity
+      and add the corresponding routes.
+    DESC
+
+    def copy_controller_file
+      template 'entity_token_controller.rb.erb', "app/controllers/#{name.underscore}_token_controller.rb"
+    end
+
+    def add_route
+      route "post '#{name.underscore}_token' => '#{name.underscore}_token#create'"
+    end
+
+    private
+
+    def entity_name
+      name
+    end
+  end
+end

lib/generators/templates/entity_token_controller.rb.erb

@@ -0,0 +1,2 @@
+class <%= entity_name.camelize %>TokenController < Knock::AuthTokenController
+end

lib/generators/templates/knock.rb

@@ -1,5 +1,8 @@
 Knock.setup do |config|
 
+  ## [DEPRECATED]
+  ## This is deprecated in favor of `User.from_token_request`.
+  ##
   ## User handle attribute
   ## ---------------------
   ##
@@ -8,6 +11,9 @@
   ## Default:
   # config.handle_attr = :email
 
+  ## [DEPRECATED]
+  ## This is deprecated in favor of `User.from_token_request`.
+  ##
   ## Current user retrieval from handle when signing in
   ## --------------------------------------------------
   ##
@@ -25,6 +31,9 @@
   ## Default:
   # config.current_user_from_handle = -> (handle) { User.find_by! Knock.handle_attr => handle }
 
+  ## [DEPRECATED]
+  ## This is depreacted in favor of `User.from_token_payload`.
+  ##
   ## Current user retrieval when validating token
   ## --------------------------------------------
   ##
@@ -92,8 +101,7 @@
   ## Exception Class
   ## ---------------
   ##
-  ## Configure the Exception to be used (raised and rescued) for User Not Found.
-  ## note: change this if ActiveRecord is not being used.
+  ## Configure the exception to be used when user cannot be found.
   ##
   ## Default:
   # config.not_found_exception_class_name = 'ActiveRecord::RecordNotFound'