devise-jwt 0.4.4 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9129d2a81114b968dc51a11fa2e04aef75b9324f
-  data.tar.gz: 26c8980b2a75ba0f225193cc5cffed9b8bbb9c1f
+  metadata.gz: 7d9d15287c66562066c4c4a729506396e7ec4007
+  data.tar.gz: 1043788671b10218a3bc7c778f10a2f2c258ee84
 SHA512:
-  metadata.gz: 9e89f30b0eee4ffce4632572a71b6c66a1075ba8e0a20e24bc64c0eb2227c27f4ca5df2af7a25296cccf19edb320cfa18236d4d365bf2f50a37983d6746d71de
-  data.tar.gz: e4838a029bc9e0753ffb6cd49bf9cdeb50ea88f0c7a909b43e6e60a8e7ecb87639058199350d04d0fbb876db923cdf0e13d0f27bc4c431ffb081a7e02bbd3c68
+  metadata.gz: 1fb0e64bff0707c6a476868f5b1ed9fe967472e0fa385dac3e7c74b8f54433a98d57b1e16b057e59d566721ab91444aed1ec5ece13e309867c43da5bfe5554c4
+  data.tar.gz: d2cb740987f7c7321a16a38def56fb7e31e90cc4b17f3cdb37ae65f38ac308b64619d52e4ac929f5fbab0ccb18e264837805a98342a9160710df806413b5e9f9

data/CHANGELOG.md

@@ -4,6 +4,11 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/) 
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
+## [0.5.0] - 2017-12-11
+### Added
+- Added whitelist strategy
+- Update `warden-jwt_auth` dependency
+
 ## [0.4.4] - 2017-12-04
 ### Fixed
 - Configure classes as strings to avoid problems with Rails STI

data/README.md

@@ -26,7 +26,7 @@ You can read about which security concerns this library takes into account and a
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'devise-jwt', '~> 0.4.4'
+gem 'devise-jwt', '~> 0.5.0'
 ```
 
 And then execute:
@@ -86,6 +86,14 @@ def jwt_payload
 end
 ```
 
+You can add a hook method `on_jwt_dispatch` on the user model. It is executed when a token dispatched for that user instance, and it takes `token` and `payload` as parameters.
+
+```ruby
+def on_jwt_dispatch(token, payload)
+  do_something(token, payload)
+end
+```
+
 Note: if you are making cross-domain requests, make sure that you add `Authorization` header to the list of allowed request headers and exposed response headers. You can use something like [rack-cors](https://github.com/cyu/rack-cors) for that, for example:
 
 ```ruby
@@ -103,7 +111,7 @@ end
 
 ### Revocation strategies
 
-`devise-jwt` comes with two revocation strategies out of the box. They are implementations of what is discussed in the blog post [JWT Revocation Strategies](http://waiting-for-dev.github.io/blog/2017/01/24/jwt_revocation_strategies/), where I also talk about their pros and cons.
+`devise-jwt` comes with three revocation strategies out of the box. Some of them are implementations of what is discussed in the blog post [JWT Revocation Strategies](http://waiting-for-dev.github.io/blog/2017/01/24/jwt_revocation_strategies/), where I also talk about their pros and cons.
 
 #### JTIMatcher
 
@@ -152,7 +160,7 @@ end
 
 #### Blacklist
 
-In this strategy, a database table is used as a blacklist of revoked JWT tokens. The `jti` claim, which uniquely identifies a token, is persisted.
+In this strategy, a database table is used as a blacklist of revoked JWT tokens. The `jti` claim, which uniquely identifies a token, is persisted. The `exp` claim is also stored to allow the clean-up of staled tokens.
 
 In order to use it, you need to create the blacklist table in a migration:
 
@@ -197,6 +205,74 @@ class User < ApplicationRecord
 end
 ```
 
+#### Whitelist
+
+Here, the model itself acts also as a revocation strategy, but it needs to have
+a one-to-many association with another table which stores the tokens (in fact
+their `jti` claim, which uniquely identifies them) valids for each user record.
+
+The workflow is as the following:
+
+- Once a token is dispatched for a user, its `jti` claim is stored in the
+  associated table.
+- At every authentication, the incoming token `jti` is matched against all the
+  `jti` associated to that user. The authentication only succeeds if one of
+  them matches.
+- On a sign out, the token `jti` is deleted from the associated table.
+
+In fact, besides the `jti` claim, the `aud` claim is also stored and matched at
+every authentication. This, together with the [aud_header](#aud_header)
+configuration parameter, can be used to differentiate between clients or
+devices for the same user.
+
+The `exp` claim is also stored to allow the clean-up of staled tokens.
+
+In order to use it, you have to create yourself the associated table and model.
+The association table must be called `whitelisted_jwts`:
+
+```ruby
+def change
+  create_table :whitelisted_jwts do |t|
+    t.string :jti, null: false
+    t.string :aud
+    # If you want to leverage the `aud` claim, add to it a `NOT NULL` constraint:
+    # t.string :aud, null: false
+    t.datetime :exp, null: false
+    t.references :your_user_table, foreign_key: true
+  end
+  
+  add_index :whitelisted_jwts, :jti, unique: true
+end
+```
+Important: You are encouraged to set a unique index in the jti column. This way we can be sure at the database level that there aren't two valid tokens with same jti at the same time.
+
+And then, the model:
+
+```ruby
+class WhitelistedJwt < ApplicationRecord
+end
+```
+
+Finally, include de strategy in the model and configure it:
+
+```ruby
+class User < ApplicationRecord
+  include Devise::JWT::RevocationStrategies::Whitelist
+  
+  devise :database_authenticatable,
+         :jwt_authenticatable, jwt_revocation_strategy: self
+end
+```
+
+Be aware that this strategy makes uses of `on_jwt_dispatch` method in the user model, so if you need to use it don't forget to call `super`:
+
+```ruby
+def on_jwt_dispatch(token, payload)
+  super
+  do_something(token, payload)
+end
+```
+
 #### Null strategy
 
 A [null object pattern](https://en.wikipedia.org/wiki/Null_Object_pattern) strategy, which does not revoke tokens, is provided out of the box just in case you are absolutely sure you don't need token revocation. It is recommended **not to use it**.
@@ -308,6 +384,22 @@ jwt.request_formats = {
 
 By default, only requests without format are processed.
 
+#### aud_header
+
+Request header which content will be stored to the `aud` claim in the payload.
+
+It is used to validate whether an incoming token was originally issued to the
+same client, checking if `aud` and the `aud_header` header value match. If you
+don't want to differentiate between clients, you don't need to provide that
+header.
+
+**Important:** Be aware that this workflow is not bullet proof. In some
+scenarios a user can handcraft the request headers, therefore being able to
+impersonate any client. In such cases you could need something more robust,
+like an OAuth workflow with client id and client secret.
+
+Defaults to `JWT_AUD`.
+
 ## Development
 
 There are docker and docker-compose files configured to create a development environment for this gem. So, if you use Docker you only need to run:

data/devise-jwt.gemspec

@@ -22,7 +22,7 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   spec.add_dependency 'devise', '~> 4.0'
-  spec.add_dependency 'warden-jwt_auth', '~> 0.2.1'
+  spec.add_dependency 'warden-jwt_auth', '~> 0.3.0'
 
   spec.add_development_dependency "bundler", "~> 1.12"
   spec.add_development_dependency "rake", "~> 10.0"

data/lib/devise/jwt.rb

@@ -42,6 +42,10 @@ module Devise
       forward_to_warden(:revocation_requests, value)
     end
 
+    setting(:aud_header) do |value|
+      forward_to_warden(:aud_header, value)
+    end
+
     # A hash of warden scopes as keys and an array of request formats that will
     # be processed as values. When a scope is not present or if it has a nil
     # item, requests without format will be taken into account.

data/lib/devise/jwt/revocation_strategies.rb

@@ -2,6 +2,7 @@
 
 require 'devise/jwt/revocation_strategies/jti_matcher'
 require 'devise/jwt/revocation_strategies/blacklist'
+require 'devise/jwt/revocation_strategies/whitelist'
 require 'devise/jwt/revocation_strategies/null'
 
 module Devise

data/lib/devise/jwt/revocation_strategies/whitelist.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require 'active_support/concern'
+
+module Devise
+  module JWT
+    module RevocationStrategies
+      # This strategy must be included in the user model.
+      #
+      # The JwtWhitelist table must include `jti`, `aud`, `exp` and `user_id`
+      # columns
+      #
+      # In order to tell whether a token is revoked, it just tries to find the
+      # `jti` and `aud` values from the token on the `whitelisted_jwts`
+      # table for the respective user.
+      #
+      # If the values don't exist means the token was revoked.
+      # On revocation, it deletes the matching record from the
+      # `whitelisted_jwts` table.
+      #
+      # On sign in, it creates a new record with the `jti` and `aud` values.
+      module Whitelist
+        extend ActiveSupport::Concern
+
+        included do
+          has_many :whitelisted_jwts, dependent: :destroy
+
+          # @see Warden::JWTAuth::Interfaces::RevocationStrategy#jwt_revoked?
+          def self.jwt_revoked?(payload, user)
+            !user.whitelisted_jwts.exists?(payload.slice('jti', 'aud'))
+          end
+
+          # @see Warden::JWTAuth::Interfaces::RevocationStrategy#revoke_jwt
+          def self.revoke_jwt(payload, user)
+            user.whitelisted_jwts.find_by(payload.slice('jti', 'aud')).destroy!
+          end
+        end
+
+        # Warden::JWTAuth::Interfaces::User#on_jwt_dispatch
+        # :reek:FeatureEnvy
+        def on_jwt_dispatch(_token, payload)
+          whitelisted_jwts.create!(
+            jti: payload['jti'],
+            aud: payload['aud'],
+            exp: Time.at(payload['exp'].to_i)
+          )
+        end
+      end
+    end
+  end
+end

data/lib/devise/jwt/version.rb

@@ -2,6 +2,6 @@
 
 module Devise
   module JWT
-    VERSION = '0.4.4'
+    VERSION = '0.5.0'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: devise-jwt
 version: !ruby/object:Gem::Version
-  version: 0.4.4
+  version: 0.5.0
 platform: ruby
 authors:
 - Marc Busqué
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-12-04 00:00:00.000000000 Z
+date: 2017-12-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: devise
@@ -30,14 +30,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.2.1
+        version: 0.3.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.2.1
+        version: 0.3.0
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -200,6 +200,7 @@ files:
 - lib/devise/jwt/revocation_strategies/blacklist.rb
 - lib/devise/jwt/revocation_strategies/jti_matcher.rb
 - lib/devise/jwt/revocation_strategies/null.rb
+- lib/devise/jwt/revocation_strategies/whitelist.rb
 - lib/devise/jwt/version.rb
 homepage: https://github.com/waiting-for-dev/devise-jwt
 licenses: