rails_jwt_auth 0.18.1 → 1.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 3f935bf415eb61e8c8d04a0ee5701e35225a1f68
-  data.tar.gz: 5f97e07f1f1ff4de288872d717f6b632a6132417
+SHA256:
+  metadata.gz: 3ce38e7a38fa015a6dbf8b1504e41fd273cf3646d0b2d9053c63476d55b3c729
+  data.tar.gz: 9581d2075661754ed5d43f3a344c8d3fd0da631b9b5c8ea8e51b65fa14bb2c33
 SHA512:
-  metadata.gz: 0a8976264bfcf1fae83bf32d8c3f2930141b162614a0af7b9782ca90725ba4af8173508eb7c1fa7c8094624e0f477faad6337ca6a2e99376bbc84c7be5b75594
-  data.tar.gz: 297a00da37aff4ece4ba9580e0e2d59bd1351f9dfe234373e00ac8de9f917094b814de50ca501305465eaf1551158a0129102d59fd25f62ef80e72c87721d59f
+  metadata.gz: f0bdc862727abcdc1db5d1a3e00bd124b7ac15e45d47e483b8487ba46854dfc68edda3a1dcef1d5cda55fb733840f7679f2bbd03996cae3ee4e775d0f12f5a5d
+  data.tar.gz: 58cd478adf9a9145fb33e7f531e8010faa6e68f86243478515333acc9aa5578531f047ca059620ae1ce867cff8fbbf7a03de5ceb81e30ede35b9d8360e5392b6

data/README.md

@@ -1,8 +1,29 @@
 # RailsJwtAuth
+
 [![Gem Version](https://badge.fury.io/rb/rails_jwt_auth.svg)](https://badge.fury.io/rb/rails_jwt_auth)
 ![Build Status](https://travis-ci.org/rjurado01/rails_jwt_auth.svg?branch=master)
 
-Rails-API authentication solution based on Warden and JWT and inspired by Devise.
+Rails-API authentication solution based on JWT and inspired by Devise.
+
+> This is documentation for version `1.x`. If you are using `0.x` version use this
+[link](https://github.com/rjurado01/rails_jwt_auth/tree/0.x)
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Configuration](#configuration)
+- [Modules](#modules)
+- [ORMs support](#orms-support)
+- [Controller helpers](#controller-helpers)
+- [Default Controllers API](#default-controllers-api)
+- [Customize]()
+    + [Controllers](#custom-controllers)
+    + [Payload](#custom-payload)
+    + [Responses](#custom-responses)
+    + [Strong parameters](#custom-strong-parameters)
+- [Examples](#examples)
+- [Testing](#testing-rspec)
+- [License](#license)
 
 ## Installation
 
@@ -30,228 +51,88 @@ Finally execute:
 rails g rails_jwt_auth:install
 ```
 
-## Configuration
-
-You can edit configuration options into `config/initializers/auth_token_auth.rb` file created by generator.
-
-| Option                         | Default value     | Description                                                           |
-| ------------------------------ | ----------------- | --------------------------------------------------------------------- |
-| model_name                     | 'User'            | Authentication model name                                             |
-| auth_field_name                | 'email'           | Field used to authenticate user with password                         |
-| auth_field_email               | true              | Validate auth field email format                                      |
-| email_regex                    | see config file   | Regex used to Validate email format                                   |
-| jwt_expiration_time            | 7.days            | Tokens expiration time                                                |
-| jwt_issuer                     | 'RailsJwtAuth'    | The "iss" (issuer) claim identifies the principal that issued the JWT |
-| simultaneous_sessions          | 2                 | Number of simultaneous sessions for an user                           |
-| mailer_sender                  |                   | E-mail address which will be shown in RailsJwtAuth::Mailer            |
-| confirmation_url               | confirmation_path | Url used to create email link with confirmation token                 |
-| confirmation_expiration_time   | 1.day             | Confirmation token expiration time                                    |
-| reset_password_url             | password_path     | Url used to create email link with reset password token               |
-| reset_password_expiration_time | 1.day             | Confirmation token expiration time                                    |
-| set_password_url               | password_path     | Url used to create email link with set password token                 |
-| deliver_later                  | false             | Uses `deliver_later` method to send emails                            |
-| invitation_expiration_time     | 2.days            | Time an invitation is valid and can be accepted                       |
-| invitation_url                 | invitation_path   | URL used to create email link with invitation token                   |
-
-## Authenticatable
-
-Hashes and stores a password in the database to validate the authenticity of a user while signing in.
-
-### ActiveRecord
-
-Include `RailsJwtAuth::Authenticatable` module into your User class:
-
-```ruby
-# app/models/user.rb
-class User < ApplicationRecord
-  include RailsJwtAuth::Authenticatable
-end
-```
-
-and create a migration to add authenticable fields to User model:
-
-```ruby
-# example migration
-create_table :users do |t|
-  t.string :email
-  t.string :password_digest
-  t.string :auth_tokens
-end
-```
-
-### Mongoid
-
-Include `RailsJwtAuth::Authenticatable` module into your User class:
+Only for ActiveRecord, generate migrations:
 
-```ruby
-# app/models/user.rb
-class User
-  include Mongoid::Document
-  include RailsJwtAuth::Authenticatable
-end
+```bash
+rails g rails_jwt_auth:migrate
 ```
 
-Fields are added automatically.
-
-## Confirmable
-
-Sends emails with confirmation instructions and verifies whether an account is already confirmed during sign in.
+## Configuration
 
-### ActiveRecord
+You can edit configuration options into `config/initializers/auth_token_auth.rb` file created by generator.
 
-Include `RailsJwtAuth::Confirmable` module into your User class:
+| Option                          | Default value     | Description                                                            |
+| ------------------------------- | ----------------- | ---------------------------------------------------------------------- |
+| model_name                      | 'User'            | Authentication model name                                              |
+| auth_field_name                 | 'email'           | Field used to authenticate user with password                          |
+| email_auth_field                | 'email'           | Field used to send emails                                              |
+| jwt_expiration_time             | 7.days            | Tokens expiration time                                                 |
+| jwt_issuer                      | 'RailsJwtAuth'    | The "iss" (issuer) claim identifies the principal that issued the JWT  |
+| simultaneous_sessions           | 2                 | Number of simultaneous sessions for an user. Set 0 to disable sessions |
+| mailer_sender                   |                   | E-mail address which will be shown in RailsJwtAuth::Mailer             |
+| send_email_changed_notification | true              | Notify original email when it changes                                  |
+| confirmation_expiration_time    | 1.day             | Confirmation token expiration time                                     |
+| reset_password_expiration_time  | 1.day             | Confirmation token expiration time                                     |
+| deliver_later                   | false             | Uses `deliver_later` method to send emails                             |
+| invitation_expiration_time      | 2.days            | Time an invitation is valid and can be accepted                        |
+| confirmations_url               | nil               | Url used to create email link with confirmation token                  |
+| reset_passwords_url             | nil               | Url used to create email link with reset password token                |
+| set_passwords_url               | nil               | Url used to create email link with set password token                  |
+| invitationss_url                | nil               | Url used to create email link with invitation token                    |
+
+## Modules
+
+It's composed of 5 modules:
+
+| Module        | Description                                                                                                     |
+| ------------- | --------------------------------------------------------------------------------------------------------------- |
+| Authenticable | Hashes and stores a password in the database to validate the authenticity of a user while signing in            |
+| Confirmable   | Sends emails with confirmation instructions and verifies whether an account is already confirmed during sign in |
+| Recoverable   | Resets the user password and sends reset instructions                                                           |
+| Trackable     | Tracks sign in timestamps and IP address                                                                        |
+| Invitable     | Allows you to invite an user to your application sending an invitation mail                                     |
+
+## ORMs support
+
+RailsJwtAuth support both Mongoid and ActiveRecord.
+
+For next examples `auth_field_name` and `email_field_name` are configured to use the field `email`.
+
+**ActiveRecord**
 
 ```ruby
 # app/models/user.rb
 class User < ApplicationRecord
   include RailsJwtAuth::Authenticatable
   include RailsJwtAuth::Confirmable
-end
-```
-
-and create a migration to add confirmation fields to User model:
-
-```ruby
-# example migration
-change_table :users do |t|
-  t.string :email # if it doesn't exist yet
-  t.string :unconfirmed_email
-  t.string :confirmation_token
-  t.datetime :confirmation_sent_at
-  t.datetime :confimed_at
-end
-```
-
-### Mongoid
-
-Include `RailsJwtAuth::Confirmable` module into your User class:
-
-```ruby
-# app/models/user.rb
-class User
-  include Mongoid::Document
-  include RailsJwtAuth::Authenticatable
-  include RailsJwtAuth::Confirmable
-end
-```
-
-This module needs that model has `email` field.
-
-## Recoverable
-
-Resets the user password and sends reset instructions
-
-### ActiveRecord
-
-Include `RailsJwtAuth::Recoverable` module into your User class:
-
-```ruby
-# app/models/user.rb
-class User < ApplicationRecord
-  include RailsJwtAuth::Authenticatable
   include RailsJwtAuth::Recoverable
-end
-```
-
-and create a migration to add recoverable fields to User model:
-
-```ruby
-# example migration
-change_table :users do |t|
-  t.string :reset_password_token
-  t.datetime :reset_password_sent_at
-end
-```
-
-### Mongoid
-
-Include `RailsJwtAuth::Recoverable` module into your User class:
-
-```ruby
-# app/models/user.rb
-class User
-  include Mongoid::Document
-  include RailsJwtAuth::Authenticatable
-  include RailsJwtAuth::Recoverable
-end
-```
-
-## Trackable
-
-Tracks sign in timestamps and IP address.
-
-### ActiveRecord
-
-Include `RailsJwtAuth::Trackable` module into your User class:
-
-```ruby
-# app/models/user.rb
-class User < ApplicationRecord
-  include RailsJwtAuth::Authenticatable
   include RailsJwtAuth::Trackable
-end
-```
-
-and create a migration to add recoverable fields to User model:
+  include RailsJwtAuth::Invitable
 
-```ruby
-# example migration
-change_table :users do |t|
-  t.string :last_sign_in_ip
-  t.datetime :last_sign_in_at
+  validates :email, presence: true,
+                    uniqueness: true,
+                    format: URI::MailTo::EMAIL_REGEXP
 end
 ```
 
-### Mongoid
+Ensure you have executed migrate task: `rails g rails_jwt_auth:migrate` and you have uncomented all modules fields into generated [migration file](https://github.com/rjurado01/rails_jwt_auth/blob/master/lib/generators/templates/migration.rb).
 
-Include `RailsJwtAuth::Trackable` module into your User class:
+**Mongoid**
 
 ```ruby
-# app/models/user.rb
 class User
   include Mongoid::Document
   include RailsJwtAuth::Authenticatable
+  include RailsJwtAuth::Confirmable
+  include RailsJwtAuth::Recoverable
   include RailsJwtAuth::Trackable
-end
-```
-
-## Invitable
-
-This module allows you to invite an user to your application sending an invitation mail with a unique link and complete registration by setting user's password.
-
-### ActiveRecord
-
-Include `RailsJwtAuth::Invitable` module in your User model:
-
-```ruby
-# app/models/user.rb
-class User < ApplicationRecord
-  include RailsJwtAuth::Authenticatable
   include RailsJwtAuth::Invitable
-end
-```
 
-And create the corresponding migration
+  field :email, type: String
 
-```ruby
-# Example migration
-change_table :users do |t|
-  t.string :invitation_token
-  t.datetime :invitation_sent_at
-  t.datetime :invitation_accepted_at
-  t.datetime :invitation_created_at
-end
-```
-
-### Mongoid
-
-Include `RailsJwtAuth::Invitable` module in your User model:
-
-```ruby
-# app/models/user.rb
-class User < ApplicationRecord
-  include RailsJwtAuth::Authenticatable
-  include RailsJwtAuth::Invitable
+  validates :email, presence: true,
+                    uniqueness: true,
+                    format: URI::MailTo::EMAIL_REGEXP
 end
 ```
 
@@ -259,12 +140,12 @@ end
 
 RailsJwtAuth will create some helpers to use inside your controllers.
 
-To use this helpers we need to include `WardenHelper` into `ApplicationController`:
+To use this helpers we need to include `AuthenticableHelper` into `ApplicationController`:
 
 ```ruby
 # app/controllers/application_controller.rb
 class ApplicationController < ActionController::API
-  include RailsJwtAuth::WardenHelper
+  include RailsJwtAuth::AuthenticableHelper
 end
 ```
 
@@ -278,7 +159,20 @@ end
     end
     ```
 
-    This helper expect that token has been into **AUTHORIZATION** header.
+    This helper expect that token has been into **AUTHORIZATION** header.  
+    Raises `RailsJwtAuth::NotAuthorized` exception when it fails.
+
+-   **authenticate**
+
+    Authenticate your controllers:
+
+    ```ruby
+    class MyController < ApplicationController
+      before_action :authenticate
+    end
+    ```
+
+    This helper is like `authenticate!` but it not raises exception
 
 -   **current_user**
 
@@ -292,7 +186,7 @@ end
 
 ### Session
 
-Session api is defined by RailsJwtAuth::SessionsController.
+Session api is defined by `RailsJwtAuth::SessionsController`.
 
 1.  Get session token:
 
@@ -321,7 +215,7 @@ Session api is defined by RailsJwtAuth::SessionsController.
 
 ### Registration
 
-Registration api is defined by RailsJwtAuth::RegistrationsController.
+Registration api is defined by `RailsJwtAuth::RegistrationsController`.
 
 1.  Register user:
 
@@ -350,7 +244,7 @@ Registration api is defined by RailsJwtAuth::RegistrationsController.
 
 ### Confirmation
 
-Confirmation api is defined by RailsJwtAuth::ConfirmationsController.
+Confirmation api is defined by `RailsJwtAuth::ConfirmationsController`.
 
 1.  Confirm user:
 
@@ -380,7 +274,7 @@ Confirmation api is defined by RailsJwtAuth::ConfirmationsController.
 
 ### Password
 
-Password api is defined by RailsJwtAuth::PasswordsController.
+Password api is defined by `RailsJwtAuth::PasswordsController`.
 
 1.  Send reset password email:
 
@@ -414,13 +308,13 @@ Password api is defined by RailsJwtAuth::PasswordsController.
 
 ### Invitations
 
-Invitations api is provided by RailsJwtAuth::InvitationsController.
+Invitations api is provided by `RailsJwtAuth::InvitationsController`.
 
 1.  Create an invitation and send email:
 
 ```js
 {
-  url: host/invitation,
+  url: host/invitations,
   method: POST,
   data: {
     invitation: {
@@ -435,14 +329,12 @@ Invitations api is provided by RailsJwtAuth::InvitationsController.
 
 ```js
 {
-  url: host/invitation,
+  url: host/invitations/:invitation_token,
   method: PUT,
   data: {
-    accept_invitation: {
-      invitation_token: "token",
+    invitation: {
       password: '1234',
-      password_confirmation: '1234',
-      // More fields of your user...
+      password_confirmation: '1234'
     }
   }
 }
@@ -450,22 +342,30 @@ Invitations api is provided by RailsJwtAuth::InvitationsController.
 
 Note: To add more fields, see "Custom strong parameters" below.
 
-## Custom controllers
+## Customize
+
+RailsJwtAuth offers an easy way to customize certain parts.
+
+### Custom controllers
 
 You can overwrite RailsJwtAuth controllers to edit actions, responses,
 permitted parameters...
 
-For example, if we want to change registration strong parameters we
+For example, if we want to call custom method when user is created we need to
 create new registration controller inherited from default controller:
 
 ```ruby
 # app/controllers/registrations_controller.rb
 class RegistrationsController < RailsJwtAuth::RegistrationsController
-  private
+  ...
 
-  def create_params
-    params.require(:user).permit(:email, :name, :surname, :password, :password_confirmation)
+  def create
+    user = RailsJwtAuth.model.new(create_params)
+    user.do_something_custom
+    ...
   end
+
+  ...
 end
 ```
 
@@ -476,7 +376,35 @@ And edit route resource to use it:
 resource :registration, controller: 'registrations', only: [:create, :update, :destroy]
 ```
 
-## Edit user information
+### Custom payload
+
+If you need edit default payload used to generate jwt you can overwrite the method `to_token_payload` into your User class:
+
+```ruby
+class User < ApplicationRecord
+  include RailsJwtAuth::Authenticatable
+  ...
+
+  def to_token_payload(request)
+    {
+      auth_token: regenerate_auth_token,
+      # add here your custom info
+    }
+  end
+end
+```
+
+### Custom responses
+
+You can overwrite `RailsJwtAuth::RenderHelper` to customize controllers responses.
+
+### Custom strong parameters
+
+You can overwrite `RailsJwtAuth::ParamsHelper` to customize controllers strong parameters.
+
+## Examples
+
+### Edit user information
 
 This is a controller example that allows users to edit their `email` and `password`.
 
@@ -500,7 +428,7 @@ class CurrentUserController < ApplicationController
 end
 ```
 
-## Register users with random password
+### Register users with random password
 
 This is a controller example that allows admins to register users with random password and send email to reset it.
 If registration is sucess it will send email to `set_password_url` with reset password token.
@@ -511,7 +439,7 @@ class UsersController < ApplicationController
 
   def create
     user = User.new(create_params)
-    user.set_and_send_password_instructions ? render_204 : render_422(user.errors)
+    user.set_and_send_password_instructions ? render_204 : render_422(user.errors.details)
   end
 
   private
@@ -522,42 +450,33 @@ class UsersController < ApplicationController
 end
 ```
 
-## Custom responses
-
-You can overwrite `RailsJwtAuth::RenderHelper` to customize controllers responses.
-
-## Custom strong parameters
-
-You can overwrite `RailsJwtAuth::ParamsHelper` to customize controllers strong parameters.
-
 ## Testing (rspec)
 
 Require the RailsJwtAuth::Spec::Helpers helper module in `rails_helper.rb`.
 
 ```ruby
-  require 'rails_jwt_auth/spec/helpers'
+require 'rails_jwt_auth/spec_helpers'
+...
+RSpec.configure do |config|
   ...
-  RSpec.configure do |config|
-    ...
-    config.include RailsJwtAuth::Spec::Helpers, :type => :controller
-  end
+  config.include RailsJwtAuth::SpecHelpers, :type => :controller
+end
 ```
 
-And then we can just call sign_in(user) to sign in as a user, or sign_out for examples that have no user signed in. Here's two quick examples:
+And then we can just call sign_in(user) to sign in as a user:
 
 ```ruby
-  describe ExampleController
-    it "blocks unauthenticated access" do
-      sign_out
-      expect { get :index }.to raise_error(RailsJwtAuth::Errors::NotAuthorized)
-    end
+describe ExampleController
+  it "blocks unauthenticated access" do
+    expect { get :index }.to raise_error(RailsJwtAuth::Errors::NotAuthorized)
+  end
 
-    it "allows authenticated access" do
-      sign_in
-      get :index
-      expect(response).to be_success
-    end
+  it "allows authenticated access" do
+    sign_in user
+    get :index
+    expect(response).to be_success
   end
+end
 ```
 
 ## Locales

data/app/controllers/concerns/rails_jwt_auth/authenticable_helper.rb

@@ -0,0 +1,44 @@
+module RailsJwtAuth
+  NotAuthorized = Class.new(StandardError)
+
+  module AuthenticableHelper
+    def current_user
+      @current_user
+    end
+
+    def signed_in?
+      !current_user.nil?
+    end
+
+    def authenticate!
+      begin
+        payload = RailsJwtAuth::JwtManager.decode_from_request(request).first
+      rescue JWT::ExpiredSignature, JWT::VerificationError, JWT::DecodeError
+        unauthorize!
+      end
+
+      if !@current_user = RailsJwtAuth.model.from_token_payload(payload)
+        unauthorize!
+      elsif @current_user.respond_to? :update_tracked_fields!
+        @current_user.update_tracked_fields!(request)
+      end
+    end
+
+    def authenticate
+      begin
+        payload = RailsJwtAuth::JwtManager.decode_from_request(request).first
+        @current_user = RailsJwtAuth.model.from_token_payload(payload)
+      rescue JWT::ExpiredSignature, JWT::VerificationError, JWT::DecodeError
+        @current_user = nil
+      end
+
+      if @current_user&.respond_to? :update_tracked_fields!
+        @current_user.update_tracked_fields!(request)
+      end
+    end
+
+    def unauthorize!
+      raise NotAuthorized
+    end
+  end
+end

data/app/controllers/concerns/rails_jwt_auth/params_helper.rb

@@ -29,9 +29,7 @@ module RailsJwtAuth
     end
 
     def invitation_update_params
-      params.require(:accept_invitation).permit(:invitation_token,
-                                                :password,
-                                                :password_confirmation)
+      params.require(:invitation).permit(:password, :password_confirmation)
     end
   end
 end

data/app/controllers/concerns/rails_jwt_auth/render_helper.rb

@@ -13,6 +13,10 @@ module RailsJwtAuth
       render json: {}, status: 204
     end
 
+    def render_404
+      render json: {}, status: 404
+    end
+
     def render_422(errors)
       render json: {errors: errors}, status: 422
     end

data/app/controllers/rails_jwt_auth/confirmations_controller.rb

@@ -5,20 +5,17 @@ module RailsJwtAuth
 
     def create
       user = RailsJwtAuth.model.where(email: confirmation_create_params[:email]).first
-      return render_422(email: [I18n.t('rails_jwt_auth.errors.not_found')]) unless user
+      return render_422(email: [{error: :not_found}]) unless user
 
-      user.send_confirmation_instructions ? render_204 : render_422(user.errors)
+      user.send_confirmation_instructions ? render_204 : render_422(user.errors.details)
     end
 
     def update
-      if params[:confirmation_token].blank?
-        return render_422(confirmation_token: [I18n.t('rails_jwt_auth.errors.not_found')])
-      end
+      return render_404 unless
+        params[:id] &&
+        (user = RailsJwtAuth.model.where(confirmation_token: params[:id]).first)
 
-      user = RailsJwtAuth.model.where(confirmation_token: params[:confirmation_token]).first
-      return render_422(confirmation_token: [I18n.t('rails_jwt_auth.errors.not_found')]) unless user
-
-      user.confirm! ? render_204 : render_422(user.errors)
+      user.confirm! ? render_204 : render_422(user.errors.details)
     end
   end
 end