Minato::Rails::Auth

Minato Rails Auth is a library designed to be an authentication layer in Rails applications. It has a JWT module, that can be included in Rails Controllers to authenticate requests. And has a RSpec shared contexts, to simplify authentication in automated tests.

Installation

The recommended installation way is by Gem or Bundler:

By Gem

$ gem install minato-rails-auth

By Bundler

$ bundle add minato-rails-auth

Or just add the following line on your Gemfile file:

gem 'minato-rails-auth'

And you can specify the version:

gem 'minato-rails-auth', '~> 0.1.0'

Configuration

To configure the Minato Rails Auth lib on your Rails application, is necessary to follow the steps:

1. Create a configuration file:

   [rails-app]/config/initializers/minato_rails_auth.rb
   

2. Add the following content in the file:

   require 'minato/rails/auth'
   
   Minato::Rails::Auth.configure do |conf|
       conf.jwt.issuer = Settings.api.secure.issuer
       conf.jwt.jwks_uri = Settings.api.secure.jwks_uri
   end
   

- Each option specs:

    - `conf.jwt`  
        - stores all jwt configuration
    - `conf.jwt.issuer` 
        - example: 'http://localhost'  
        - is the jwt issuer, when the system uses Ory, it's the gateway host
    - `conf.jwt.jwks_uri` 
        - example: 'http://localhost:4456/.well-known/jwks.json' 
        - is the jwks obtetion uri, when the system uses Ory, it's the direct gateway host
    - `conf.jwt.jwks` 
        - default: nil   
        - this is the jwks data, if this is specified it will not be necessary the conf.jwt.jwks_uri attribute
    - `conf.jwt.algorithms` 
        - default:  'RS256'
        - alghorithm used to decode the jwt
    - `conf.jwt.verify_iss` 
        - default:  true   
        - this specify if the issuer should be checked
    - `conf.jwt.verify_token_signature` 
        - default: true   
        - this specify if the token signature should be checked
    - `conf.jwt.hmac_secret` 
        - default: nil
        - hmac secret, is necessary only in HMAC algorithms
    - `conf.jwt.additional_params` 
        - default: {}
        - is JWT.decode additional options
        - docs: https://github.com/jwt/ruby-jwt/blob/main/README.md

And now, the library was configured in your Rails application.

Usage

Auth system

To add the JWT authentication system in your Rails application, just follow the steps:

1. Include the JWT module in your ApplicationController:

   class ApplicationController < ActionController::API
       include Minato::Rails::Auth::JWT
   end
   

2. Now it is available the method authenticate_request! in your controllers, and you can call it when you want to auth a controller:

   class FooController < ApplicationController
       before_action :authenticate_request!
   end
   

3. Now the variable current_user is availabe in your controller, containing the following methods:

• .machine?

  • This will return a boolean value that will tell you if the client is a machine or not

• .human?

  • This works like the .machine? method, but tells you if the client is human.

• .session

  • This returns a object containing the JWT payload, if the client is human.

• .machine

  • This returns a string with the machine name, when the client is a machine.

Testing tools

The Minato Rails Auth makes available the RSpec shared contexts, to make it available you can include the module in your [rails-app]/spec/spec_helper.rb:

require 'minato/rails/auth/spec'

And now it will be available the following shared contexts, that you can use following the docs:

• with jwt authentication:
  • Just create a jwt with empty payload. To set the payload you should create a jwt_payload variable using let.
• with human jwt authentication:
  • Creates a jwt with human payload. You set the user attributes with variables jwt_email, jwt_account_id, jwt_session_id, jwt_identity_id and jwt_payload.
• with machine jwt authentication:
  • Creates a jwt with machine payload. You can set the machine name with the variable jwt_machine.
• with missing jwt authentication:
  • Raise a ::JWT::VerificationError, simulating when the user is not authenticated.

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 GitLab at https://gitlab.com/ferreri/minato/minato-rails-auth.