Rottweiler
Rottweiler is a Ruby gem that provides functionality for verifying JSON Web Tokens (JWTs). It allows you to easily verify the authenticity and integrity of JWTs, making it an essential tool for applications that rely on JWT-based authentication and authorization. Rottweiler's intuitive interface and comprehensive documentation make it easy to use and integrate into new or existing Rails projects.
Requirements
- Ruby >= 2.7
- Rails >= 5.x
Installation
Install the gem and add to the application's Gemfile by executing:
$ bundle add rottweiler
If bundler is not being used to manage dependencies, install the gem by executing:
$ gem install rottweiler
Configuration
Before start using Rottweiler gem you might need to configure it to fit your application. First of all you need to choose the appropriate cryptographic algorithm which is used for JWT generation and verification. The most common are HMAC and RSA, but there're also other available algorithms. You can find more about available algorithms in the documentation of JWT gem.
To configure Rottwiler gem you should add a new initializer file to config/initializers/rottweiler.rb
and set Rottweiler.config
to configure it for your application.
Below you can find an example of how to configure Rottweiler for verification of JWTs using the RSA algorithm:
# frozen_string_literal: true
require 'rottweiler'
Rottweiler.config do |config|
# Here an example of configuration for JWT generated with RSA algorithm (RSA 256)
config.jwt.algorithm = 'RS256'
# Decode key must be a OpenSSL::PKey::RSA when RSA algorithm is used
config.jwt.decode_key = OpenSSL::PKey::RSA.new(ENV['JWT_PUBLIC_KEY'])
end
JWT header and param
By default Rottweiler will look for JWT token in headers['Authorization']
header and params[:token]
, but if you need to use a different header or param, you can specify which header and parameter to use for JWT lookup:
Rottweiler.config do |config|
config.token_header = 'X-JWT-Token'
# To search for JWT token in `params[:_jwt]`
config.token_param = [:_jwt]
# To search for JWT token in `params[:secrets][:jwt]`
config.token_param = [:secrets, :jwt]
end
Unauthorized status code
If for some reason you don't want Rottweiler to respond with 401 Unauthorized
on authentication failure, you can customize the status code by setting:
Rottweiler.config.unauthorized_status = :bad_request
# or
Rottweiler.config do |config|
config.unauthorized_status = 403
end
Usage
To start using Rottweiler in your controllers you just need to include Rottweiler::Authentication
module in your controllers:
class ApplicationController < ActionController::API
include Rottweiler::Authentication
# If you want to run some specific code on authentication failure, you can do it
# by setting on_authentication_failed callback
on_authentication_failed do |errors|
# your code here
end
# If you need to run some specific code on authentication success, you can do it
# by setting on_authentication_success callback
on_authentication_success do |data|
# your code here
end
end
Skip authentication
Sometimes you might want to skip authentication for specific controllers or actions. For doing so you can use skip_authentication!
helper inside your controller:
class PublicController < ApplicationController
# Skip authentication for all the actions in this controller (make it public).
skip_authentication!
end
If you want to skip authentication only for specific actions, you can pass the name of the actions for which you want to skip authentication with :only
option:
class CustomController < ApplicationController
skip_authentication! only: %i[status public_action]
# Authentication required
def index; end
# Skip authentication
def status; end
# Skip authentication
def public_action; end
end
You can also proceed in an opposite direction, by skipping authentication for all the actions except the actions specified with :except
option:
class StrangeController < ApplicationController
skip_authentication! except: %i[private_action]
# Skip authentication
def index; end
# Authentication required
def private_action; end
end
NOTE: Rottweiler::Authentication
have to be included before other authorization modules, in order to perform authentication checks before authorization.
Development
After checking out the repo, run bin/setup
to install dependencies. Then, run rake spec
to run the tests. You can also run bin/console
for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run bundle exec rake install
. To release a new version, update the version number in version.rb
, and then run bundle exec rake release
, which will create a git tag for the version, push git commits and the created tag, and push the .gem
file to rubygems.org.
Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/demetra-it/rottweiler. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.
License
The gem is available as open source under the terms of the MIT License.
Code of Conduct
Everyone interacting in the Rottweiler project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.