knock

Seamless JWT authentication for Rails API

Description

Knock is an authentication solution for Rails API-only application based on JSON Web Tokens.

What are JSON Web Tokens?

Why should I use this?

• It's lightweight.
• It's tailored for Rails API-only application.
• It's stateless.
• It works out of the box with Auth0.

Is this gem going to be maintained?

Yes.

Upcoming features & improvements

• Easy way to authenticate multiple user types (User, Admin, ...)
• Remove ActiveRecord dependency

Really want some feature? Don't hesitate to open an issue :)

Getting Started

Installation

Add this line to your application's Gemfile:

gem 'knock'

And then execute:

$ bundle install

Finally, run the install generator:

$ rails generate knock:install

It will create the following initializer config/initializers/knock.rb. This file contains all the informations about the existing configuration options.

Requirements

Knock makes one assumption about your user model:

It must have an authenticate method, similar to the one added by has_secure_password.

class User < ActiveRecord::Base
  has_secure_password
end

Using has_secure_password is recommended, but you don't have to as long as your user model implements an authenticate instance method with the same behavior.

Usage

Mount the Knock::Engine in your config/routes.rb

Rails.application.routes.draw do
  mount Knock::Engine => "/knock"

  # your routes ...
end

Then include the Knock::Authenticable module in your ApplicationController

class ApplicationController < ActionController::API
  include Knock::Authenticable
end

You can now protect your resources by adding the authenticate before_action to your controllers like this:

class MyResourcesController < ApplicationController
  before_action :authenticate

  def index
    # etc...
  end

  # etc...
end

If no valid token is passed with the request, Knock will respond with:

head :unauthorized

Authenticating from a web or mobile application:

Example request to get a token from your API:

POST /knock/auth_token
{"auth": {"email": "[email protected]", "password": "secret"}}

Example response from the API:

201 Created
{"jwt": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9"}

To make an authenticated request to your API, you need to pass the token in the request header:

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9
GET /my_resources

NB: HTTPS should always be enabled when sending a password or token in your request.

Authenticated tests

To authenticate within your tests:

1. Create a valid token
2. Pass it in your request

e.g.

class MyResourcesControllerTest < ActionController::TestCase
  def authenticate
    token = Knock::AuthToken.new(payload: { sub: users(:one).id }).token
    request.env['HTTP_AUTHORIZATION'] = "bearer #{token}"
  end

  setup do
    authenticate
  end

  it 'responds successfully' do
    get :index
    assert_response :success
  end
end

CORS

To enable cross-origin resource sharing, check out the rack-cors gem.

Related links

• 10 things you should know about tokens

Contributing

1. Fork it ( https://github.com/nsarno/knock/fork )
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

License

MIT