RailsJwtAuth

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

This is documentation for version 2.x. If you are using 1.x version use this link

Version 2.x introduces incompatible API changes.

• Installation
• Configuration
• Modules
• ORMs support
• Controller helpers
• Default Controllers API
• Customize
  • Controllers
  • Payload
  • Responses
  • Strong parameters
• Examples
• Testing
• License

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

Only for ActiveRecord, generate migrations:

rails g rails_jwt_auth:migrate

You can edit configuration options into config/initializers/rails_jwt_auth.rb file created by generator.

It's composed of 6 modules:

RailsJwtAuth support both Mongoid and ActiveRecord.

For next examples auth_field_name and email_field_name are configured to use the field email.

ActiveRecord

# app/models/user.rb
class User < ApplicationRecord
  include RailsJwtAuth::Authenticatable
  include RailsJwtAuth::Confirmable
  include RailsJwtAuth::Recoverable
  include RailsJwtAuth::Trackable
  include RailsJwtAuth::Invitable
  include RailsJwtAuth::Lockable

  validates :email, presence: true,
                    uniqueness: true,
                    format: URI::MailTo::EMAIL_REGEXP
end

Ensure you have executed migrate task: rails g rails_jwt_auth:migrate and you have uncomented all modules fields into generated migration file.

Mongoid

class User
  include Mongoid::Document
  include RailsJwtAuth::Authenticatable
  include RailsJwtAuth::Confirmable
  include RailsJwtAuth::Recoverable
  include RailsJwtAuth::Trackable
  include RailsJwtAuth::Invitable
  include RailsJwtAuth::Lockable

  field :email, type: String

  validates :email, presence: true,
                    uniqueness: true,
                    format: URI::MailTo::EMAIL_REGEXP
end

RailsJwtAuth will create some helpers to use inside your controllers.

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

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

• authenticate!

  Authenticate your controllers:

  class MyController < ApplicationController
    before_action :authenticate!
  end

  This helper expect that token has been into AUTHORIZATION header. Raises RailsJwtAuth::NotAuthorized exception when it fails.

• authenticate

  Authenticate your controllers:

  class MyController < ApplicationController
    before_action :authenticate
  end

  This helper is like authenticate! but it not raises exception

• current_user

  Return current signed-in user.

• jwt_payload

  Return current jwt payload.

• signed_in?

  Verify if a user is signed in.

Session api is defined by RailsJwtAuth::SessionsController.

1. Get session token:

{
  url: host/session,
  method: POST,
  data: {
    session: {
      email: 'user@email.com',
      password: '12345678'
    }
  }
}

2. Delete session

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

Registration api is defined by RailsJwtAuth::RegistrationsController.

1. Register user:

{
  url: host/registration,
  method: POST,
  data: {
    user: {
      email: 'user@email.com',
      password: 'xxxx'
    }
  }
}

Profile api let you get/update your user info and is defined by RailsJwtAuth::ProfilesController.

1. Get user info:

{
  url: host/profile,
  method: GET,
  headers: { 'Authorization': 'Bearer auth_token'}
}

2. Update user info:

{
  url: host/profile,
  method: PUT,
  data: {
    profile: {
      name: 'new_name',
    }
  },
  headers: { 'Authorization': 'Bearer auth_token'}
}

3. Update user password:

{
  url: host/profile/password,
  method: PUT,
  data: {
    profile: {
      current_password: 'xxxx',
      password: 'yyyy',
    }
  },
  headers: { 'Authorization': 'Bearer auth_token'}
}

4. Update user email (needs confirmation module):

{
  url: host/profile/email,
  method: PUT,
  data: {
    profile: {
      email: 'new@email.com',
      password: 'xxxx', # email change is protected by password
    }
  },
  headers: { 'Authorization': 'Bearer auth_token'}
}

Confirmation api is defined by RailsJwtAuth::ConfirmationsController.

It is necessary to set a value for confirmations_url option into config/initializers/rails_jwt_auth.rb.

1. Confirm user:

{
  url: host/confirmations/:token,
  method: PUT
  data: {}
}

2. Create confirmation (resend confirmation email):

{
  url: host/confirmations,
  method: POST,
  data: {
    confirmation: {
      email: 'user@example.com'
    }
  }
}

Reset password api is defined by RailsJwtAuth::ResetPasswordsController.

1. Send reset password email (init reset password process):

{
  url: host/reset_passwords,
  method: POST,
  data: {
    reset_password: {
      email: 'user@example.com'
    }
  }
}

2. Check token validation:

Used to verify a token and show an alert in your website before the new password is set.

{
  url: host/reset_passwords/:token,
  method: GET
}

3. Update password:

{
  url: host/reset_passwords/:token,
  method: PUT,
  data: {
    reset_password: {
      password: '1234',
      password_confirmation: '1234'
    }
  }
}

Invitations api is provided by RailsJwtAuth::InvitationsController.

1. Create an invitation and send email:

{
  url: host/invitations,
  method: POST,
  data: {
    invitation: {
      email: 'user@example.com',
      // More fields of your user
    }
  }
}

2. Check token validation:

Used to verify token and show an alert in your web before invitation data is completed.

{
  url: host/invitations/:token,
  method: GET
}

3. 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.

Unlock api is provided by RailsJwtAuth::UnlocksController.

1. Unlock user:

{
  url: host/unlock_accounts/:unlock_token,
  method: PUT,
  data: {}
}

RailsJwtAuth offers an easy way to customize certain parts.

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

For example, if we want to call custom method when user is created we need to create new registration controller inherited from default controller:

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

  def create
    user = RailsJwtAuth.model.new(create_params)
    user.do_something_custom
    ...
  end

  ...
end

And edit route resource to use it:

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

If you need edit default payload used to generate jwt you can overwrite the method to_token_payload into your User class:

class User < ApplicationRecord
  include RailsJwtAuth::Authenticatable
  ...

  def to_token_payload(request)
    {
      auth_token: auth_tokens.last,
      # add here your custom info
    }
  end
end

You can overwrite RailsJwtAuth::RenderHelper to customize controllers responses without need to overwrite each controller.

Example:

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

module RailsJwtAuth
  module RenderHelper
    private

    def render_session(jwt, user)
      # add custom field to session response
      render json: {session: {jwt: jwt, my_custom_field: user.custom_field}}, status: 201
    end

  ...
end

You can overwrite RailsJwtAuth::ParamsHelper to customize controllers strong parameters without need to overwrite each controller.

Example:

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

module RailsJwtAuth
  module ParamsHelper
    private

    def registration_create_params
      # change root to :data
      params.require(:data).permit(:email, :password, :password_confirmation)
    end

  ...
end

To use a custom mailer, create a class that extends RailsJwtAuth::Mailer, like this:

class CustomMailer < RailsJwtAuth::Mailer
  def confirmation_instructions(user)
    # set your custom code here

    super
  end
end

Then, in your config/initializers/rails_jwt_auth.rb, set config.mailer to "CustomMailer".

If you only need to customize templates, overwrite files in 'app/views/rails_jwt_auth/mailer'

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

require 'rails_jwt_auth/spec_helpers'
...
RSpec.configure do |config|
  ...
  config.include RailsJwtAuth::SpecHelpers, type: :controller
end

And then we can just call sign_in(user) to sign in as a user:

describe ExampleController
  it 'blocks unauthenticated access' do
    expect { get :index }.to raise_error(RailsJwtAuth::NotAuthorized)
  end

  it 'allows authenticated access' do
    sign_in user
    get :index
    expect(response).to be_success
  end
end

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

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