RailsJwtAuth

Build Status

Rails-API authentication solution based on Warden and JWT and inspired by Devise.

Installation

Add this line to your application's Gemfile:

gem 'rails_jwt_auth'

And then execute:

$ bundle

Or install it yourself as:

$ gem install rails_jwt_auth

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
accept_invitation_url	invitations_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:

# app/models/user.rb
class User < ApplicationRecord
  include RailsJwtAuth::Authenticatable
end

and create a migration to add authenticable fields to User model:

# 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:

# app/models/user.rb
class User
  include Mongoid::Document
  include RailsJwtAuth::Authenticatable
end

Fields are added automatically.

Confirmable

Sends emails with confirmation instructions and verifies whether an account is already confirmed during sign in.

ActiveRecord

Include RailsJwtAuth::Confirmable module into your User class:

# 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:

# 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 :confirmed_at
end

Mongoid

Include RailsJwtAuth::Confirmable module into your User class:

# 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:

# 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:

# 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:

# 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:

# 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:

# example migration
change_table :users do |t|
  t.string :last_sign_in_ip
  t.datetime :last_sign_in_at
end

Mongoid

Include RailsJwtAuth::Trackable module into your User class:

# app/models/user.rb
class User
  include Mongoid::Document
  include RailsJwtAuth::Authenticatable
  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:

# app/models/user.rb
class User < ApplicationRecord
  include RailsJwtAuth::Authenticatable
  include RailsJwtAuth::Invitable
end

And create the corresponding migration

# 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:

# app/models/user.rb
class User < ApplicationRecord
  include RailsJwtAuth::Authenticatable
  include RailsJwtAuth::Invitable
end

Controller helpers

RailsJwtAuth will create some helpers to use inside your controllers.

To use this helpers we need to include WardenHelper into ApplicationController:

# app/controllers/application_controller.rb
class ApplicationController < ActionController::API
  include RailsJwtAuth::WardenHelper
end

authenticate!

Authenticate your controllers:
```
class MyController < ApplicationController
  before_action :authenticate!
end
```
This helper expect that token has been into AUTHORIZATION header.
current_user

Return current signed-in user.
signed_in?

Verify if a user is signed in.

Default Controllers API

Session

Session api is defined by RailsJwtAuth::SessionsController.

Get session token:

{
  url: host/session,
  method: POST,
  data: {
    session: {
      email: "[email protected]",
      password: "12345678"
    }
  }
}

Delete session

{
  url: host/session,
  method: DELETE,
  headers: { 'Authorization': 'Bearer auth_token'}
}

Registration

Registration api is defined by RailsJwtAuth::RegistrationsController.

{
  url: host/registration,
  method: POST,
  data: {
    user: {
      email: "[email protected]",
      password: "12345678"
    }
  }
}

Delete user:

{
  url: host/registration,
  method: DELETE,
  headers: { 'Authorization': 'Bearer auth_token'}
}

Confirmation

Confirmation api is defined by RailsJwtAuth::ConfirmationsController.

Confirm user:

{
  url: host/confirmation,
  method: PUT
  data: {
    confirmation_token: "token"
  }
}

Create confirmation (resend confirmation email):

{
  url: host/confirmation,
  method: POST,
  data: {
    confirmation: {
      email: "[email protected]"
    }
  }
}

Password

Password api is defined by RailsJwtAuth::PasswordsController.

Send reset password email:

{
  url: host/password,
  method: POST,
  data: {
    password: {
      email: "[email protected]"
    }
  }
}

Update password:

{
  url: host/password,
  method: PUT,
  data: {
    reset_password_token: "token",
    password: {
      password: '1234',
      password_confirmation: '1234'
    }
  }
}

Invitations

Invitations api is provided by RailsJwtAuth::InvitationsController.

Create an invitation and send email:

{
  url: host/invitations,
  method: POST,
  data: {
    invitation: {
      email: "[email protected]",
      // More fields of your user
    }
  }
}

Accept an invitation:

{
  url: host/invitations/:invitation_token,
  method: PUT,
  data: {
    invitation: {
      password: '1234',
      password_confirmation: '1234'
    }
  }
}

Note: To add more fields, see "Custom strong parameters" below.

Custom controllers

You can overwrite RailsJwtAuth controllers to edit actions, responses, permitted parameters...

For example, if we want to change registration strong parameters we create new registration controller inherited from default controller:

# app/controllers/registrations_controller.rb
class RegistrationsController < RailsJwtAuth::RegistrationsController
  private

  def create_params
    params.require(:user).permit(:email, :name, :surname, :password, :password_confirmation)
  end
end

And edit route resource to use it:

# config/routes.rb
resource :registration, controller: 'registrations', only: [:create, :update, :destroy]

Edit user information

This is a controller example that allows users to edit their email and password.

class CurrentUserController < ApplicationController
  before_action 'authenticate!'

  def update
    if update_params[:password]
      current_user.update_with_password(update_params)
    else
      current_user.update_attributes(update_params)
    end
  end

  private

  def update_params
    params.require(:user).permit(:email, :current_password, :password)
  end
end

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.

class UsersController < ApplicationController
  before_action 'authenticate!'

  def create
    user = User.new(create_params)
    user.set_and_send_password_instructions ? render_204 : render_422(user.errors)
  end

  private

  def create_params
    params.require(:user).permit(:email)
  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.

Testing (rspec)

Require the RailsJwtAuth::Spec::Helpers helper module in rails_helper.rb.

  require 'rails_jwt_auth/spec/helpers'
  ...
  RSpec.configure do |config|
    ...
    config.include RailsJwtAuth::Spec::Helpers, :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:

  describe ExampleController
    it "blocks unauthenticated access" do
      sign_out
      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
  end

Locales

Copy config/locales/en.yml into your project config/locales folder and edit it.

License

The gem is available as open source under the terms of the MIT License.