api_guard 0.2.2 → 0.5.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 6b7ce3ac5306ae3a652084d29da83f37ec9b41c5
-  data.tar.gz: 7fb6b919ed4044e459a3840e442505326bfda971
+SHA256:
+  metadata.gz: bc003426a48f2bf1a83d3b1653438efa43522f465a4cf98b4ac0b030f691cbfd
+  data.tar.gz: 771a016a40a938684ea61accde401e7eed3dc8c201688f51bb0444cd241901d7
 SHA512:
-  metadata.gz: e02605d2b473c9931a1c494203562ae9e87ef90d5b3adfa4e043aba6b96e3da7aa3fc306189139a4d546b7b88eb4ecbdb876783dab28b9e6879b37dcca2f1c97
-  data.tar.gz: 293b709e2ae69d3b07912c319d5fd37c8ae3156797cf09b19aa55ab8bc317e90822747a3b3d0a856c368d0e16d8a89cdb7b6ca208d047e9dc5142db81db385d8
+  metadata.gz: 16a0a967961773fcfdab3744fcfd228198484eb550b7b6abeb19e4daa1d2a42d7ecf2730709c4ab7f518bdb0fe1781973255b24da60c67a88b71198cb76913d1
+  data.tar.gz: e609d92695acc9d424739450b87c6a7cd4725d200e3b3bdf745e465e2c090fe9af7bb15820bb02d9964cc0af420f7faa34fede752484b41dcfe9aaf7bc53114c

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-master/badge.svg?branch=master)](https://github.com/Gokul595/api_guard/actions?query=workflow%3Abuild-master)
 [![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.
@@ -194,6 +202,8 @@ To authenticate the API request just add this before_action in the controller:
 before_action :authenticate_and_set_user
 ```
 
+>**Note:** It is possible to authenticate with more than one resource, e.g. `authenticate_and_set_user_or_admin` will permit tokens issued for users or admins.
+
 Send the access token got in sign in API in the Authorization header in the API request as below. 
 Also, make sure you add "Bearer" before the access token in the header value.
 
@@ -353,19 +363,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 +399,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 
@@ -439,11 +453,11 @@ api_guard_associations refresh_token: 'refresh_tokens', blacklisted_token: 'blac
 
 ### Token blacklisting
 
-To include token blacklisting in your application you need to create a table to store the refresh tokens. This will be 
+To include token blacklisting in your application you need to create a table to store the blacklisted tokens. This will be 
 used to blacklist a JWT access token from future use. The access token will be blacklisted on successful sign out of the 
 resource.
 
-Use below command to create a model `RefeshToken` with columns to store the token and the user reference
+Use below command to create a model `BlacklistedToken` with columns to store the token and the user reference
 
 ```bash
 $ rails generate model blacklisted_token token:string user:references expire_at:datetime
@@ -539,28 +553,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,6 +1,8 @@
-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'
@@ -24,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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module ApiGuard
   class AppSecretKey
     def initialize(application)

data/lib/api_guard/engine.rb

@@ -1,10 +1,12 @@
+# 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