slots-jwt 0.0.4

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3d6628ed470d9b4cec56322b2f5fb64ec3680eea78f133f7914390415e610492
+  data.tar.gz: 9f6e1a6276ebbaa24db8332423d47ecb9f630b3d68fe0a0d034bcd3140d2ecd2
+SHA512:
+  metadata.gz: 54d442b78eb5450335975c2b913029f236255e1adbb8a796afb261a3f67fe99c3838f69d5fa72cfe65b4eecf94d666c3ff797d81770072edad33270a5e63e698
+  data.tar.gz: 15aafdcc9d1e8d6a20e4d7bbf4911d44aa60baa9b73b96dc03cb05f36738c65a64ed1b3e51e3e616ffe64f8617b4016a9685e034ed9b3cd293718638a0b6f5e0

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2018 Jonathon Gardner
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,214 @@
+# Slots
+Token authentication solution for rails 5 API. Slots use JSON Web Tokens for authentication and database session for remembering signed in users.
+
+## Getting started
+Slots 0.0.4 works with Rails 5. Add this line to your application's Gemfile:
+
+```ruby
+gem 'slots'
+```
+Then run `bundle install`.
+
+Next create the slots config file and add the routes using:
+```console
+$ rails generate slots:install
+```
+This will create `config/initializers/slots.rb` and add the following line to `config/routes.rb`
+```ruby
+mount Slots::Engine => "/auth"
+```
+This will mount all slot routes to `auth/*`.
+
+Next, the following command can be used to generate the authentication model.
+```console
+$ rails generate slots:model User
+```
+Any rails accepted name can be used for the model but `User` is the expected default. If a different name is used for the authentication model than it must be defined in the config file for slots (this will automatically be done if the `generate slots` is used).
+config/initializers/slots.rb
+```ruby
+Slots.configure do |config|
+  ...
+  config.authentication_model = 'AnotherModel'
+  ...
+end
+```
+If you are using a model that has already been created than just add the following with the desired plugins:
+```ruby
+class MyModel < ApplicationRecord
+  ...
+  slots :database_authentication
+  end
+  ...
+end
+```
+And make sure the table has the necessary columns (if using the default setup, that would be email and password_digest). If other methods are desired for authentication like LDAP do not pass `:database_authentication` to slots and add a method `authenticate(password)` in the model. Database Authentication stores a password in the database using Secure Password.
+
+Tokens are expected to be in the header of the request in the following format:
+```ruby
+'authorization' => 'Bearer token=TOKEN'
+```
+They are also returned in the header in the same way.
+
+## Usage
+To require a user to be authenticated the following methods can be used in the controller.
+```ruby
+require_login!
+```
+
+`require_login!` takes the usual options of a `before_action` (`only`, `except`) and also `load_user`.
+The `current_user` is populated with the information from JWT. This can be a problem because the info in the JWT could become out of date; it would not update until the token has expired. If you want to force the user to be reloaded from the database you can call `require_user_load!` or pass `load_user: true` to `require_login!`. Default is not to load the user to help keep the JWT stateless.
+
+NOTE: Before changes can be made to `current_user` user must be reloaded. This can be done using the above method or by `current_user.valid_in_database?`.
+
+WARNING: do not call  `require_login!` twice in one controller. For example if one route, you want with load_user and one without don't do the following, because only the last one will be done.
+```ruby
+require_login! only: [:action1]
+require_login! load_user: true, only: [:action2]
+```
+This is a limitation on rails `before_action`. In the example above only `action2` will require a login. Instead use the following:
+```ruby
+require_login! only: [:action1, :action2]
+require_user_load! only: [:action2]
+```
+
+These method will raise a `Slots::InvalidToken` Error. This error can be caught using the helper method `catch_invalid_token`. If nothing is passed the following will be returned with a unauthorized status:
+```
+  'errors' => {
+    'authentication' => ['invalid or missing token']
+  }
+```
+A custom message or status can be returned using the following:
+```ruby
+catch_invalid_token(response: {my_message: 'Some custom message'}, status: :im_a_teapot)
+```
+It is sometimes easier to always require login and explicitly ignore it when needed. To do this add `require_login!` and `catch_invalid_token` to the `ApplicationController`. Then on routes that you do not want to require authentication use the following method.
+```ruby
+ignore_login!
+```
+This takes all the same options as `require_login!`.
+
+To not allow a user to sign in the following can be used in the authentication model:
+```ruby
+class User < ApplicationRecord
+  slots :database_authentication
+
+  reject_new_token do
+    !self.approved # Return true if they cannot get a new token
+  end
+end
+```
+This will not allow unapproved users to get a new token (login or update_session_token).
+
+## Authorization
+Sometimes when dealing with authentication you also need authorization. While in most cases you should use another gem to handle this, if it is simple (like an admin or approved user) slots can handle it. Just add the following:
+```ruby
+class SomeController < ApplicationController
+  ...
+
+  reject_token do
+    !current_user.admin # Return true to not allow to see resource
+  end
+
+  def some_special_action_that_you_must_be_admin_for
+  end
+
+  ...
+end
+```
+`reject_token` take the same params as rails `before_action`. This will raise a `Slots::AccessDenied` Error for users not approved for the routes in this controller. To catch this error you can use the helper method `catch_access_denied`. If nothing is passed the following will be returned with a forbidden status:
+```
+  'errors' => {
+    'authorization' => ["can't access"]
+  }
+```
+A custom message or status can be returned using the following:
+```ruby
+catch_invalid_token(response: {my_message: 'Some custom message'}, status: :im_a_teapot)
+```
+NOTE: If you want the token to be rejected for all tokens (i.e. require all routes to have an approved user) add the above to the `ApplicationController`. You can then also add more specific requirements to a controller by also adding it in the controller like requiring an admin. To ignore a `reject_token` use `skip_callback!` which again takes the same params as `before_action`.
+
+## Sessions
+If sessions are allowed (`session_lifetime` is not nil) `session: true` can be passed along when signing in to receive a session token. A session tokens has a the session id in the payload of the JWT. This is kept in the JWT so the front-end only has to track one token. There are two ways to get a new token after a session token has expired.
+  1. The first is by sending the token to `MOUNT_LOCATION/update_session_token`. This method will always return a new token even if the token has not expired. This will return the same information as `sign_in` (user information and with the token in the header).
+  2. The second is by adding `update_expired_session_tokens!` (which takes the usual options of a `before_action` `only`, `except`, etc). This method will allow any route to take a valid expired token and it will return a new token in the headers with usual route information in the body. A token will only be returned in the header if the token passed is expired. When using this method a problem can arise were two request are made at the same time with the same expired token. The first request processed would return a new token but the second request would fail because the expired token does not match the information of the session anymore (since it was just updated) and would therefore return unauthorized. To fix this there is a previous jwt lifetime (which defaults to 5 seconds and can be changed in the config). This will allow the previous token to be valid for 5 seconds (or whatever is set in config). If a previous token is sent that is within the previous lifetime it will be a valid token but it will not return a new token (since one was already returned in the earlier request).
+
+## Testing
+
+By adding `include Slots::Tests` the following methods can be used within minitest, `authorized_get`, `authorized_post`, `authorized_put`, `authorized_patch` and `authorized_delete`. These methods are the same as the usual `get`, ... `delete` but the first param in the method must be the user. For example:
+```ruby
+authorized_get users(:some_user), some_route_url, params: {one: 'something', ...}, headers: {'info' => 'someInfo', ...}
+```
+
+## Configurations
+Default configuration:
+```ruby
+Slots.configure do |config|
+  config.logins = :email
+  config.login_regex_validations = true
+  config.authentication_model = 'User'
+  config.secret = ENV['SLOT_SECRET']
+  config.token_lifetime = 1.hour
+  config.session_lifetime = 2.weeks
+  config.previous_jwt_lifetime = 5.seconds
+  config.secret_yaml = false
+end
+```
+- `logins`: this is the column to use for logins. It must be a symbol or a hash with symbol regex pair where the symbol is the column and the regex is when to use it (hash order matters). An example might is
+```ruby
+  config.logins = {email: /@/, username: //}
+```
+This would make it if a value for login is passed and it has an @ symbol than check the email column otherwise check the username column.
+- `login_regex_validations`: This will require the column for login to match the regex passed and no others before it. So for the example above it would not allow username to contain '@'.
+- `authentication_model`: The model used for authentication.
+- `secret`: This is the secret used to encode the JWS.
+- `token_lifetime`: This is the lifetime of the token, it should be kept short (less than one hour).
+- `session_lifetime`: This is the session lifetime, set to nil if you do not want to use sessions.
+- `previous_jwt_lifetime`: This is the lifetime of the previous_jwt, for example if two request are sent with an expired token the first one will update the session making the second one invalid (because the iat doesn't match the session). Therefore this is to gives time for all following request to use the new token.
+- `secret_yaml`: Set to true to load secret from `config/slots_secrets.yml`. [More](Secret Yaml)
+
+### Secret Yaml
+`config/slots_secrets.yml` can be used to store multiple secrets with a date (this way secrets can be updated without invalidating current tokens). The format for the file is:
+```yaml
+---
+- CREATED_AT: EPOCH TIME IN SECONDS
+  SECRET: new_secret
+- CREATED_AT: EPOCH TIME IN SECONDS
+  SECRET: old_secret
+...
+```
+The order should be newer to older secrets. This file can be created/updated manually or using `rake slots:new_secret`. If using `rake slots:new_secret` secrets that are older than session_lifetime will be removed. When updating manually remember to restart the server `rake restart`.
+
+## Routes
+
+All these routes will be mounted at the route used above in `mount Slots::Engine =>`.
+
+| Route Helper | Route | Token |     |
+| ------------ | ----- | ----- | --- |
+| `slots.sign_in` | GET/POST `/sign_in` | Does not require Token | This is used to sign in. login and password are expected as params. If the credentials are valid the user is returned with the token in header in the following format: `'authorization' => 'Bearer token=TOKEN'` (same as sending) |
+| `slots.sign_out` | DELETE `/sign_out` | Requires Token | This is used to sign out. This will delete the session if one exist for the token. |
+| `slots.update_session_token` | GET `/update_session_token` | Requires Token (token can be expired). | This is used to force a new token to be returned from an expired token using the session in the JWT. The token is returned in the same way as sign_in. |
+
+
+### Why use session token inside a JWS?
+
+Good question, first it's important to talk about some of the reasons (well maybe just one of the reasons) for using JWS:
+  - They are stateless. The nice thing is you don't have to go query a database to see if the session exist. Also if you have two different services that don't share a database they can validate the request by having the same secret.
+
+Some of the problems with JWS:
+  - Since the tokens are stateless its hard to revoke a token before it expires. In the case of this gem revoking a token is important for signing out. Some solutions suggested are:
+
+| Solutions  | Problems |
+| ---------- | -------- |
+| Set long expatriation and ignore signing out (Have front end handle it by saving the token if the user wants to stay signed in) | If the token is compromised the token is still valid for X time. You can only revoke it by creating a new secret, which would require all users to get a new tokens. |
+| Set long expiration and Store JWS in database | Not stateless. |
+| Set long expiration and Blacklist JWS to revoke (or when a user signs out) | Better... but still not stateless. |
+| Set short expiration and have a refresher/session token | When user signs out tokens are still valid for X time (which should be short). If the user info is changed (like a user is deactivated) the token is still valid until it expires. If a token with a session is compromised it can be revoked by removing that session (or all sessions if needed). |
+
+The last solution I feel is the best because for most API calls (within the expiration time) the token remains stateless. The downsides can be negligible by setting the expiration time to something small (less than an hour). .
+
+
+## Contributing
+
+
+## License
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rdoc/task'
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Slots'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.md')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load 'rails/tasks/engine.rake'
+
+load 'rails/tasks/statistics.rake'
+
+require 'bundler/gem_tasks'
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+task default: :test

data/app/controllers/slots/sessions_controller.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Slots
+  class SessionsController < ApplicationController
+    update_expired_session_tokens! only: :update_session_token # needed if token is expired
+    require_user_load! only: :update_session_token
+    require_login! only: [:update_session_token, :sign_out]
+    skip_callback!
+
+    def sign_in
+      @_current_user = _authentication_model.find_for_authentication(params[:login])
+
+      current_user.authenticate!(params[:password])
+
+      new_token!(ActiveModel::Type::Boolean.new.cast(params[:session]))
+      render json: current_user.as_json, status: :accepted
+    end
+
+    def sign_out
+      Slots::Session.find_by(session: jw_token.session)&.delete if jw_token.session.present?
+      head :ok
+    end
+
+    def update_session_token
+      # TODO think about not allowing user to get new token here because then there
+      current_user.update_token unless current_user.new_token?
+      render json: current_user.as_json, status: :accepted
+    end
+
+    private
+
+      def _authentication_model
+        Slots.configuration.authentication_model
+      end
+  end
+end

data/app/mailers/slots/application_mailer.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Slots
+  class ApplicationMailer < ActionMailer::Base
+    default from: "from@example.com"
+    layout "mailer"
+  end
+end

data/app/models/slots/application_record.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Slots
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/app/models/slots/session.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Slots
+  class Session < ApplicationRecord
+    belongs_to :user, session_assocaition
+    before_validation :create_random_session, on: :create
+    validates :session, :jwt_iat, presence: true
+    validates :session, uniqueness: true
+
+    def update_random_session
+      self.session = SecureRandom.hex(32)
+    end
+
+    def self.expired
+      self.where(self.arel_table[:created_at].lte(Slots.configuration.session_lifetime.ago))
+    end
+
+    def self.not_expired
+      self.where(self.arel_table[:created_at].gt(Slots.configuration.session_lifetime.ago))
+    end
+
+    def self.matches_jwt(sloken_jws)
+      jwt_where = self.arel_table[:jwt_iat].eq(sloken_jws.iat)
+      if Slots.configuration.previous_jwt_lifetime
+        jwt_where = jwt_where.or(
+          Arel::Nodes::Grouping.new(
+            self.arel_table[:previous_jwt_iat].eq(sloken_jws.iat)
+              .and(self.arel_table[:jwt_iat].gt(Slots.configuration.previous_jwt_lifetime.ago.to_i))
+            )
+        )
+      end
+
+      self.not_expired
+        .where(jwt_where)
+        .find_by(session: sloken_jws.session)
+    end
+    private
+      def create_random_session
+        update_random_session unless self.session
+      end
+  end
+end

data/config/routes.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+user_model = Slots.configuration.authentication_model&.name&.underscore || ""
+Slots::Engine.routes.draw do
+  get 'sign_in', to: 'sessions#sign_in'
+  post 'sign_in', to: 'sessions#sign_in'
+  delete 'sign_out', to: 'sessions#sign_out'
+  get 'update_session_token', to: 'sessions#update_session_token'
+  # get 'valid_token', to: 'sessions#valid_token' TODO not sure if valid token is needed
+end

data/lib/generators/slots/install/USAGE

@@ -0,0 +1,13 @@
+Description:
+    This is used for creating slots config file and adding the routes to config/routes.rb
+
+Example:
+    rails generate slots:install
+
+    This will create:
+        config/initializers.slots.rb
+        db/migrate/YYYYMMDDHHMMSS_create_slots_sessions.rb
+
+    This will add:
+      TO: config/routes.rb
+        mount Slots::Engine => "/slots"

data/lib/generators/slots/install/install_generator.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Slots
+  class InstallGenerator < Rails::Generators::Base
+    source_root File.expand_path('templates', __dir__)
+
+    def copy_initializer
+      template "slots.rb", "config/initializers/slots.rb"
+      template "create_slots_sessions.rb", "db/migrate/#{Time.now.strftime("%Y%m%d%H%M%S")}_create_slots_sessions.rb"
+    end
+
+    def add_route
+      route "mount Slots::Engine => '/auth'"
+    end
+  end
+end

data/lib/generators/slots/install/templates/create_slots_sessions.rb

@@ -0,0 +1,13 @@
+class CreateSlotsSessions < ActiveRecord::Migration[5.2]
+  def change
+    create_table :slots_sessions do |t|
+      t.string :session, length: 128
+      t.bigint :jwt_iat
+      t.bigint :previous_jwt_iat
+      t.bigint :user_id, index: true
+
+      t.timestamps
+    end
+    add_index :slots_sessions, :session, unique: true
+  end
+end

data/lib/generators/slots/install/templates/slots.rb

@@ -0,0 +1,10 @@
+Slots.configure do |config|
+  # config.logins = :email || {email: /@/, username: //}
+  # config.login_regex_validations = true
+  # config.authentication_model = 'User'
+  # config.secret = ENV['SLOT_SECRET']
+  # config.token_lifetime = 1.hour
+  # config.session_lifetime = 2.weeks
+  # config.previous_jwt_lifetime = 5.seconds # Set to nil if you dont want previous_jwt_lifetime
+  # config.secret_yaml = false # Set to true to read secret from config/slots_secrets.yml
+end