SecureApi
SecureApi is a Tiny JWT-based Authenticaton framework for RoR API's
Table of Contents
Installation
Add this line to your application's Gemfile:
gem 'secure_api'
And then execute:
$ bundle install
Or install it yourself as:
$ gem install secure_api
Usage
Initializer and Migration
Before using the gem you must run the SecureApi generator:
$ rails g secure_api:install
This will create an initializer at config/initializers/secure_api.rb
and a migration at db/migrate/secure_api_migration.rb
.
Don't forget to migrate your db before continuing, in order to create the secure_api_tokens
table, you will also need to update the initializer's required fields.
Usage requirements
In order for the gem to work, your User
class must have email
and password
fields, you can customize them in the initializer.
in order to authenticate requests you must add a callback in the main controller of your application or in any other controller where you need SecureApi's functionality:
class ApplicationController < ActionController::Base
before_action :authenticate_request!
# skip_before_action :authenticate_request! ## use this to skip authentication on specific requests
end
When making an authenticated requests, the Authorization
header should be included, with your token.
In addition to authenticating the requests, SecureApi mounts a number of routes at /user
, detailed documentation can be found here
Extra
User response
SecureApi controller responses that return a user, default to this JSON response:
{
"user": {
"USER"
},
"token": {
"token": "String",
"expiration": "ISO8601"
}
}
The USER defaults to the user instance without password and timestamps, this can be customized by creating an instance method in the user class named secure_api_resonse
that returns a hash of attributes:
class User < ApplicationRecord
def full_name
first_name + last_name
end
def secure_api_response
{
full_name: full_name
}
end
end
Helpers
SecureApi provides some additional helpers.
To facilitate testing the auth_headers
method is available in the Minitest
suite:
require 'test_helper'
class MyControllerTest < ActionDispatch::IntegrationTest
test 'some url' do
user = User.create
headers = auth_headers(user)
# headers is a hash, you can add any key you want
headers[:another_header] = 'Something'
get some_url, headers: headers
end
end
If your project does not use Minitest
, you must include these modules into your test suite of choice:
SecureApi::Helpers::Test, SecureApi
In addition there is authenticate_cable_request!
to authenticate ActionCable connections, given the token is included in the params (wss://MY_OWN_DOMAIN/cable?Authorization=TOKEN
):
module ApplicationCable
class Connection < ActionCable::Connection::Base
identified_by :current_user
def connect
self.current_user = find_verified_user
end
private
def find_verified_user
# authenticate_cable_request! returns the user, or false
authenticate_cable_request! || reject_unauthorized_connection
end
end
end
Secure token
The secure_token
method is avilabe to the user instance, which returns a SecureApi::Token
instance:
user = User.first
user.secure_token
# <SecureApi::Token id: 1, token: "eyJhbGciOiJIUzI1NiJ9.eyJkYXRhIjoxLCJleHAiOjE2MDYxM...", exp_date: "2020-11-23 13:26:13", resource_type: "User", resource_id: 1, created_at: "2020-11-22 13:26:13", updated_at: "2020-11-22 13:26:13">
Development
After checking out the repo, run bundle install
to install dependencies. You can also run rails s
or rails c
to run the server (Dummy app) or the console.
Testing
To test the gem simply run rails test
from the root of the library folder.
Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/davidmetta/secure_api.
License
The gem is available as open source under the terms of the MIT License.