jwt_sessions Ruby Gem

jwt_sessions provides configurable, manageable, and safe stateful sessions based on JSON Web Tokens (JWT).

Key features include:

• Backend Session Storage: Stores session state in Redis or memory to enable reliable logout and session management.
• Framework Agnostic: Can be used in any Ruby application, with built-in integration for Rails.
• JWT Standard Compliance: Uses the ruby-jwt gem for encoding/decoding, supporting standard claims and various cryptographic signing algorithms. By default, it uses the ext claim and HS256 signing.

When using cookies for token transport, the gem provides CSRF protection. The login and refresh methods of JWTSessions::Session return a :csrf token.

Usage:

1. The client must send this CSRF token in a header (defaulting to X-CSRF-Token) for all non-GET/HEAD requests.
2. The Authorization mixin automatically verifies this token against the one stored in the session.
3. If a mismatch occurs, JWTSessions::Errors::Unauthorized is raised.

You can manually generate a masked token using session.masked_csrf(access_token) to mitigate BREACH attacks.

# Example: Rendering CSRF in a Rails controller
render json: { csrf: tokens[:csrf] }

The core concept of jwt_sessions is a dual-token system where each session is represented by a pair of tokens:

1. Access Token: Used to retrieve secure resources. It typically has a shorter lifespan.
2. Refresh Token: Used to renew the access token once it has expired. It typically has a longer lifespan.

To ensure security (XSS/CSRF protection) and allow for reliable session management (like logging out users or resetting passwords), the gem uses a backend session store (supporting Redis and memory) to handle CSRF checks and prevent refresh token hijacking.

For non-Rails frameworks (like Sinatra), include JWTSessions::Authorization in your class and implement three required methods to allow the gem to extract request data:

1. request_headers: Must return a hash-like object of request headers.
2. request_cookies: Must return a hash-like object of request cookies.
3. request_method: Must return the current request verb as an uppercase string (e.g., 'GET', 'POST').

class SimpleApp < Sinatra::Base
  include JWTSessions::Authorization

  def request_headers
    env.inject({}) { |acc, (k,v)| acc[$1.downcase] = v if k =~ /^http_(.*)/i; acc }
  end

  def request_cookies
    request.cookies
  end

  def request_method
    request.request_method
  end
end

Before using the gem, you must configure a signing algorithm and a key. By default, it uses HS256. For HMAC algorithms, you can use the signing_key shortcut. For asymmetric algorithms like RS256, you must specify both private_key and public_key.

# For HMAC (e.g., HS256)
JWTSessions.algorithm = "HS256"
JWTSessions.signing_key = "secret"

# For RSA (e.g., RS256)
JWTSessions.algorithm   = "RS256"
JWTSessions.private_key = OpenSSL::PKey::RSA.generate(2048)
JWTSessions.public_key  = JWTSessions.private_key.public_key

To install jwt_sessions, add the following line to your Gemfile and run bundle install.

gem "jwt_sessions"

bundle install

The library requires RbNaCl and the sodium cryptographic library for cryptographic operations. If you are developing on MacOS and need to install the required system dependency, you can use Homebrew.

brew install libsodium

By default, the gem only verifies the exp (expiration) claim. You can enable verification for other claims globally via JWTSessions.jwt_options.

Global Options:

• verify_iss: Verify Issuer.
• verify_sub: Verify Subject.
• verify_iat: Verify Issued At.
• verify_aud: Verify Audience.
• leeway: Global clock skew allowance in seconds.

Controller-level Overrides: To pass specific claims (like sub, aud, iss) or custom leeways for a specific request, implement a token_claims method in your controller.

# Global configuration
JWTSessions.jwt_options[:verify_iss] = true
JWTSessions.jwt_options[:leeway]     = 30

# Controller-level override
class UsersController < ApplicationController
  def token_claims
    {
      aud: ["admin", "staff"],
      verify_aud: true,
      exp_leeway: 15
    }
  end
end

When initializing JWTSessions::Session.new, the following options are available:

• payload: Hash of session data for the access token. (Default: {})
• refresh_payload: Hash of session data for the refresh token. (Default: same as payload)
• access_claims: Hash of JWT claims to validate in the access token.
• refresh_claims: Hash of JWT claims to validate in the refresh token.
• namespace: String used to group sessions (e.g., by user ID) to enable features like global logout.
• refresh_by_access_allowed: Boolean. If true, allows refreshing a session using the last expired access token.
• access_exp: Integer. Access token expiration in seconds (overrides global settings).
• refresh_exp: Integer. Refresh token expiration in seconds (overrides global settings).