jwt_sessions 2.3.1 → 2.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ea880100e93f25c3fc31e32161f6881a21c184cb
-  data.tar.gz: b549fea16c7d4ea09d8c1f7002a0d5cdd06c36b5
+  metadata.gz: 8fe66c91df4011e6e59d05bda8a9d43188b8f07a
+  data.tar.gz: 97bb42e7a8f6ecb5037b3bc6b057758dfcf2397d
 SHA512:
-  metadata.gz: 78a5845fb2168f8ae8023d6ce6cc291ed2803fecefe2298afbc4423fc7319a29a7a75efd68fa2a17fc28e498a0b73d0c183ca1f1fb1f6005efc6430898acd92b
-  data.tar.gz: dc9074a35fee61a1749d42ec5bd3de687c683a8aa39c32c683eb58579b5831e735dc9904ff60c61b1add355ed61ddbb2686a74f171ceaa3922fcb737618f3bad
+  metadata.gz: a353fc811d0cd645655467088651f33b22e9dde3778a8fe2ef027bb07f5274a98acb0f9243a8791251d203e14445f453e2ee61af6829b078e4150f199a0332cc
+  data.tar.gz: baef0f6687c8ec9171e67a74fda5d5f4907a600e7d6ce829a5d01e39cfb62af6777dce235bcfcc989313c6d9b3273abbd914da8d0a074b9f0ceff517398f87e1

data/README.md

@@ -11,6 +11,7 @@ XSS/CSRF safe JWT auth designed for SPA
 - [Synopsis](#synopsis)
 - [Installation](#installation)
 - [Getting Started](#getting-started)
+  * [Creating a session](#creating-a-session)
   * [Rails integration](#rails-integration)
   * [Non-Rails usage](#non-rails-usage)
 - [Configuration](#configuration)
@@ -32,7 +33,9 @@ XSS/CSRF safe JWT auth designed for SPA
 
 Main goal of this gem is to provide configurable, manageable, and safe stateful sessions based on JSON Web Tokens.
 
-It's designed to be framework agnostic yet is easily integrable so Rails integration is also available out of the box.
+The gem stores JWT based sessions on the backend (currently, redis and memory stores are supported), making it possible to manage sessions, reset passwords, logout users in a reliable and secure way.
+
+It's designed to be framework agnostic yet is easily integrable, and Rails integration is available out of the box.
 
 Core concept behind `jwt_sessions` is that each session is represented by a pair of tokens: access and refresh, and a session store is used to handle CSRF checks and refresh token hijacking. Both tokens have configurable expiration times, but in general refresh token is supposed to have a longer lifespan than an access token. Access token is used to retrieve secured resources and refresh token is used to renew the access token once it's expired. Default token store is based on redis.
 
@@ -56,7 +59,80 @@ bundle install
 
 ## Getting Started
 
-`Authorization` mixin is supposed to be included in your controllers and is used to retrieve access and refresh tokens from incoming requests and verify CSRF token if needed. It assumes that a token is either in a cookie or in a header (cookie and header names are configurable). It tries to retrieve it from headers first, then from cookies (CSRF check included) if the headers check failed.
+You should configure an encryption algorithm and specify the encryption key. By default the gem uses `HS256`.
+
+```ruby
+JWTSessions.encryption_key = "secret"
+```
+
+`Authorization` mixin provides helper methods which are used to retrieve access and refresh tokens from incoming requests and verify CSRF token if needed. It assumes that a token can be found either in a cookie or in a header (cookie and header names are configurable). It tries to retrieve it from headers first, then from cookies (CSRF check included) if the headers check failed.
+
+### Creating a session
+
+Each token contains a payload with custom session info. The payload is a regular Ruby hash. \
+Usually, it contains user ID or other data which helps to identify current user but it's not necessary, the payload can be an empty hash as well.
+
+```ruby
+> payload = { user_id: user.id }
+=> {:user_id=>1}
+```
+
+Generate the session with a custom payload. By default the same payload is sewn into the session's access and refresh tokens.
+
+```ruby
+> session = JWTSessions::Session.new(payload: payload)
+=> #<JWTSessions::Session:0x00007fbe2cce9ea0...>
+```
+
+Sometimes it makes sense to keep different data within the payloads of access and refresh tokens. \
+The access token may contain rich data including user settings, etc., while the appropriate refresh token will include only the bare minimum which will be required to reconstruct a payload for the new access token during refresh.
+
+```ruby
+session = JWTSessions::Session.new(payload: payload, refresh_payload: refresh_payload)
+```
+
+Now we can call `login` method on the session to retrieve a set of tokens.
+
+```ruby
+> session.login
+=> {:csrf=>"BmhxDRW5NAEIx...",
+    :access=>"eyJhbGciOiJIUzI1NiJ9...",
+    :access_expires_at=>"..."
+    :refresh=>"eyJhbGciOiJIUzI1NiJ9...",
+    :refresh_expires_at=>"..."}
+```
+
+Access/refresh tokens automatically contain expiration time in their payload. Yet expiration times are also added to the output just in case. \
+The token's payload will be available in the controllers once the access (or refresh) token is authorized.
+
+To perform the refresh do:
+
+```ruby
+> session.refresh(refresh_token)
+=> {:csrf=>"+pk2SQrXHRo1iV1x4O...",
+    :access=>"eyJhbGciOiJIUzI1...",
+    :access_expires_at=>"..."}
+```
+
+Available `JWTSessions::Session.new` options:
+
+- **payload**: a hash object with session data which will be included into an access token payload. Default is an empty hash.
+- **refresh_payload**: a hash object with session data which will be included into a refresh token payload. Default is a value of the access payload.
+- **access_claims**: a hash object with [JWT claims](https://github.com/jwt/ruby-jwt#support-for-reserved-claim-names) which will be validated within the access token payload. F.e. `{ aud: ["admin"], verify_aud: true }` meaning that the token can be used only by "admin" audience. Also, the endpoint can automatically validate claims instead. See `token_claims` method.
+- **refresh_claims**: a hash object with [JWT claims](https://github.com/jwt/ruby-jwt#support-for-reserved-claim-names) which will be validated within the refresh token payload.
+- **namespace**: a string object which helps to group sessions by a custom criteria. For example, sessions can be grouped by user ID, then it'll be possible to logout the user from all devises. More info [Sessions Namespace](#sessions-namespace).
+- **refresh_by_access_allowed**: a boolean value. Default is false. It links access and refresh tokens (adds refresh token ID to access payload), making it possible to perform a session refresh by the last expired access token. See [Refresh with access token](#refresh-with-access-token).
+- **access_exp**: an integer value. Contains an access token expiration time in seconds. The value overrides global settings. See [Expiration time](#expiration-time).
+- **refresh_exp**: an integer value. Contains a refresh token expiration time in seconds. The value overrides global settings. See [Expiration time](#expiration-time).
+
+Helper methods within `Authorization` mixin:
+
+- **authorize_access_request!**: validates access token within the request.
+- **authorize_refresh_request!**: validates refresh token within the request.
+- **found_token**: a raw token found within the request.
+- **payload**: a decoded token's payload.
+- **claimless_payload**: a decoded token's payload without claims validation (can be used for checking data of an expired token).
+- **token_claims**: the method should be defined by a developer, and is expected to return a hash-like object with claims to be validated within a token's payload.
 
 ### Rails integration
 
@@ -91,25 +167,6 @@ JWTSessions.private_key = OpenSSL::PKey::RSA.generate(2048)
 JWTSessions.public_key  = JWTSessions.private_key.public_key
 ```
 
-Generate access/refresh/csrf tokens with a custom payload. \
-The payload will be available in the controllers once the access (or refresh) token is authorized. \
-Access/refresh tokens contain expiration time in their payload. Yet expiration times are also added to the output just in case.
-
-```ruby
-> payload = { user_id: user.id }
-=> {:user_id=>1}
-
-> session = JWTSessions::Session.new(payload: payload)
-=> #<JWTSessions::Session:0x00007fbe2cce9ea0...>
-
-> session.login
-=> {:csrf=>"BmhxDRW5NAEIx...",
-    :access=>"eyJhbGciOiJIUzI1NiJ9...",
-    :access_expires_at=>"..."
-    :refresh=>"eyJhbGciOiJIUzI1NiJ9...",
-    :refresh_expires_at=>"..."}
-```
-
 You can build login controller to receive access, refresh and csrf tokens in exchange for user's login/password. \
 Refresh controller - to be able to get a new access token using refresh token after access is expired. \
 Here is example of a simple login controller, which returns set of tokens as a plain JSON response. \
@@ -130,12 +187,6 @@ class LoginController < ApplicationController
 end
 ```
 
-Since it's not required to pass an access token when you want to perform a refresh you may need to have some data in the payload of the refresh token to allow you to construct a payload of the new access token during refresh.
-
-```ruby
-session = JWTSessions::Session.new(payload: payload, refresh_payload: refresh_payload)
-```
-
 Now you can build a refresh endpoint. To protect the endpoint use before_action `authorize_refresh_request!`. \
 The endpoint itself should return a renewed access token.
 
@@ -245,7 +296,7 @@ class SimpleApp < Sinatra::Base
   include JWTSessions::Authorization
 
   def request_headers
-    env.inject({}){|acc, (k,v)| acc[$1.downcase] = v if k =~ /^http_(.*)/i; acc}
+    env.inject({}) { |acc, (k,v)| acc[$1.downcase] = v if k =~ /^http_(.*)/i; acc }
   end
 
   def request_cookies
@@ -355,6 +406,7 @@ class UsersController < ApplicationController
   def token_claims
     {
       aud: ["admin", "staff"],
+      verify_aud: true, # can be used locally instead of a global setting
       exp_leeway: 15 # will be used instead of default leeway only for exp claim
     }
   end
@@ -384,6 +436,8 @@ JWTSessions.access_exp_time = 3600 # 1 hour in seconds
 JWTSessions.refresh_exp_time = 604800 # 1 week in seconds
 ```
 
+It's defined globally, but can be overridden on a session level. See `JWTSessions::Session.new` options for more info.
+
 #### CSRF and cookies
 
 In case when you use cookies as your tokens transport it gets vulnerable to CSRF. That's why both login and refresh methods of the `Session` class produce CSRF tokens for you. `Authorization` mixin expects that this token is sent with all requests except GET and HEAD in a header specified among this gem's settings (X-CSRF-Token by default). Verification will be done automatically and `Authorization` exception will be raised in case of mismatch between the token from the header and the one stored in session. \

data/lib/jwt_sessions.rb

@@ -136,6 +136,14 @@ module JWTSessions
     Time.now.to_i + refresh_exp_time.to_i
   end
 
+  def custom_access_expiration(time)
+    Time.now.to_i + (time || access_exp_time).to_i
+  end
+
+  def custom_refresh_expiration(time)
+    Time.now.to_i + (time || refresh_exp_time).to_i
+  end
+
   def header_by(token_type)
     send("#{token_type}_header")
   end

data/lib/jwt_sessions/access_token.rb

@@ -29,8 +29,8 @@ module JWTSessions
     end
 
     class << self
-      def create(csrf, payload, store)
-        new(csrf, payload, store).tap do |inst|
+      def create(csrf, payload, store, expiration = JWTSessions.access_expiration)
+        new(csrf, payload, store, SecureRandom.uuid, expiration).tap do |inst|
           store.persist_access(inst.uid, inst.csrf, inst.expiration)
         end
       end

data/lib/jwt_sessions/refresh_token.rb

@@ -13,15 +13,23 @@ module JWTSessions
       @access_uid        = access_uid
       @access_expiration = access_expiration
       @store             = store
-      @uid               = options.fetch(:uid, SecureRandom.uuid)
-      @expiration        = options.fetch(:expiration, JWTSessions.refresh_expiration)
+      @uid               = options.fetch(:uid, nil) || SecureRandom.uuid
+      @expiration        = options.fetch(:expiration, nil) || JWTSessions.refresh_expiration
       @namespace         = options.fetch(:namespace, nil)
       @token             = Token.encode(options.fetch(:payload, {}).merge("uid" => uid, "exp" => expiration.to_i))
     end
 
     class << self
-      def create(csrf, access_uid, access_expiration, store, payload, namespace)
-        inst = new(csrf, access_uid, access_expiration, store, payload: payload, namespace: namespace)
+      def create(csrf, access_uid, access_expiration, store, payload, namespace, expiration = JWTSessions.refresh_expiration)
+        inst = new(
+          csrf,
+          access_uid,
+          access_expiration,
+          store,
+          payload: payload,
+          namespace: namespace,
+          expiration: expiration
+        )
         inst.send(:persist_in_store)
         inst
       end

data/lib/jwt_sessions/session.rb

@@ -20,6 +20,8 @@ module JWTSessions
       @refresh_claims            = options.fetch(:refresh_claims, {})
       @namespace                 = options.fetch(:namespace, nil)
       @refresh_by_access_allowed = options.fetch(:refresh_by_access_allowed, false)
+      @_access_exp               = options.fetch(:access_exp, nil)
+      @_refresh_exp              = options.fetch(:refresh_exp, nil)
     end
 
     def login
@@ -237,18 +239,26 @@ module JWTSessions
     end
 
     def create_refresh_token
-      @_refresh = RefreshToken.create(@_csrf.encoded,
-                                      @_access.uid,
-                                      @_access.expiration,
-                                      store,
-                                      refresh_payload,
-                                      namespace)
+      @_refresh = RefreshToken.create(
+        @_csrf.encoded,
+        @_access.uid,
+        @_access.expiration,
+        store,
+        refresh_payload,
+        namespace,
+        JWTSessions.custom_refresh_expiration(@_refresh_exp)
+      )
       @refresh_token = @_refresh.token
       link_access_to_refresh
     end
 
     def create_access_token
-      @_access = AccessToken.create(@_csrf.encoded, payload, store)
+      @_access = AccessToken.create(
+        @_csrf.encoded,
+        payload,
+        store,
+        JWTSessions.custom_access_expiration(@_access_exp)
+      )
       @access_token = @_access.token
     end
   end

data/lib/jwt_sessions/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module JWTSessions
-  VERSION = "2.3.1"
+  VERSION = "2.4.0"
 end

data/test/units/jwt_sessions/test_session.rb

@@ -27,6 +27,18 @@ class TestSession < Minitest::Test
     assert_equal payload[:test], decoded_access["test"]
   end
 
+  def test_login_with_custom_exp
+    @new_session = JWTSessions::Session.new(
+      payload: payload,
+      access_exp: 18000, # 5 hours in seconds
+      refresh_exp: 18000
+    )
+    assert_equal false, tokens[:refresh_expires_at] == tokens[:access_expires_at]
+    new_tokens = @new_session.login
+    assert_equal LOGIN_KEYS, new_tokens.keys.sort
+    assert_equal new_tokens[:refresh_expires_at], new_tokens[:access_expires_at]
+  end
+
   def test_refresh
     refreshed_tokens = session.refresh(tokens[:refresh])
     decoded_access = JWTSessions::Token.decode(refreshed_tokens[:access]).first
@@ -34,6 +46,18 @@ class TestSession < Minitest::Test
     assert_equal payload[:test], decoded_access["test"]
   end
 
+  def test_refresh_with_custom_exp
+    @new_session = JWTSessions::Session.new(
+      payload: payload,
+      access_exp: 18000, # 5 hours in seconds
+      refresh_exp: 18000
+    )
+    new_tokens = @new_session.login
+    refreshed_tokens = @new_session.refresh(new_tokens[:refresh])
+    assert_equal LOGIN_KEYS, new_tokens.keys.sort
+    assert_equal refreshed_tokens[:refresh_expires_at], refreshed_tokens[:access_expires_at]
+  end
+
   def test_refresh_expired
     JWTSessions.refresh_exp_time = 0
     session = JWTSessions::Session.new(payload: payload)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jwt_sessions
 version: !ruby/object:Gem::Version
-  version: 2.3.1
+  version: 2.4.0
 platform: ruby
 authors:
 - Yulia Oletskaya
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-02-01 00:00:00.000000000 Z
+date: 2019-05-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jwt