keycloak_rack 1.0.0

data/lib/keycloak_rack/flexible_struct.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module KeycloakRack
+  # @abstract
+  class FlexibleStruct < Dry::Struct
+    transform_keys(&:to_sym)
+
+    transform_types do |type|
+      # :nocov:
+      if type.default?
+        type.constructor do |value|
+          value.nil? ? Dry::Types::Undefined : value
+        end
+      else
+        type
+      end
+      # :nocov:
+    end
+  end
+end

data/lib/keycloak_rack/http_client.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module KeycloakRack
+  # @note Adapted from monadic HTTP client in another project
+  # @api private
+  class HTTPClient
+    include Dry::Monads[:do, :result]
+
+    include Import[config: "keycloak-rack.config", server_url: "keycloak-rack.server_url", x509_store: "keycloak-rack.x509_store"]
+
+    # @param [String] realm_id
+    # @param [String] path
+    # @return [Dry::Monads::Success(Net::HTTPSuccess)] on a successful request
+    # @return [Dry::Monads::Failure(Symbol, String, Net::HTTPResponse)] on a failure
+    def get(realm_id, path)
+      uri = build_uri realm_id, path
+
+      request = Net::HTTP::Get.new(uri)
+
+      call request
+    end
+
+    # @param [String] realm_id
+    # @param [String] path
+    # @return [Dry::Monads::Success({ Symbol => Object })] on a successful request
+    # @return [Dry::Monads::Failure(:invalid_response, String, Net::HTTPResponse)] if the JSON fails to parse
+    # @return [Dry::Monads::Failure(Symbol, String, Net::HTTPResponse)] on a failure
+    def get_json(realm_id, path)
+      response = yield get realm_id, path
+
+      parse_json response
+    end
+
+    # @param [Net::HTTPRequest] request
+    # @return [Dry::Monads::Success(Net::HTTPSuccess)] on a successful request
+    # @return [Dry::Monads::Failure(Symbol, String, Net::HTTPResponse)] on a failure
+    def call(request)
+      # :nocov:
+      return Failure[:invalid_request, "Not a request: #{request.inspect}", nil] unless request.kind_of?(Net::HTTPRequest)
+
+      uri = request.uri
+
+      use_ssl = uri.scheme != "http"
+      # :nocov:
+
+      Net::HTTP.start(uri.host, uri.port, use_ssl: use_ssl, cert_store: x509_store) do |http|
+        response = http.request request
+
+        # :nocov:
+        case response
+        when Net::HTTPSuccess then Success response
+        when Net::HTTPBadRequest then Failure[:bad_request, "Bad Request", response]
+        when Net::HTTPUnauthorized then Failure[:unauthorized, "Unauthorized", response]
+        when Net::HTTPForbidden then Failure[:forbidden, "Forbidden", response]
+        when Net::HTTPNotFound then Failure[:not_found, "Not Found: #{uri}", response]
+        when Net::HTTPGatewayTimeout then Failure[:gateway_timeout, "Gateway Timeout", response]
+        when Net::HTTPClientError then Failure[:client_error, "Client Error: HTTP #{response.code}", response]
+        when Net::HTTPServerError then Failure[:server_error, "Server Error: HTTP #{response.code}", response]
+        else
+          Failure[:unknown_error, "Unknown Error", response]
+        end
+        # :nocov:
+      end
+    end
+
+    private
+
+    # @param [String] realm_id
+    # @param [String] path
+    # @return [URI]
+    def build_uri(realm_id, path)
+      string_uri = File.join(server_url, "realms", realm_id, path)
+
+      URI(string_uri)
+    end
+
+    # @param [Net::HTTPResponse] response
+    # @return [Dry::Monads::Sucess({ Symbol => Object })] the deserialized JSON, should more or less always be a hash
+    # @return [Dry::Monads::Failure(:invalid_response, String, Net::HTTPResponse)] if the JSON fails to parse
+    def parse_json(response)
+      Success JSON.parse response.body, symbolize_names: true
+    rescue JSON::ParserError => e
+      Failure[:invalid_response, "Response was not valid JSON: #{e.message}", response]
+    end
+  end
+end

data/lib/keycloak_rack/import.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module KeycloakRack
+  # Dependency injection injector
+  #
+  # @api private
+  # @!visibility private
+  Import = Dry::AutoInject(Container)
+end

data/lib/keycloak_rack/key_fetcher.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module KeycloakRack
+  # Fetches the public key for a keycloak installation.
+  #
+  # @api private
+  class KeyFetcher
+    include Import[config: "keycloak-rack.config", http_client: "keycloak-rack.http_client"]
+
+    delegate :realm_id, to: :config
+
+    # @return [Dry::Monads::Success({ Symbol => Object })]
+    # @return [Dry::Monads::Failure(Symbol, String)]
+    def find_public_keys
+      http_client.get_json(realm_id, "protocol/openid-connect/certs").or do |(code, reason, response)|
+        Dry::Monads::Result::Failure[:invalid_public_keys, "Could not fetch public keys: #{reason.inspect}"]
+      end
+    end
+  end
+end

data/lib/keycloak_rack/key_resolver.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module KeycloakRack
+  # A caching resolver that wraps around {KeycloakRack::KeyFetcher} to cache its result
+  # for {KeycloakRack::Config#cache_ttl} seconds (default: 1.day)
+  #
+  # @api private
+  class KeyResolver
+    include Import[config: "keycloak-rack.config", fetcher: "keycloak-rack.key_fetcher"]
+
+    delegate :cache_ttl, to: :config
+
+    # @!attribute [r] cached_public_key_retrieved_at
+    # @return [ActiveSupport::TimeWithZone]
+    attr_reader :cached_public_key_retrieved_at
+
+    # @!attribute [r] cached_public_keys
+    # @return [Dry::Monads::Success({ Symbol => <{ Symbol => String }> })]
+    # @return [Dry::Monads::Failure]
+    attr_reader :cached_public_keys
+
+    def initialize(**)
+      super
+
+      @cached_public_keys = Dry::Monads.Failure("nothing fetched yet")
+      @cached_public_key_retrieved_at = 1.year.ago
+    end
+
+    # @see KeycloakRack::PublicKeyResolver#find_public_keys
+    # @return [Dry::Monads::Success({ Symbol => Object })]
+    # @return [Dry::Monads::Failure(Symbol, String)]
+    def find_public_keys
+      fetch! if should_refetch?
+
+      @cached_public_keys
+    end
+
+    def has_failed_fetch?
+      @cached_public_keys.failure?
+    end
+
+    def has_outdated_cache?
+      Time.current > @cached_public_key_expires_at
+    end
+
+    # @return [void]
+    def refresh!
+      fetch!
+    end
+
+    def should_refetch?
+      has_failed_fetch? || has_outdated_cache?
+    end
+
+    private
+
+    # @return [void]
+    def fetch!
+      @cached_public_keys = fetcher.find_public_keys
+      @cached_public_key_retrieved_at = Time.current
+      @cached_public_key_expires_at = @cached_public_key_retrieved_at + cache_ttl.seconds
+    end
+  end
+end

data/lib/keycloak_rack/middleware.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module KeycloakRack
+  # Rack middleware that calls {KeycloakRack::Authenticate} to process a keycloak token.
+  #
+  # Upon successful processing, it populates the following values into the rack environment
+  # for consumption later down the stack:
+  #
+  # - `keycloak:session`: An instance of {KeycloakRack::Session} that serves as the primary interface
+  # - `keycloak:authorize_realm`: An instance of {KeycloakRack::AuthorizeRealm} for authorizing realm-level roles
+  # - `keycloak:authorize_resource`: An instance of {KeycloakRack::AuthorizeResource} for authorizing resource-level roles
+  class Middleware
+    include Dry::Monads[:result]
+
+    include Import[authenticate: "keycloak-rack.authenticate", config: "keycloak-rack.config"]
+
+    # @param [#call] app the next component in the rack middleware stack
+    def initialize(app, **options)
+      super(**options)
+
+      @app = app
+    end
+
+    # Process the rack environment and inject the gem's interfaces into it.
+    #
+    # If the authentication is a monadic failure, and {KeycloakRack::Config#halt_on_auth_failure halt_on_auth_failure}
+    # is true, then it will short-circuit with {#authentication_failed}.
+    #
+    # @param [Hash] env the rack environment
+    # @return [Object]
+    def call(env)
+      result = authenticate.call(env)
+
+      return authentication_failed(env, result) if halt?(result)
+
+      session_opts = { skipped: false, auth_result: result }
+
+      case result
+      in Success[:authenticated, decoded_token]
+        session_opts[:token] = decoded_token
+      in Success[:skipped]
+        session_opts[:skipped] = true
+      else
+        # nothing to do
+      end
+
+      env["keycloak:session"] = session = KeycloakRack::Session.new(**session_opts)
+      env["keycloak:authorize_realm"] = session.authorize_realm
+      env["keycloak:authorize_resource"] = session.authorize_resource
+
+      @app.call(env)
+    end
+
+    private
+
+    # Build the authentication failure when short-circuiting.
+    #
+    # @note See {#build_failure_headers} and {#build_failure_body} for opportunities
+    #   to override.
+    # @param [Hash] env the rack environment
+    # @param [Dry::Monads::Result] monad
+    # @return [(Integer, { String => String }, <String>)] rack response
+    def authentication_failed(env, monad)
+      status = build_failure_status env, monad
+
+      headers = build_failure_headers env, monad
+
+      body = build_failure_body env, monad
+
+      # :nocov:
+      body = body.to_json unless body.kind_of?(String)
+      # :nocov:
+
+      [
+        status,
+        headers,
+        [ body ]
+      ]
+    end
+
+    def build_failure_status(env, monad)
+      case monad
+      in Failure[:no_token, _]
+        401
+      in Failure[:expired, String, String, Exception]
+        403
+      in Failure[Symbol, String, String, Exception]
+        400
+      else
+        500
+        # nothing to do
+      end
+    end
+
+    # @todo Make customizable
+    # @param [Hash] env the rack environment
+    # @param [Dry::Monads::Result] monad
+    # @return [{ String => String }]
+    def build_failure_headers(env, monad)
+      {
+        "Content-Type" => "application/json"
+      }
+    end
+
+    # @todo Make customizable
+    # @note Currently uses GraphQL error format.
+    # @param [Hash] env the rack environment
+    # @param [Dry::Monads::Result] monad
+    # @return [String, #to_json]
+    def build_failure_body(env, monad)
+      _reason, message, _token, _original_error = monad.failure
+
+      {
+        errors: [
+          {
+            message: message,
+            extensions: {
+              code: "UNAUTHENTICATED"
+            }
+          }
+        ]
+      }
+    end
+
+    # @param [Dry::Monads::Result] result
+    def halt?(result)
+      return false unless result.failure?
+
+      config.halt_on_auth_failure?
+    end
+  end
+end

data/lib/keycloak_rack/railtie.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module KeycloakRack
+  # Railtie that gets autoloaded when Rails is detected in the environment.
+  #
+  # @api private
+  class Railtie < Rails::Railtie
+    railtie_name :keycloak_rack
+
+    initializer("keycloak_rack.insert_middleware") do |app|
+      app.config.middleware.use(KeycloakRack::Middleware)
+    end
+  end
+end

data/lib/keycloak_rack/read_token.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module KeycloakRack
+  # Read the bearer token from the `Authorization` token.
+  #
+  # @api private
+  class ReadToken
+    include Dry::Monads[:result]
+
+    include Import[config: "keycloak-rack.config"]
+
+    # The pattern to match bearer tokens with.
+    BEARER_TOKEN = /\ABearer (?<token>.+)\z/i.freeze
+
+    # @param [Hash, #[]] env
+    # @return [Dry::Monads::Success(String)] when a token is found
+    # @return [Dry::Monads::Success(nil)] when a token is not found, but unauthenticated requests are allowed
+    # @return [Dry::Monads::Failure(:no_token, String)]
+    def call(env)
+      found_token = read_from env
+
+      return Success(found_token) if found_token.present?
+
+      return Success(nil) if config.allow_anonymous?
+
+      Failure[:no_token, "No JWT provided"]
+    end
+
+    private
+
+    # @param [Hash] env the rack environment
+    # @option env [String] "HTTP_AUTHORIZATION" the Authorization header
+    # @return [String, nil]
+    def read_from(env)
+      match = BEARER_TOKEN.match env["HTTP_AUTHORIZATION"]
+
+      match&.[](:token)
+    end
+  end
+end

data/lib/keycloak_rack/resource_role_map.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module KeycloakRack
+  # A type to define a map of {RoleMap}s keyed by resource type.
+  #
+  # @api private
+  ResourceRoleMap = Types::Hash.map(Types::String, RoleMap).default { { "account" => {} } }
+end

data/lib/keycloak_rack/role_map.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module KeycloakRack
+  # PORO to interface with Keycloak roles.
+  class RoleMap < KeycloakRack::FlexibleStruct
+    # @!attribute [r] roles
+    # @return [<String>]
+    attribute :roles, Types::StringList
+
+    # @param [#to_s] name
+    def has_role?(name)
+      name.to_s.in? roles
+    end
+  end
+end

data/lib/keycloak_rack/session.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module KeycloakRack
+  # This serves as the primary interface for interacting with Rack and Rails applications,
+  # and an instance gets mounted into `keycloak:session` when the middleware processes.
+  class Session
+    extend Dry::Initializer
+
+    include Dry::Matcher.for(:authenticate!, with: Dry::Matcher::ResultMatcher)
+
+    option :auth_result, Types.Instance(Dry::Monads::Result)
+    option :skipped, Types::Bool, default: proc { false }
+    option :token, Types.Instance(KeycloakRack::DecodedToken).optional, optional: true
+    option :authorize_realm, Types.Interface(:call), default: proc { KeycloakRack::AuthorizeRealm.new self }
+    option :authorize_resource, Types.Interface(:call), default: proc { KeycloakRack::AuthorizeResource.new self }
+
+    delegate :has_realm_role?, :has_resource_role?, to: :token, allow_nil: true
+
+    alias skipped? skipped
+
+    # @return [Dry::Monads::Result]
+    def authenticate!
+      auth_result
+    end
+
+    # @return [Dry::Monads::Result]
+    def authorize_realm!(*args)
+      authorize_realm.call(*args)
+    end
+
+    # @return [Dry::Monads::Result]
+    def authorize_resource!(*args)
+      authorize_resource.call(*args)
+    end
+
+    def authenticated?
+      auth_result.success? && token.present?
+    end
+
+    def anonymous?
+      auth_result.success? && token.blank?
+    end
+  end
+end