api_guard 0.2.1 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 4bbc1b32deafff68b420cf4b56f343d67a90caa7
-  data.tar.gz: 5b7f2aa8e25c5fd1fdbf5c4d21d99fb3461ecf33
+SHA256:
+  metadata.gz: db273f8953347d07ed9d5acb5923480e463461517e2e1396d37a9db704ffc218
+  data.tar.gz: 92b5aeffc41c1d97d3d1ade1389b4acd902ff66166ecb3895fd858b0f8f51a01
 SHA512:
-  metadata.gz: cc4e72c586bae02e4f5bb9671e070625f58c88152924ff1448cd2b7d0ce805aa6f47db48ee8359b6411321e1333ddf3ae121ce2ba85a5a1d20471101cf7d16a2
-  data.tar.gz: 8284feb1676f32b989735c9097f5f1c2e329f6e150ab2ebed2fba4b622a7c1eb7b9ba7186f01f049738a8d5a4920c857e23de9a96b0eef09c8b3be715b29b3ea
+  metadata.gz: d99aa923a6b41bdc4b1c5524cc9159342fee8e1c31931d0387c21651d7b338ccef6be7773cdd48d8773f1b50000e228310bf7a18d9c3cefaeb52f63f2b82c824
+  data.tar.gz: 3651814062e401e8c8be16d9c103a23de042232140bccb10a79977dc3ffdb7370b658ddfeed26cc3e995705e3d7e60c90d97f5b65469025eed717260e6097a31

data/README.md

@@ -1,9 +1,8 @@
 # API Guard
 
 [![Version](https://img.shields.io/gem/v/api_guard.svg?color=green)](https://rubygems.org/gems/api_guard)
-[![Build Status](https://travis-ci.org/Gokul595/api_guard.svg?branch=master)](https://travis-ci.org/Gokul595/api_guard)
+[![Build Status](https://github.com/Gokul595/api_guard/workflows/build/badge.svg?branch=master)](https://github.com/Gokul595/api_guard/actions?query=workflow%3Abuild)
 [![Maintainability](https://api.codeclimate.com/v1/badges/ced3e74a26a66ed915cb/maintainability)](https://codeclimate.com/github/Gokul595/api_guard/maintainability)
-[![Test Coverage](https://api.codeclimate.com/v1/badges/ced3e74a26a66ed915cb/test_coverage)](https://codeclimate.com/github/Gokul595/api_guard/test_coverage)
 
 
 [JSON Web Token (JWT)](https://jwt.io/) based authentication solution with token refreshing & blacklisting for APIs 
@@ -35,7 +34,12 @@ for cryptographic signing.
 * [Overriding defaults](#overriding-defaults)
     * [Controllers](#controllers)
     * [Routes](#routes)
+    * [Adding custom data in JWT token payload](#adding-custom-data-in-jwt-token-payload)
+    * [Override finding resource](#override-finding-resource)
+    * [Customizing / translating response messages using I18n](#customizing--translating-response-messages-using-i18n)
 * [Testing](#testing)
+* [Wiki](https://github.com/Gokul595/api_guard/wiki)
+    * [Using API Guard with Devise](https://github.com/Gokul595/api_guard/wiki/Using-API-Guard-with-Devise)
 * [Contributing](#contributing)
 * [License](#license)
 
@@ -63,20 +67,22 @@ Below steps are provided assuming the model in `User`.
 
 ### Creating User model
 
-Create a model for User with below command
+Create a model for User with below command.
 
 ```bash
 $ rails generate model user name:string email:string:uniq password_digest:string
 ```
 
-Then, run migration to create the `users` table
+Then, run migration to create the `users` table.
 
 ```bash
 $ rails db:migrate
 ```
 
 Add [has_secure_password](https://api.rubyonrails.org/classes/ActiveModel/SecurePassword/ClassMethods.html#method-i-has_secure_password) 
-in `User` model for password authentication
+in `User` model for password authentication. 
+
+> Refer [this Wiki](https://github.com/Gokul595/api_guard/wiki/Using-API-Guard-with-Devise#authentication) for configuring API Guard authentication to work with Devise instead of using `has_secure_password`.
 
 ```ruby
 class User < ApplicationRecord
@@ -86,7 +92,7 @@ end
 
 Then, add `bcrypt` gem in your Gemfile which is used by 
 [has_secure_password](https://api.rubyonrails.org/classes/ActiveModel/SecurePassword/ClassMethods.html#method-i-has_secure_password)
-for encrypting password and authentication
+for encrypting password and authentication.
 
 ```ruby
 gem 'bcrypt', '~> 3.1.7'
@@ -108,6 +114,8 @@ api_guard_routes for: 'users'
 
 This will generate default routes such as sign up, sign in, sign out, token refresh, password change for User.
 
+> Refer [this Wiki](https://github.com/Gokul595/api_guard/wiki/Using-API-Guard-with-Devise#routes) for configuring API Guard routes to work with Devise.
+
 ### Registration
 
 This will create an user and responds with access token, refresh token and access token expiry in the response header.
@@ -353,19 +361,19 @@ configurations.
 ApiGuard.setup do |config|
   # Validity of the JWT access token
   # Default: 1 day
-  config.token_validity = 1.day
+  # config.token_validity = 1.day
 
   # Secret key for signing (encoding & decoding) the JWT access token
   # Default: 'secret_key_base' from Rails secrets 
-  config.token_signing_secret = Rails.application.secrets.secret_key_base
+  # config.token_signing_secret = 'my_signing_secret'
 
   # Invalidate old tokens on changing the password
   # Default: false
-  config.invalidate_old_tokens_on_password_change = false
+  # config.invalidate_old_tokens_on_password_change = false
 
   # Blacklist JWT access token after refreshing
   # Default: false
-  config.blacklist_token_after_refreshing = false
+  # config.blacklist_token_after_refreshing = false
 end
 ```
 
@@ -389,6 +397,10 @@ Override this by configuring `token_signing_secret`
 config.token_signing_secret = 'my_signing_secret'
 ```
 
+>**Note:** Avoid committing this token signing secret in your version control (GIT) and always keep this secure. As,
+>exposing this allow anyone to generate JWT access token and give full access to APIs. Better way is storing this value
+>in environment variable or in encrypted secrets (Rails 5.2+)
+
 ### Invalidate tokens on password change
 
 By default, API Guard will not invalidate old JWT access tokens on changing password. If you need, you can enable it by 
@@ -539,28 +551,96 @@ api_guard_routes for: 'users', only: [:authentication]
 
 >**Available controllers:** registration, authentication, tokens, passwords
 
-**Customizing the routes**
+**Customizing the route path:**
 
-To customize the default routes generated by API Guard you can use `api_guard_scope` in the routes.
+You can customize the path of the default routes of the API Guard using the `api_guard_scope` as below,
 
 ```ruby
 api_guard_routes for: 'users', except: [:registration]
 
 api_guard_scope 'users' do
-  post 'account/create' => 'users/registration#create'
-  delete 'account/delete' => 'users/registration#destroy'
+  post 'account/create' => 'api_guard/registration#create'
+  delete 'account/delete' => 'api_guard/registration#destroy'
 end
 ```
 
 Above configuration will replace default registration routes `users/sign_up` & `users/delete` with `account/create` & 
 `account/delete`
 
+### Adding custom data in JWT token payload
+
+You can add custom data in the JWT token payload in the format of Hash and use the data after decoding the token on 
+every request.
+
+To add custom data, you need to create an instance method `jwt_token_payload` in the resource model as below which 
+should return a Hash,
+
+```ruby
+class User < ApplicationRecord
+  def jwt_token_payload
+    { custom_key: 'value' }
+  end
+end
+```
+
+API Guard will add the hash returned by this method to the JWT token payload in addition to the default payload values. 
+This data (including default payload values) will be available in the instance variable `@decoded_token` on each request 
+if the token has been successfully decoded. You can access the values as below,
+
+```ruby
+@decoded_token[:custom_key]
+```
+
+### Override finding resource
+
+By default, API Guard will try to find the resource by it's `id`. If you wish to override this default behavior, you can
+do it by creating a method `find_resource_from_token` in the specific controller or in `ApplicationController` as you 
+need.
+
+**Adding custom logic in addition to the default logic:**
+```ruby
+def find_resource_from_token(resource_class)
+  user = super # This will call the actual method defined in API Guard
+  user if user&.active?
+end
+```
+
+**Using custom query to find the user from the token:**
+```ruby
+def find_resource_from_token(resource_class)
+  resource_id = @decoded_token[:"#{@resource_name}_id"]
+  resource_class.find_by(id: resource_id, status: 'active') if resource_id
+end
+```
+
+This method has an argument `resource_class` which is the class (model) of the current resource (`User`).
+This method should return a resource object to successfully authenticate the request or `nil` to respond with 401.
+
+You can also use the [custom data](#adding-custom-data-in-jwt-token-payload) added in the JWT token payload using 
+`@decoded_token` instance variable and customize the logic as you need.
+
+### Customizing / translating response messages using I18n
+
+API Guard uses [I18n](https://guides.rubyonrails.org/i18n.html) for success and error messages. You can create your own 
+locale file and customize the messages for any language.
+
+```yaml
+en:
+  api_guard:
+    authentication:
+      signed_in: 'Signed in successfully'
+      signed_out: 'Signed out successfully'
+```
+
+You can find the complete list of available keys in this file:
+https://github.com/Gokul595/api_guard/blob/master/config/locales/en.yml
+
 ## Testing
 
 API Guard comes with helper for creating JWT access token and refresh token for the resource which you can use it for 
 testing the controllers of your application.
 
-For using it include the helper in you test framework
+For using it, just include the helper in your test framework.
 
 **RSpec**
 

data/Rakefile

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 begin
   require 'bundler/setup'
 rescue LoadError
@@ -14,11 +16,6 @@ RDoc::Task.new(:rdoc) do |rdoc|
   rdoc.rdoc_files.include('lib/**/*.rb')
 end
 
-
-
 load 'rails/tasks/statistics.rake'
 
-
-
 require 'bundler/gem_tasks'
-

data/app/controllers/api_guard/application_controller.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module ApiGuard
   class ApplicationController < ActionController::Base
     skip_before_action :verify_authenticity_token, raise: false

data/app/controllers/api_guard/authentication_controller.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require_dependency 'api_guard/application_controller'
 
 module ApiGuard
@@ -8,22 +10,22 @@ module ApiGuard
     def create
       if resource.authenticate(params[:password])
         create_token_and_set_header(resource, resource_name)
-        render_success(message: 'Signed in successfully')
+        render_success(message: I18n.t('api_guard.authentication.signed_in'))
       else
-        render_error(422, message: 'Invalid login credentials')
+        render_error(422, message: I18n.t('api_guard.authentication.invalid_login_credentials'))
       end
     end
 
     def destroy
       blacklist_token
-      render_success(message: 'Signed out successfully')
+      render_success(message: I18n.t('api_guard.authentication.signed_out'))
     end
 
     private
 
     def find_resource
       self.resource = resource_class.find_by(email: params[:email].downcase.strip) if params[:email].present?
-      render_error(422, message: 'Invalid login credentials') unless resource
+      render_error(422, message: I18n.t('api_guard.authentication.invalid_login_credentials')) unless resource
     end
   end
 end

data/app/controllers/api_guard/passwords_controller.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require_dependency 'api_guard/application_controller'
 
 module ApiGuard
@@ -7,12 +9,12 @@ module ApiGuard
     def update
       invalidate_old_jwt_tokens(current_resource)
 
-      if current_resource.update_attributes(password_params)
+      if current_resource.update(password_params)
         blacklist_token unless ApiGuard.invalidate_old_tokens_on_password_change
         destroy_all_refresh_tokens(current_resource)
 
         create_token_and_set_header(current_resource, resource_name)
-        render_success(message: 'Password changed successfully')
+        render_success(message: I18n.t('api_guard.password.changed'))
       else
         render_error(422, object: current_resource)
       end

data/app/controllers/api_guard/registration_controller.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require_dependency 'api_guard/application_controller'
 
 module ApiGuard
@@ -8,7 +10,7 @@ module ApiGuard
       init_resource(sign_up_params)
       if resource.save
         create_token_and_set_header(resource, resource_name)
-        render_success(message: 'Signed up successfully')
+        render_success(message: I18n.t('api_guard.registration.signed_up'))
       else
         render_error(422, object: resource)
       end
@@ -16,7 +18,7 @@ module ApiGuard
 
     def destroy
       current_resource.destroy
-      render_success(message: "Account deleted successfully")
+      render_success(message: I18n.t('api_guard.registration.account_deleted'))
     end
 
     private

data/app/controllers/api_guard/tokens_controller.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require_dependency 'api_guard/application_controller'
 
 module ApiGuard
@@ -11,7 +13,7 @@ module ApiGuard
       @refresh_token.destroy
       blacklist_token if ApiGuard.blacklist_token_after_refreshing
 
-      render_success(message: 'Token refreshed successfully')
+      render_success(message: I18n.t('api_guard.access_token.refreshed'))
     end
 
     private
@@ -21,9 +23,9 @@ module ApiGuard
 
       if refresh_token_from_header
         @refresh_token = find_refresh_token_of(current_resource, refresh_token_from_header)
-        return render_error(401, message: 'Invalid refresh token') unless @refresh_token
+        return render_error(401, message: I18n.t('api_guard.refresh_token.invalid')) unless @refresh_token
       else
-        render_error(401, message: 'Refresh token is missing in the request')
+        render_error(401, message: I18n.t('api_guard.refresh_token.missing'))
       end
     end
   end

data/config/locales/en.yml

@@ -0,0 +1,22 @@
+en:
+  api_guard:
+    authentication:
+      signed_in: 'Signed in successfully'
+      signed_out: 'Signed out successfully'
+      invalid_login_credentials: 'Invalid login credentials'
+    password:
+      changed: 'Password changed successfully'
+    registration:
+      signed_up: 'Signed up successfully'
+      account_deleted: 'Account deleted successfully'
+    access_token:
+      refreshed: 'Token refreshed successfully'
+      missing: 'Access token is missing in the request'
+      invalid: 'Invalid access token'
+      expired: 'Access token expired'
+    refresh_token:
+      invalid: 'Invalid refresh token'
+      missing: 'Refresh token is missing in the request'
+    response:
+      success: 'success'
+      error: 'error'

data/config/routes.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 ApiGuard::Engine.routes.draw do
   # Can't see anything here?
   # Goto 'lib/api_guard/route_mapper.rb'

data/lib/api_guard.rb

@@ -1,8 +1,12 @@
-require "api_guard/engine"
-require "api_guard/route_mapper"
-require "api_guard/modules"
+# frozen_string_literal: true
+
+require 'api_guard/engine'
+require 'api_guard/route_mapper'
+require 'api_guard/modules'
 
 module ApiGuard
+  autoload :AppSecretKey, 'api_guard/app_secret_key'
+
   module Test
     autoload :ControllerHelper, 'api_guard/test/controller_helper'
   end
@@ -22,14 +26,15 @@ module ApiGuard
   mattr_accessor :api_guard_associations
   self.api_guard_associations = {}
 
-  mattr_reader :mapped_resource
-  @@mapped_resource = {}
+  mattr_reader :mapped_resource do
+    {}
+  end
 
   def self.setup
     yield self
   end
 
   def self.map_resource(routes_for, class_name)
-    @@mapped_resource[routes_for.to_sym] = ApiGuard::ResourceMapper.new(routes_for, class_name)
+    mapped_resource[routes_for.to_sym] = ApiGuard::ResourceMapper.new(routes_for, class_name)
   end
 end

data/lib/api_guard/app_secret_key.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module ApiGuard
+  class AppSecretKey
+    def initialize(application)
+      @application = application
+    end
+
+    def detect
+      secret_key_base(:credentials) || secret_key_base(:secrets) ||
+        secret_key_base(:config) || secret_key_base
+    end
+
+    private
+
+    def secret_key_base(source = nil)
+      return @application.secret_key_base unless source
+
+      @application.send(source).secret_key_base.presence if @application.respond_to?(source)
+    end
+  end
+end

data/lib/api_guard/engine.rb

@@ -1,18 +1,17 @@
+# frozen_string_literal: true
+
 module ApiGuard
   class Engine < ::Rails::Engine
     isolate_namespace ApiGuard
 
     config.generators do |g|
       g.test_framework :rspec
-      g.fixture_replacement :factory_girl, :dir => 'spec/factories'
+      g.fixture_replacement :factory_girl, dir: 'spec/factories'
     end
 
     # Use 'secret_key_base' from Rails secrets if 'token_signing_secret' is not configured
     initializer 'ApiGuard.token_signing_secret' do |app|
-      unless ApiGuard.token_signing_secret
-        signing_secret = app.respond_to?(:credentials) ? app.credentials.secret_key_base : app.secrets.secret_key_base
-        ApiGuard.token_signing_secret = signing_secret
-      end
+      ApiGuard.token_signing_secret ||= ApiGuard::AppSecretKey.new(app).detect
     end
   end
 end