jwt-auth 4.2.0 → 5.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cb9d83836fe9d226380f942eaa215d51fb3ad36d05ea5ead0aaae1fbb270931a
-  data.tar.gz: ec4fcf71b3bea2a226e806ad26c979695fd2eaec8ee506fc078147b2145659d6
+  metadata.gz: c1f15acad1cbf01398773956c92432bcb1011ab1a41e37ef8829196260274b9d
+  data.tar.gz: add25d8fdb4425010c9a8a48fdded669818420d1e923d44a8ed7189861bf7279
 SHA512:
-  metadata.gz: d881ce27f177aa441846d4d7cd8aa9d5518e1c543caa7a5df06f31f5a6b95d4daf13d29a2e2321e767e5ed9574908859cd055fd2458c4bb9c2bd5f44576e1334
-  data.tar.gz: 5c94d698a8d3797416b8bb7a357fbccd203fca8fa82b92bf340fafd03e17783467b4ccdc646f66bf0aeef74153f384464c68ae667d440af37b7ad648adc3b9ce
+  metadata.gz: 9aaaf2d95f5a00989134c7e5be578e2078bbe8c7f2d50c4575a2fbe6acdd4b181629f0236aafe8a2a0faa20edc6b8a4b8b2e2619235fd529eb4066573b09ca62
+  data.tar.gz: 7f37a1e60dc8f81f61fee5d20529c62119c4f22e78b88a36fc94a8ecceff8c7a23e0b6a97d1778d85e26717f5018ccb12a946557910434cb3e6771816c80383e

data/.travis.yml

@@ -1,6 +1,9 @@
 language: ruby
 rvm:
+  - 2.3.0
   - 2.4.0
+  - 2.5.0
+  - 2.6.0
 cache:
   bundler: true
 env:

data/Gemfile

@@ -1,4 +1,7 @@
 # frozen_string_literal: true
 
 source 'https://rubygems.org'
+
+ruby '>= 2.3'
+
 gemspec

data/README.md

@@ -2,6 +2,33 @@
 
 JWT-based authentication middleware for Rails API without Devise
 
+## Concept
+
+JWT::Auth uses a two-token authentication mechanism.
+When the client authenticates against the application, a long-lived token is generated (called a refresh token).
+Using this long-lived token, a short-lived token can be requested using a different endpoint.
+This short-lived token (called an access token) can then be used to manipulate the API.
+
+```
+     +--------+                               +---------------+
+     |        |---- Authentication Request -->|    Sign in    |
+     |        |                               |    Endpoint   |
+     |        |<--------- Refresh Token ------|               |
+     |        |                               +---------------+
+     |        |                             
+     |        |                               +---------------+
+     |        |--------- Refresh Token ------>|    Refresh    |
+     | Client |                               |    Endpoint   |
+     |        |<--------- Access Token -------|               |
+     |        |                               +---------------+
+     |        |
+     |        |                               +---------------+
+     |        |---------- Access Token ------>|      API      |
+     |        |                               |    Endpoint   |
+     |        |<------- Protected Resource ---|               |
+     +--------+                               +---------------+
+```
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -23,9 +50,14 @@ Create an initializer:
 ```ruby
 JWT::Auth.configure do |config|
   ##
-  # Token lifetime
+  # Refresh token lifetime
+  #
+  config.refresh_token_lifetime = 1.year
+  
+  ##
+  # Access token lifetime
   #
-  config.token_lifetime = 24.hours
+  config.access_token_lifetime = 2.hours
   
   ##
   # JWT secret
@@ -36,7 +68,7 @@ end
 
 Do not try to set the `model` configuration property in the initializer, as this property is already set by including the `Authenticatable` concern in your model.
 
-Include model methods in your user model:
+Include model methods in your user model. This adds a dummy `#find_by_token` method, which you can override, and a validation for `#token_version`.
 
 ```ruby
 class User < ApplicationRecord
@@ -44,7 +76,7 @@ class User < ApplicationRecord
 end
 ```
 
-Optionally, define the `find_by_token` method on your model to allow additional checks (for example account activation):
+Optionally, override the `#find_by_token` method on your model to allow additional checks (for example account activation):
 
 ```ruby
 def self.find_by_token(params)
@@ -52,7 +84,7 @@ def self.find_by_token(params)
 end
 ```
 
-Add a `token_version` field to your user model:
+Generate the `token_version` migration:
 
 ```ruby
 class AddTokenVersionToUser < ActiveRecord::Migration[5.0]
@@ -71,6 +103,9 @@ class ApplicationController < ActionController::API
   
   rescue_from JWT::Auth::UnauthorizedError, :with => :handle_unauthorized
   
+  # Validate validity of token (if present) on all routes
+  before_action :validate_token
+
   protected
   
   def handle_unauthorized
@@ -79,24 +114,88 @@ class ApplicationController < ActionController::API
 end
 ```
 
-Set callbacks on routes:
+Add the appropriate filters on your authentication API actions:
 
 ```ruby
-class MyController < ApplicationController
-  # Authenticates user from request header
-  # The callback raises an UnauthorizedError on missing or invalid token 
-  before_action :authenticate_user, :except => %i[create]
-  
-  # Validate token if there is a token present
-  # The callback raises an UnauthorizedError only if there is a token present, and it is invalid
-  # This prevents users from using an expired token on an unauthenticated route and getting a HTTP 2xx
-  before_action :validate_token 
-  
-  # Renew token and set response header
-  after_action :renew_token
+class TokensController < ApplicationController
+  # Validate refresh token on refresh action
+  before_action :validate_refresh_token, :only => :update
+
+  # Require token only on refresh action
+  before_action :require_token, :only => :update
+
+  ##
+  # POST /token
+  #
+  # Sign in the user
+  #
+  def create
+    @user = User.active.find_by :email => params[:email], :password => params[:password]
+    raise JWT::Auth::UnauthorizedError unless @user
+
+    # Return a long-lived refresh token
+    set_refresh_token @user
+
+    head :no_content
+  end
+
+  ##
+  #
+  # PATCH /token
+  #
+  # Refresh access token
+  #
+  def update
+    # Return a short-lived access token
+    set_access_token
+
+    head :no_content
+  end
+end
+
+```
+
+Set the appropriate filters on your API actions:
+
+```ruby
+class ContentController < ApplicationController
+  # Validate access token on all actions
+  before_action :validate_access_token
+
+  # Require token for protected actions
+  before_action :require_token, :only => :authenticated
+
+  ##
+  # GET /unauthenticated
+  #
+  # This endpoint is not protected, performing a request without a token, or with a valid token will succeed
+  # Performing a request with an invalid token will raise an UnauthorizedError
+  #
+  def unauthenticated
+    head :no_content
+  end
+
+  ##
+  # GET /unauthenticated
+  #
+  # This endpoint is protected, performing a request with a valid access token will succeed
+  # Performing a request without a token, with an invalid token or with a refresh token will raise an UnauthorizedError
+  #
+  def authenticated
+    head :no_content
+  end
 end
 ```
 
+You can find a fully working sample application in [spec/dummy](spec/dummy).
+
+## Migration guide
+
+### From 4.2 to 5.0
+
+5.0 includes breaking changes and introduces the concept of a refresh and an access token.
+Please remove jwt-auth entirely from your application, and reinstall it using the instructions above.
+
 ## Contributing
 
 1. Fork it ( https://github.com/floriandejonckheere/jwt-auth/fork )
@@ -104,3 +203,5 @@ end
 3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)
 5. Create a new Pull Request
+
+For your convenience, scripts to automatically increment version number and build a release were included in `bin/`.

data/bin/build

@@ -0,0 +1,22 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# build - Build and publish a gem
+#
+
+require 'yaml'
+
+# Push to git repository
+puts 'Pushing to git repository...'
+`git push --follow-tags`
+
+# Build gem
+puts 'Building .gem...'
+`gem build jwt-auth.gemspec`
+
+# Publish gem
+puts 'Publishing gem...'
+`gem push $(ls *.gem | sort -h | tail -1)`
+
+puts "\nRelease v#{YAML.load_file File.join __dir__, '..', 'version.yml'} published!"

data/bin/release

@@ -0,0 +1,40 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# release - Increment gem version and create a release
+#
+
+require 'semverse'
+require 'yaml'
+
+VERSION_FILE = File.join __dir__, '..', 'version.yml'
+
+version = Semverse::Version.new YAML.load_file VERSION_FILE
+new_version = nil
+
+case ARGV.first
+when '--major'
+  new_version = "#{version.major + 1}.0.0"
+when '--minor'
+  new_version = "#{version.major}.#{version.minor + 1}.0"
+when '--patch'
+  new_version = "#{version.major}.#{version.minor}.#{version.patch + 1}"
+else
+  puts "Usage: #{__FILE__} --major | --minor | --patch"
+  exit! 1
+end
+
+# Write version file
+File.write VERSION_FILE, new_version.to_yaml
+
+# Create git commit
+puts 'Creating release commit...'
+`git add #{VERSION_FILE}`
+`git commit -m 'Bump version to #{new_version}'`
+
+# Create git tag
+puts 'Creating release tag...'
+`git tag v#{new_version}`
+
+puts "\nRelease v#{new_version} created!"

data/jwt-auth.gemspec

@@ -1,7 +1,6 @@
-# coding: utf-8
 # frozen_string_literal: true
 
-lib = File.expand_path('../lib', __FILE__)
+lib = File.expand_path('lib', __dir__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 
 require 'jwt/auth/version'
@@ -11,26 +10,30 @@ Gem::Specification.new do |gem|
   gem.version       = JWT::Auth::VERSION
   gem.authors       = ['Florian Dejonckheere']
   gem.email         = ['florian@floriandejonckheere.be']
+  gem.date          = Time.now.utc.strftime '%Y-%m-%d'
   gem.summary       = 'JWT-based authentication for Rails API'
   gem.description   = 'Authentication middleware for Rails API that uses JWTs'
   gem.homepage      = 'https://github.com/floriandejonckheere/jwt-auth'
   gem.license       = 'MIT'
 
-  gem.files         = `git ls-files -z`.split("\x0")
-  gem.executables   = gem.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  gem.files         = `git ls-files -z`.split "\x0"
+  gem.executables   = gem.files.grep(%r{^bin/}) { |f| File.basename f }
   gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
-  gem.require_paths = ['lib']
+  gem.require_paths = %w[lib]
 
-  gem.add_runtime_dependency 'jwt', '~> 2.0'
-  gem.add_runtime_dependency 'rails', '~> 5.2'
+  gem.add_runtime_dependency 'jwt'
+  gem.add_runtime_dependency 'rails'
 
-  gem.add_development_dependency 'bundler', '~> 1.17'
-  gem.add_development_dependency 'rubocop', '~> 0.63'
-  gem.add_development_dependency 'rake', '~> 12.3'
-  gem.add_development_dependency 'rspec', '~> 3.8'
-  gem.add_development_dependency 'rspec-rails', '~> 3.8'
-  gem.add_development_dependency 'rdoc', '~> 6.1'
-  gem.add_development_dependency 'coveralls', '~> 0.8'
+  gem.add_development_dependency 'bundler'
   gem.add_development_dependency 'byebug'
-  gem.add_development_dependency 'sqlite3'
+  gem.add_development_dependency 'coveralls'
+  gem.add_development_dependency 'database_cleaner'
+  gem.add_development_dependency 'rake'
+  gem.add_development_dependency 'rdoc'
+  gem.add_development_dependency 'rspec'
+  gem.add_development_dependency 'rspec-rails'
+  gem.add_development_dependency 'rubocop'
+  gem.add_development_dependency 'semverse'
+  gem.add_development_dependency 'shoulda-matchers'
+  gem.add_development_dependency 'sqlite3', '~> 1.3.6'
 end

data/lib/jwt/auth.rb

@@ -8,3 +8,5 @@ require 'jwt/auth/configuration'
 require 'jwt/auth/authenticatable'
 require 'jwt/auth/authentication'
 require 'jwt/auth/token'
+require 'jwt/auth/access_token'
+require 'jwt/auth/refresh_token'

data/lib/jwt/auth/access_token.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'jwt/auth/configuration'
+
+module JWT
+  module Auth
+    ##
+    # JWT access token
+    #
+    class AccessToken < Token
+      def type
+        :access
+      end
+
+      def lifetime
+        JWT::Auth.access_token_lifetime
+      end
+    end
+  end
+end

data/lib/jwt/auth/authenticatable.rb

@@ -11,9 +11,25 @@ module JWT
       extend ActiveSupport::Concern
 
       included do
+        ##
+        # Define model in jwt-auth configuration
+        #
         JWT::Auth.configure do |config|
           config.model = name
         end
+
+        ##
+        # Token version validation
+        #
+        validates :token_version,
+                  :presence => true
+
+        ##
+        # Dummy #find_by_token method
+        #
+        def find_by_token(*args)
+          find_by args
+        end
       end
     end
   end

data/lib/jwt/auth/authentication.rb

@@ -9,52 +9,93 @@ module JWT
     #
     module Authentication
       ##
-      # Current user helper
+      # Current user
       #
       def current_user
-        jwt && jwt.subject
+        token&.subject
       end
 
       ##
-      # Authenticate a request
+      # Validate a token (if it's present)
       #
-      def authenticate_user
-        raise JWT::Auth::UnauthorizedError unless jwt && jwt.valid?
+      # Apply this before_action filter for every API action
+      #
+      # @raises JWT::Auth::UnauthorizedError if a token is present and invalid
+      #
+      def validate_token
+        raise JWT::Auth::UnauthorizedError unless token.nil? || token&.valid?
       end
 
       ##
-      # Validate a token (authenticate a request iff there is a token)
+      # Authenticate the user with the token
       #
-      def validate_token
-        authenticate_user if jwt
+      # Apply this filter for API actions that need an access token
+      # This filter does not enforce token presence
+      #
+      # @raises JWT::Auth::UnauthorizedError if a token is present and it is not a valid access token
+      #
+      def validate_access_token
+        raise JWT::Auth::UnauthorizedError unless header.nil? || token.is_a?(AccessToken)
       end
 
       ##
-      # Add JWT header to response
+      # Validate a refresh token
+      #
+      # Apply this filter for the API token refresh action
+      # This filter does not enforce token presence
       #
-      def renew_token
-        return unless jwt && jwt.valid?
-        jwt.renew!
-        response.headers['Authorization'] = "Bearer #{jwt.to_jwt}"
+      # @raises JWT::Auth::UnauthorizedError if a token is present and it is not a valid refresh token
+      #
+      def validate_refresh_token
+        raise JWT::Auth::UnauthorizedError unless header.nil? || token.is_a?(RefreshToken)
       end
 
-      protected
+      ##
+      # Require a token to be present
+      #
+      # Apply this filter for API actions that require an access token
+      #
+      # @raises JWT::Auth::UnauthorizedError if on token is present
+      #
+      def require_token
+        raise JWT::Auth::UnauthorizedError if token.nil?
+      end
 
       ##
-      # Extract JWT from request
+      # Set API token in the response
       #
-      def jwt
-        return @token if @token
+      def set_access_token(user = current_user)
+        set_header JWT::Auth::AccessToken.new(:subject => user)
+      end
+
+      ##
+      # Set refresh token in the response
+      #
+      def set_refresh_token(user = current_user)
+        set_header JWT::Auth::RefreshToken.new(:subject => user)
+      end
+
+      protected
 
+      def token
+        @token ||= JWT::Auth::Token.from_jwt header
+      end
+
+      ##
+      # Extract token from request
+      #
+      def header
         header = request.env['HTTP_AUTHORIZATION']
         return nil unless header
 
-        token = header.scan(/Bearer (.*)$/).flatten.last
-        return nil unless token
+        header.scan(/Bearer (.*)$/).flatten.last
+      end
 
-        @token = JWT::Auth::Token.from_token token
-      rescue JWT::DecodeError
-        nil
+      ##
+      # Set a token in the response
+      #
+      def set_header(token)
+        response.headers['Authorization'] = "Bearer #{token.to_jwt}"
       end
     end
   end