This project is not being maintained and I don't recommend using it in its current form. As an alternative, I recommend using the jwt gem directly.
Seamless JWT authentication for Rails API
Knock is an authentication solution for Rails API-only application based on JSON Web Tokens.
Add this line to your application's Gemfile:
gem 'knock'Then execute:
$ bundle install
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
endUsing 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.
Include the Knock::Authenticable module in your ApplicationController
class ApplicationController < ActionController::API
include Knock::Authenticable
endYou can now protect your resources by calling authenticate_user as a before_action
inside your controllers:
class SecuredController < ApplicationController
before_action :authenticate_user
def index
# etc...
end
# etc...
endYou can access the current user in your controller with current_user.
If no valid token is passed with the request, Knock will respond with:
head :unauthorized
You can modify this behaviour by overriding unauthorized_entity in your controller.
You also have access directly to current_user which will try to authenticate or return nil:
def index
if current_user
# do something
else
# do something else
end
endNote: the authenticate_user method uses the current_user method. Overwriting current_user may cause unexpected behaviour.
You can do the exact same thing for any entity. E.g. for Admin, use authenticate_admin and current_admin instead.
If you're using a namespaced model, Knock won't be able to infer it automatically from the method name. Instead you can use authenticate_for directly like this:
class ApplicationController < ActionController::Base
include Knock::Authenticable
private
def authenticate_v1_user
authenticate_for V1::User
end
endclass SecuredController < ApplicationController
before_action :authenticate_v1_user
endThen you get the current user by calling current_v1_user instead of current_user.
The entity model (e.g. User) can implement specific methods to provide
customization over different parts of the authentication process.
- Find the entity when creating the token (when signing in)
By default, Knock tries to find the entity by email. If you want to modify this
behaviour, implement within your entity model a class method from_token_request
that takes the request in argument.
E.g.
class User < ActiveRecord::Base
def self.from_token_request request
# Returns a valid user, `nil` or raise `Knock.not_found_exception_class_name`
# e.g.
# email = request.params["auth"] && request.params["auth"]["email"]
# self.find_by email: email
end
end- Find the authenticated entity from the token payload (when authenticating a request)
By default, Knock assumes the payload as a subject (sub) claim containing the entity's id
and calls find on the model. If you want to modify this behaviour, implement within
your entity model a class method from_token_payload that takes the
payload in argument.
E.g.
class User < ActiveRecord::Base
def self.from_token_payload payload
# Returns a valid user, `nil` or raise
# e.g.
# self.find payload["sub"]
end
end- Modify the token payload
By default the token payload contains the entity's id inside the subject (sub) claim.
If you want to modify this behaviour, implement within your entity model an instance method
to_token_payload that returns a hash representing the payload.
E.g.
class User < ActiveRecord::Base
def to_token_payload
# Returns the payload as a hash
end
end- Token Lifetime
By default the generated tokens will be valid, after generated, for 1 day. You can change it in the Knock configuration file (config/knock.rb), setting the desired lifetime:
E.g.
Knock.token_lifetime = 3.hoursIf you are generating tokens for more than one entity, you can pass each lifetime in a hash, using the entities class names as keys, like:
E.g.
# How long before a token is expired. If nil is provided,
# token will last forever.
Knock.token_lifetime = {
user: 1.day
admin: 30.minutes
}Read lib/knock.rb to learn about all the possible configuration options and their default values.
You can create an initializer like in the example below:
Inside config/initializers/knock.rb
Knock.setup do |config|
config.token_lifetime = 1.hour
# For Auth0
config.token_audience = -> { Rails.application.secrets.auth0_client_id }
config.token_secret_signature_key = -> { JWT.base64url_decode Rails.application.secrets.auth0_client_secret }
endExample request to get a token from your API:
POST /user_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 via the request header:
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9
GET /my_resources
Knock responds with a 404 Not Found when the user cannot be found or the password is invalid. This is a security best practice to avoid giving away information about the existence or not of a particular user.
NB: HTTPS should always be enabled when sending a password or token in your request.
To authenticate within your tests:
- Create a valid token
- Pass it in your request
e.g.
class SecuredResourcesControllerTest < ActionDispatch::IntegrationTest
def authenticated_header
token = Knock::AuthToken.new(payload: { sub: users(:one).id }).token
{
'Authorization': "Bearer #{token}"
}
end
it 'responds successfully' do
get secured_resources_url, headers: authenticated_header
assert_response :success
end
endIf no ActiveRecord is used, then you will need to specify what Exception will be used when the user is not found with the given credentials.
Knock.setup do |config|
# Exception Class
# ---------------
#
# Configure the Exception to be used (raised and rescued) for User Not Found.
# note: change this if ActiveRecord is not being used.
#
# Default:
config.not_found_exception_class_name = 'MyCustomException'
endThe JWT spec supports different kind of cryptographic signing algorithms.
You can set token_signature_algorithm to use the one you want in the
initializer or do nothing and use the default one (HS256).
You can specify any of the algorithms supported by the jwt gem.
If the algorithm you use requires a public key, you also need to set
token_public_key in the initializer.
To enable cross-origin resource sharing, check out the rack-cors gem.
- Fork it ( https://github.com/nsarno/knock/fork )
- Create your feature branch (
git checkout -b my-new-feature) - Commit your changes (
git commit -am 'Add some feature') - Push to the branch (
git push origin my-new-feature) - Create a new Pull Request
MIT
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent