grape-jwt-authentication 1.0.1

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "grape/jwt/authentication"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/grape-jwt-authentication.gemspec

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'grape/jwt/authentication/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'grape-jwt-authentication'
+  spec.version       = Grape::Jwt::Authentication::VERSION
+  spec.authors       = ['Hermann Mayer']
+  spec.email         = ['hermann.mayer92@gmail.com']
+
+  spec.summary       = 'A reusable Grape JWT authentication concern'
+  spec.description   = 'A reusable Grape JWT authentication concern'
+  spec.homepage      = 'https://github.com/hausgold/grape-jwt-authentication'
+
+  spec.files = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_development_dependency 'bundler', '~> 1.16'
+  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'rspec', '~> 3.0'
+  spec.add_development_dependency 'simplecov', '~> 0.15'
+  spec.add_development_dependency 'vcr', '~> 3.0'
+  spec.add_development_dependency 'webmock', '~> 3.1'
+  spec.add_development_dependency 'timecop', '~> 0.9.1'
+  spec.add_development_dependency 'rack', '~> 2.0'
+  spec.add_development_dependency 'rack-test', '~> 0.8.2'
+
+  spec.add_runtime_dependency 'activesupport', '>= 3.2.0'
+  spec.add_runtime_dependency 'grape', '~> 1.0'
+  spec.add_runtime_dependency 'httparty'
+  spec.add_runtime_dependency 'jwt', '~> 2.1'
+  spec.add_runtime_dependency 'recursive-open-struct', '~> 1.0'
+end

data/lib/grape/jwt/authentication.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require 'active_support'
+require 'active_support/concern'
+require 'active_support/configurable'
+require 'active_support/cache'
+require 'active_support/core_ext/hash'
+require 'active_support/time'
+require 'active_support/time_with_zone'
+
+require 'jwt'
+
+require 'grape'
+require 'grape/jwt/authentication/version'
+require 'grape/jwt/authentication/configuration'
+require 'grape/jwt/authentication/jwt_handler'
+require 'grape/jwt/authentication/jwt'
+require 'grape/jwt/authentication/rsa_public_key'
+
+module Grape
+  module Jwt
+    # The Grape JWT authentication concern.
+    module Authentication
+      extend ActiveSupport::Concern
+      include Grape::DSL::API
+
+      class << self
+        attr_writer :configuration
+      end
+
+      # Retrieve the current configuration object.
+      #
+      # @return [Configuration]
+      def self.configuration
+        @configuration ||= Configuration.new
+      end
+
+      # Configure the concern by providing a block which takes
+      # care of this task. Example:
+      #
+      #   Grape::Jwt::Authentication.configure do |conf|
+      #     # conf.xyz = [..]
+      #   end
+      def self.configure
+        yield(configuration)
+      end
+
+      # Reset the current configuration with the default one.
+      def self.reset_configuration!
+        self.configuration = Configuration.new
+      end
+
+      included do
+        # Configure a new Grape authentication strategy which will be
+        # backed by the JwtHandler middleware. We do not want
+        # gem-internal claim verification or database lookup
+        # functionality. Let the user handle this the way he want.
+        Grape::Middleware::Auth::Strategies.add(:jwt,
+                                                JwtHandler,
+                                                ->(opts) { [opts] })
+      end
+    end
+  end
+end

data/lib/grape/jwt/authentication/configuration.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module Grape
+  module Jwt
+    module Authentication
+      # The configuration for the Grape JWT authentication concern.
+      class Configuration
+        include ActiveSupport::Configurable
+
+        # The authenticator function which must be defined by the user to
+        # verify the given JSON Web Token. Here comes all your logic to lookup
+        # the related user on your database, the token claim verification
+        # and/or the token cryptographic signing. The function must return true
+        # or false to indicate the validity of the token.
+        #
+        #   Grape::Jwt::Authentication.configure do |conf|
+        #     conf.authenticator = proc do |token|
+        #       # Verify the token the way you like.
+        #     end
+        #   end
+        config_accessor(:authenticator) { proc { false } }
+
+        # Whenever the given value on the +Authorization+ header is not a valid
+        # Bearer authentication scheme or the token itself is not a valid JSON
+        # Web Token, this user defined function will be called. You can add
+        # custom handling of this situations, like responding different HTTP
+        # status code, or bodies. By default the Rack stack will be interrupted
+        # and a response with the 400 Bad Request status code will be send to
+        # the client. The raw token (value of the +Authorization+ header) and
+        # the Rack app will be injected to your function for maximum
+        # flexibility.
+        #
+        #   Grape::Jwt::Authentication.configure do |conf|
+        #     conf.malformed_auth_handler = proc do |raw_token, app|
+        #       # Do your own error handling.
+        #     end
+        #   end
+        config_accessor(:malformed_auth_handler) do
+          proc do |_raw_token, _app|
+            [400, {}, ['Authorization header is malformed.']]
+          end
+        end
+
+        # When the client sends a corrected formatted JSON Web Token with the
+        # Bearer authentication scheme within the +Authorization+ header and
+        # your authenticator fails for some reason (token claims, wrong
+        # audience, bad subject, expired token, wrong cryptographic signing
+        # etc), this function is called to handle the bad authentication. By
+        # default the Rack stack will be interrupted and a response with the
+        # 401 Unauthorized status code will be send to the client. You can
+        # customize this the way you like and send different error codes, or
+        # handle the error completely different. The parsed JSON Web Token and
+        # the Rack app will be injected to your function to allow any
+        # customized error handling.
+        #
+        #   Grape::Jwt::Authentication.configure do |conf|
+        #     conf.failed_auth_handler = proc do |token, app|
+        #       # Do your own error handling.
+        #     end
+        #   end
+        config_accessor(:failed_auth_handler) do
+          proc do |_token, _app|
+            [401, {}, ['Access denied.']]
+          end
+        end
+
+        # Whenever you want to use the {RsaPublicKey} class you configure the
+        # default URL on the singleton instance, or use the gem configure
+        # method and set it up accordingly.  We allow the fetch of the public
+        # key from a remote server (HTTP/HTTPS) or from a local file which is
+        # accessible by the ruby process.  Specify the URL or the local path
+        # here.
+        config_accessor(:rsa_public_key_url) { nil }
+
+        # You can preconfigure the {RsaPublickey} class to enable/disable
+        # caching. For a remote public key location it is handy to cache the
+        # result for some time to keep the traffic low to this resource server.
+        # For a local file you can skip this.
+        config_accessor(:rsa_public_key_caching) { false }
+
+        # When you make use of the caching of the {RsaPublicKey} class you can
+        # fine tune the expiration time of this cache. The RSA public key from
+        # your identity provider should not change this frequent, so a cache
+        # for at least one hour is fine. You should not set it lower than one
+        # minute. Keep this setting in mind when you change keys. Your
+        # infrastructure could be inoperable for this configured time.
+        config_accessor(:rsa_public_key_expiration) { 1.hour }
+
+        # The JSON Web Token isser which should be used for verification.
+        config_accessor(:jwt_issuer) { nil }
+
+        # The resource server (namely the one which configures this right now)
+        # which MUST be present on the JSON Web Token audience claim.
+        config_accessor(:jwt_beholder) { nil }
+
+        # You can configure a different JSON Web Token verification option hash
+        # if your algorithm differs or you want some extra/different options.
+        # Just watch out that you have to pass a proc to this configuration
+        # property. On the {Grape::Jwt::Authentication::Jwt} class it has to be
+        # a simple hash. The default is here the RS256 algorithm with enabled
+        # expiration check, and issuer+audience check when the
+        # {jwt_issuer}/{jwt_beholder} are configured accordingly.
+        config_accessor(:jwt_options) do
+          proc do
+            conf = Grape::Jwt::Authentication.configuration
+            { algorithm: 'RS256',
+              exp_leeway: 30.seconds.to_i,
+              iss: conf.jwt_issuer,
+              verify_iss: !conf.jwt_issuer.nil?,
+              aud: conf.jwt_beholder,
+              verify_aud: !conf.jwt_beholder.nil?,
+              # @TODO: https://github.com/jwt/ruby-jwt/issues/247
+              verify_iat: false }
+          end
+        end
+
+        # You can configure your own verification key on the Jwt wrapper class.
+        # This way you can pass your HMAC secret or your ECDSA public key to
+        # the JSON Web Token validation method. Here you need to pass a proc,
+        # on the {Grape::Jwt::Authentication::Jwt} class it has to be a scalar
+        # value. By default we use the
+        # {Grape::Jwt::Authentication::RsaPublicKey} class to retrieve the RSA
+        # public key.
+        config_accessor(:jwt_verification_key) do
+          proc { RsaPublicKey.instance.fetch }
+        end
+      end
+    end
+  end
+end

data/lib/grape/jwt/authentication/jwt.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require 'recursive-open-struct'
+
+module Grape
+  module Jwt
+    module Authentication
+      # A easy to use model for verification of JSON Web Tokens. This is just a
+      # wrapper class for the excellent ruby-jwt gem. It's completely up to you
+      # to use it. But be aware, its a bit optinionated by default.
+      class Jwt
+        # All the following JWT verification issues lead to a failed validation.
+        RESCUE_JWT_EXCEPTIONS = [
+          ::JWT::DecodeError,
+          ::JWT::VerificationError,
+          ::JWT::ExpiredSignature,
+          ::JWT::IncorrectAlgorithm,
+          ::JWT::ImmatureSignature,
+          ::JWT::InvalidIssuerError,
+          ::JWT::InvalidIatError,
+          ::JWT::InvalidAudError,
+          ::JWT::InvalidSubError,
+          ::JWT::InvalidJtiError,
+          ::JWT::InvalidPayload
+        ].freeze
+
+        # :reek:Attribute because its fine to be extern-modifiable at these
+        # instances
+        attr_reader :payload, :token
+        attr_writer :verification_key, :jwt_options
+        attr_accessor :issuer, :beholder
+
+        # Setup a new JWT instance. You have to pass the raw JSON Web Token to
+        # the initializer. Example:
+        #
+        #   Jwt.new('j.w.t')
+        #   # => <Jwt>
+        #
+        # @return [Jwt]
+        def initialize(token)
+          parsed_payload = JWT.decode(token, nil, false).first.symbolize_keys
+          @token = token
+          @payload = RecursiveOpenStruct.new(parsed_payload)
+        end
+
+        # Checks if the payload says this is a refresh token.
+        #
+        # @return [Boolean] Whenever this is a access token
+        def access_token?
+          payload.typ == 'access'
+        end
+
+        # Checks if the payload says this is a refresh token.
+        #
+        # @return [Boolean] Whenever this is a refresh token
+        def refresh_token?
+          payload.typ == 'refresh'
+        end
+
+        # Retrives the expiration date from the payload when set.
+        #
+        # @return [nil|ActiveSupport::TimeWithZone] The expiration date
+        def expires_at
+          exp = payload.exp
+          return nil unless exp
+          Time.zone.at(exp)
+        end
+
+        # Deliver the public key for verification by default. This uses the
+        # {RsaPublicKey} class, but you can configure the verification key the
+        # way you like. (Especially for different algorithms, like HMAC or
+        # ECDSA) Just make use of the same named setter.
+        #
+        # @return [OpenSSL::PKey::RSA|Mixed] The verification key
+        def verification_key
+          unless @verification_key
+            conf = Grape::Jwt::Authentication.configuration
+            return conf.jwt_verification_key.call
+          end
+          @verification_key
+        end
+
+        # This getter passes back the default JWT verification option hash
+        # which is optinionated.  You can change this the way you like by
+        # configuring your options with the help of the same named setter.
+        #
+        # @return [Hash] The JWT verification options hash
+        def jwt_options
+          unless @jwt_options
+            conf = Grape::Jwt::Authentication.configuration
+            return conf.jwt_options.call
+          end
+          @jwt_options
+        end
+
+        # Verify the current token by our hard and strict rules. Whenever the
+        # token was not parsed from a string, we encode the current state to a
+        # JWT string representation and check this.
+        #
+        # @return [Boolean] Whenever the token is valid or not
+        #
+        # :reek:NilCheck because we have to check the token
+        #                origin and react on it
+        def valid?
+          JWT.decode(token, verification_key, true, jwt_options) && true
+        rescue *RESCUE_JWT_EXCEPTIONS
+          false
+        end
+      end
+    end
+  end
+end

data/lib/grape/jwt/authentication/jwt_handler.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Grape
+  module Jwt
+    module Authentication
+      # Take care of the token validation and verification on this
+      # Rack middleware. It is a self contained implementation of a
+      # valid Rack handler which checks for a common JWT token
+      # Authorization header and calls a user given verification block
+      # which performs the database lookup or whatever is necessary
+      # for the verification.
+      class JwtHandler
+        # A internal exception handling for failed authentications.
+        class AuthenticationError < StandardError; end
+        # A internal exception handling for malformed headers.
+        class MalformedHeaderError < StandardError; end
+
+        # A common JWT validation regex which meets the RFC specs.
+        JWT_REGEX = /^[a-zA-Z0-9\-_]+?\.[a-zA-Z0-9\-_]+?\.([a-zA-Z0-9\-_]+)?$/
+
+        # Initialize a new Rack middleware for Bearer token
+        # processing.
+        #
+        # @param app [Proc] The regular Rack application
+        # @param options [Hash] A global-overwritting configuration hash
+        def initialize(app, options = {})
+          @app = app
+          @options = options
+        end
+
+        # A shared configuration lookup helper which selects the requested
+        # entry from the local or global configuration object.  The local
+        # configuration takes presedence over the global one.
+        #
+        # @param key [Symbol] The local config key
+        # @param global_key [Symbol] The global config key
+        # @return [Mixed] The configuration value
+        def config(key, global_key)
+          block = @options[key]
+          unless block
+            global_conf = Grape::Jwt::Authentication.configuration
+            return global_conf.send(global_key)
+          end
+          block
+        end
+
+        # Get the local or global defined authenticator for the JWT handler.
+        #
+        # @return [Proc] The authenticator block
+        def authenticator
+          config(:proc, :authenticator)
+        end
+
+        # Get the local or global defined malformed authentication handler for
+        # the JWT handler.
+        #
+        # @return [Proc] The malformed authorization handler block
+        def malformed_handler
+          config(:malformed, :malformed_auth_handler)
+        end
+
+        # Get the local or global defined failed authentication handler for the
+        # JWT handler.
+        #
+        # @return [Proc] The failed authentication handler block
+        def failed_handler
+          config(:failed, :failed_auth_handler)
+        end
+
+        # Validate the Bearer authentication scheme on the given
+        # authorization header and validate the JWT token when it was
+        # found.
+        #
+        # @param header [String] The authorization header value
+        # @return [String] The parsed and well-formatted JWT
+        def parse_token(header)
+          token = header.to_s.scan(/^Bearer (.*)/).flatten.first
+          raise MalformedHeaderError unless JWT_REGEX =~ token
+          token
+        end
+
+        # Perform the authentication logic on the Rack compatible
+        # interface.
+        #
+        # :reek:TooManyStatements because reek counts exception
+        #                         handling as statements
+        def call(env)
+          # Unfortunately Grape's middleware stack orders the error
+          # handling higher than the formatter. So when a error is
+          # raised, the Rack env was not yet analysed and the content
+          # type not negotiated. This would result in allways-JSON
+          # responses on authentication errors. We want to be smarter
+          # here and respond in the requested format on authentication
+          # errors, that why we invoke the formatter middleware here.
+          Grape::Middleware::Formatter.new(->(_) {}).call(env)
+
+          # Parse the JWT token and give it to the user defined block
+          # for futher verification. The user given block MUST return
+          # a positive result to allow the request to be further
+          # processed, or a negative result to stop processing.
+          token = parse_token(env['HTTP_AUTHORIZATION'])
+          raise AuthenticationError unless authenticator.call(token)
+
+          # Looks like we are on a good path and the given token was
+          # valid on all checks. So we continue the regular
+          # application logic now.
+          @app.call(env)
+        rescue MalformedHeaderError
+          # Call the user defined malformed authentication handler.
+          malformed_handler.call(env['HTTP_AUTHORIZATION'], @app)
+        rescue AuthenticationError
+          # Call the user defined failed authentication handler.
+          failed_handler.call(token, @app)
+        end
+      end
+    end
+  end
+end