verikloak 0.1.4 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3b7e22a96384ccea0cb43c2c611f7106d0e88b23793279f2ee105d68da226bb0
-  data.tar.gz: d83ba8ebe7834895d1a3f6e39c26dae02713611fc767177c909987ef1111cf50
+  metadata.gz: d175a574b17bd1ce5e096dbb69769d12a470f49c8444a5246881afd61d06fa52
+  data.tar.gz: 3c59a660bb142c194b6e0db2d338952c41c8a88afc479382203b4d767ab7691c
 SHA512:
-  metadata.gz: 40481fc255490d0c22c2808cf00e8c0e136488f755e6dc2e388c4ab81978975c6ee478a2916d61fe564bd25984898f74ddeccacfe1ae8006a081b3bfc441bc41
-  data.tar.gz: 0aaf942838e33a618197d0fb6d5446c6a9ffaa5b529db50902f2ab403b884b03ee0c87bdf8c99e4c8b069cad1f566026bb05fb16ab3583339493a4891eeb4f88
+  metadata.gz: 92edd8a2df134f115c3f887683246278c5778291bb86bfff22ebc873b2b92d6ff09d9c85a1f798e2f49caa09adc8c3ef18ffc83309f95799997ebbdb54b58228
+  data.tar.gz: 0e223f0055e69448899be53fc22c9ac32c5d43c410aa041daa38761ed13a00aae8d655bcb6eaff521927a5a029937fcd480c7b90dcfccddf8e6b028aaf0bf555

data/CHANGELOG.md

@@ -7,6 +7,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [0.2.0] - 2025-09-22
+
+### Added
+- Middleware options `token_env_key` and `user_env_key` for customizing where the token and decoded claims are stored in the Rack env.
+- Middleware option `realm` to change the `WWW-Authenticate` realm value emitted on 401 responses.
+- Middleware option `logger` so unexpected internal errors can be sent to the host application's logger instead of STDERR.
+
+### Changed
+- Update gem version to 0.2.0 to stay aligned with the rest of the Verikloak ecosystem gems.
+
+---
+
+## [0.1.5] - 2025-09-21
+
+### Added
+- Specs for `Verikloak::HTTP.default_connection`, ensuring retry middleware and timeout defaults stay in sync.
+
+### Changed
+- Middleware audience callables now handle zero-arity and BasicObject-style implementations without relying on `method(:call)`.
+- README documents the shared `Verikloak::HTTP.default_connection` helper for reuse/customization.
+
+### Dependencies
+- Declare `faraday-retry` as a runtime dependency so the default HTTP connection can load the retry middleware.
+
+---
+
 ## [0.1.4] - 2025-09-20
 
 ### Chore

data/README.md

@@ -1,4 +1,4 @@
-# Verikloak
+# verikloak
 
 [![CI](https://github.com/taiyaky/verikloak/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/taiyaky/verikloak/actions/workflows/ci.yml)
 [![Gem Version](https://img.shields.io/gem/v/verikloak)](https://rubygems.org/gems/verikloak)
@@ -9,8 +9,6 @@ A lightweight Rack middleware for verifying Keycloak JWT access tokens via OpenI
 
 Verikloak is a plug-and-play solution for Ruby (especially Rails API) apps that need to validate incoming `Bearer` tokens issued by Keycloak. It uses OpenID Connect Discovery and JWKs to fetch the public keys and verify JWT signatures securely.
 
----
-
 ## Features
 
 - OpenID Connect Discovery (`.well-known/openid-configuration`)
@@ -20,8 +18,6 @@ Verikloak is a plug-and-play solution for Ruby (especially Rails API) apps that
 - Rails/Rack middleware support
 - Faraday-based customizable HTTP layer
 
----
-
 ## Installation
 
 Add this line to your application's `Gemfile`:
@@ -36,8 +32,6 @@ Then install:
 bundle install
 ```
 
----
-
 ## Usage
 
 ### Rails (API mode)
@@ -81,7 +75,6 @@ structured error responses.
 > **Note:** When the Rack middleware is enabled, it already renders JSON error responses.
 > The `rescue_from` example above is only necessary if you bypass the middleware or want custom behavior.
 
----
 #### Error Hierarchy
 
 All Verikloak errors inherit from `Verikloak::Error`:
@@ -90,7 +83,7 @@ All Verikloak errors inherit from `Verikloak::Error`:
 - `Verikloak::DiscoveryError` – OIDC discovery fetch/parse (`503 Service Unavailable`)
 - `Verikloak::JwksCacheError` – JWKs fetch/parse/cache (`503 Service Unavailable`)
 - `Verikloak::MiddlewareError` – header/infra issues surfaced by the middleware (usually `401`, sometimes `503`)
----
+
 #### Recommended: use environment variables in production
 
 ```ruby
@@ -100,7 +93,27 @@ config.middleware.use Verikloak::Middleware,
   skip_paths: ['/', '/health', '/public/*', '/rails/*']
 ```
 This makes the configuration secure and flexible across environments.
----
+
+#### Advanced middleware options
+
+`Verikloak::Middleware` exposes a few optional knobs that help integrate with
+different Rack stacks:
+
+- `token_env_key` (default: `"verikloak.token"`) — where the raw JWT is stored in the Rack env
+- `user_env_key` (default: `"verikloak.user"`) — where decoded claims are stored
+- `realm` (default: `"verikloak"`) — value used in the `WWW-Authenticate` header for 401 responses
+- `logger` — an object responding to `error` (and optionally `debug`) that receives unexpected 500-level failures
+
+```ruby
+config.middleware.use Verikloak::Middleware,
+  discovery_url: ENV.fetch("DISCOVERY_URL"),
+  audience: ENV.fetch("CLIENT_ID"),
+  token_env_key: "rack.session.token",
+  user_env_key: "rack.session.claims",
+  realm: "my-api",
+  logger: Rails.logger
+```
+
 ### Accessing claims in controllers
 
 Once the middleware is enabled, Verikloak adds the decoded token and raw JWT to the Rack environment.  
@@ -117,7 +130,7 @@ class Api::V1::NotesController < ApplicationController
   end
 end
 ```
----
+
 ### Standalone Rack app
 
 ```ruby
@@ -133,7 +146,6 @@ run ->(env) {
   [200, { "Content-Type" => "application/json" }, [user.to_json]]
 }
 ```
----
 
 ## How It Works
 
@@ -149,8 +161,6 @@ run ->(env) {
    - `nbf` (not before)
 7. Makes the decoded payload available in `env["verikloak.user"]`
 
----
-
 ## Error Responses
 
 Verikloak returns JSON error responses in a consistent format with structured error codes. The HTTP status code reflects the nature of the error: 401 for client-side authentication issues, 503 for server-side discovery/JWKs errors, and 500 for unexpected internal errors.
@@ -236,13 +246,13 @@ For a full list of error cases and detailed explanations, please see the [ERRORS
 | Key             | Required | Description                                 |
 | --------------- | -------- | ------------------------------------------- |
 | `discovery_url` | Yes   | Full URL to your realm's OIDC discovery doc |
-| `audience`      | Yes   | Your client ID (checked against `aud`)      |
+| `audience`      | Yes   | Your client ID (checked against `aud`). Accepts a String or callable returning a String/Array per request. |
 | `skip_paths`    | No       | Array of paths or wildcards to skip authentication, e.g. `['/', '/health', '/public/*']`. **Note:** Regex patterns are not supported. |
 | `discovery`     | No       | Inject custom Discovery instance (advanced/testing) |
 | `jwks_cache`    | No       | Inject custom JwksCache instance (advanced/testing) |
 | `leeway`       | No       | Clock skew tolerance (seconds) applied during JWT verification. Defaults to `TokenDecoder::DEFAULT_LEEWAY`. |
 | `token_verify_options` | No | Hash of advanced JWT verification options passed through to TokenDecoder. For example: `{ verify_iat: false, leeway: 10, algorithms: ["RS256"] }`. If both `leeway:` and `token_verify_options[:leeway]` are set, the latter takes precedence. |
-| `connection`   | No       | Inject a Faraday::Connection used for both Discovery and JWKs fetches. Allows unified timeout, retry, and headers. |
+| `connection`   | No       | Inject a Faraday::Connection used for both Discovery and JWKs fetches. Defaults to a safe connection with timeouts and retries. |
 
 #### Option: `skip_paths`
 
@@ -264,33 +274,51 @@ Paths **not matched** by any `skip_paths` entry will require a valid JWT.
 **Note:** Regex patterns are not supported. Only literal paths and `*` wildcards are allowed.  
 Internally, `*` expands to match nested paths, so patterns like `/rails/*` are valid. This differs from regex — for example, `'/rails'` alone matches only `/rails`, while `'/rails/*'` covers both `/rails` and deeper subpaths.
 
+#### Option: `audience`
+
+The `audience` option may be either a static String or any callable object (Proc, lambda, object responding to `#call`). When a callable is provided it receives the Rack `env` and can return a different audience for each request. This is useful when a single gateway serves multiple downstream clients:
+
+```ruby
+Verikloak::Middleware.new(app,
+  discovery_url: ENV['DISCOVERY_URL'],
+  audience: ->(env) {
+    env['PATH_INFO'].start_with?('/admin') ? 'admin-client-id' : 'public-client-id'
+  }
+)
+```
+
+The callable may also return an Array of audiences when a route is valid for multiple clients.
+
 #### Customizing Faraday for Discovery and JWKs
 
-Both `Discovery` and `JwksCache` accept a `Faraday::Connection`.  
-This allows you to configure timeouts, retries, logging, and shared headers:
+Both `Discovery` and `JwksCache` accept a `Faraday::Connection`.
+Verikloak ships with a helper you can re-use anywhere:
+
+```ruby
+connection = Verikloak::HTTP.default_connection
+```
+
+The default connection enables retries (via `faraday-retry`) for idempotent GET requests and applies conservative timeouts (5s request / 2s open). If you need to add extra middleware, adapters, or instrumentation, you can build on top of the defaults:
 
 ```ruby
-connection = Faraday.new(request: { timeout: 5 }) do |f|
+connection = Faraday.new(request: { timeout: 10 }) do |f|
+  f.request :retry, Verikloak::HTTP::RETRY_OPTIONS
   f.response :logger
+  f.adapter Faraday.default_adapter
 end
 
 config.middleware.use Verikloak::Middleware,
   discovery_url: ENV["DISCOVERY_URL"],
   audience: ENV["CLIENT_ID"],
-  jwks_cache: Verikloak::JwksCache.new(
-    jwks_uri: "https://example.com/realms/myrealm/protocol/openid-connect/certs",
-    connection: connection
-  )
-```
-This makes it easy to apply consistent Faraday settings across both discovery and JWKs fetches.
+  connection: connection
 
-```ruby
-# Alternatively, you can pass the connection directly to the middleware:
-config.middleware.use Verikloak::Middleware,
-  discovery_url: ENV["DISCOVERY_URL"],
-  audience: ENV["CLIENT_ID"],
+# Or pass the connection through to a shared JwksCache instance
+jwks_cache = Verikloak::JwksCache.new(
+  jwks_uri: "https://example.com/realms/myrealm/protocol/openid-connect/certs",
   connection: connection
+)
 ```
+This makes it easy to keep HTTP settings consistent across discovery, JWK refreshes, and any other Verikloak components you wire together.
 
 #### Customizing token verification (leeway and options)
 
@@ -314,8 +342,6 @@ config.middleware.use Verikloak::Middleware,
 - `token_verify_options:` is passed directly to TokenDecoder (and ultimately to `JWT.decode`).
 - If both are set, `token_verify_options[:leeway]` takes precedence.
 
----
-
 #### Performance note
 
 Internally, Verikloak caches `TokenDecoder` instances per JWKs fetch to avoid reinitializing
@@ -330,14 +356,13 @@ Verikloak consists of modular components, each with a focused responsibility:
 |----------------|--------------------------------------------------------|--------------|
 | `Middleware`    | Rack-compatible entry point for token validation     | Rack layer   |
 | `Discovery`     | Fetches OIDC discovery metadata (`.well-known`)      | Network layer|
+| `HTTP`          | Provides shared Faraday connection with retries/timeouts | Network layer|
 | `JwksCache`     | Fetches & caches JWKs public keys (with ETag)        | Cache layer  |
 | `TokenDecoder`  | Decodes and verifies JWTs (signature, exp, nbf, iss, aud) | Crypto layer |
 | `Errors`        | Centralized error hierarchy                          | Core layer   |
 
 This separation enables better testing, modular reuse, and flexibility.
 
----
-
 ## Development (for contributors)
 
 Clone and install dependencies:
@@ -349,8 +374,6 @@ bundle install
 ```
 See **Testing** below to run specs and RuboCop. For releasing, see **Publishing**.
 
----
-
 ## Testing
 
 All pull requests and pushes are automatically tested with [RSpec](https://rspec.info/) and [RuboCop](https://rubocop.org/) via GitHub Actions.
@@ -362,40 +385,33 @@ To run the test suite locally:
 docker compose run --rm dev rspec
 docker compose run --rm dev rubocop
 ```
----
 
 ## Contributing
 
 Bug reports and pull requests are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.
 
----
-
 ## Security
 
 If you find a security vulnerability, please follow the instructions in [SECURITY.md](SECURITY.md).
 
----
-
 ## License
 
 This project is licensed under the [MIT License](LICENSE).
 
----
-
 ## Publishing (for maintainers)
 
 Gem release instructions are documented separately in [MAINTAINERS.md](MAINTAINERS.md).
 
----
-
 ## Changelog
 
 See [CHANGELOG.md](CHANGELOG.md) for release history.
 
----
-
 ## References
 
-- [OpenID Connect Discovery 1.0 Spec](https://openid.net/specs/openid-connect-discovery-1_0.html)  
-- [Keycloak Documentation: Securing Apps](https://www.keycloak.org/docs/latest/securing_apps/#openid-connect)  
-- [JWT RFC 7519](https://datatracker.ietf.org/doc/html/rfc7519) 
+- [OpenID Connect Discovery 1.0 Spec](https://openid.net/specs/openid-connect-discovery-1_0.html)
+- [Keycloak Documentation: Securing Apps](https://www.keycloak.org/docs/latest/securing_apps/#openid-connect)
+- [JWT RFC 7519](https://datatracker.ietf.org/doc/html/rfc7519)
+- [verikloak-rails on RubyGems](https://rubygems.org/gems/verikloak-rails)
+- [verikloak-bff on RubyGems](https://rubygems.org/gems/verikloak-bff)
+- [verikloak-pundit on RubyGems](https://rubygems.org/gems/verikloak-pundit)
+- [verikloak-audience on RubyGems](https://rubygems.org/gems/verikloak-audience)

data/lib/verikloak/discovery.rb

@@ -4,6 +4,8 @@ require 'faraday'
 require 'json'
 require 'uri'
 
+require 'verikloak/http'
+
 module Verikloak
   # Fetches and caches the OpenID Connect Discovery document.
   #
@@ -39,10 +41,10 @@ module Verikloak
     REQUIRED_FIELDS = %w[jwks_uri issuer].freeze
 
     # @param discovery_url [String] The full URL to the `.well-known/openid-configuration`.
-    # @param connection [Faraday::Connection] Optional Faraday client (for DI/tests). Defaults to `Faraday.new`.
+    # @param connection [Faraday::Connection] Optional Faraday client (for DI/tests).
     # @param cache_ttl [Integer] Cache TTL in seconds (default: 3600).
     # @raise [DiscoveryError] when `discovery_url` is not a valid HTTP(S) URL
-    def initialize(discovery_url:, connection: Faraday.new, cache_ttl: 3600)
+    def initialize(discovery_url:, connection: Verikloak::HTTP.default_connection, cache_ttl: 3600)
       unless discovery_url.is_a?(String) && discovery_url.strip.match?(%r{^https?://})
         raise DiscoveryError.new('Invalid discovery URL: must be a non-empty HTTP(S) URL',
                                  code: 'invalid_discovery_url')

data/lib/verikloak/http.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'faraday/retry'
+
+module Verikloak
+  # Internal HTTP helpers shared across components.
+  module HTTP
+    # Default request timeout (seconds) for outbound discovery/JWKs calls.
+    DEFAULT_TIMEOUT = 5
+    # Default open/read timeout (seconds) before establishing the HTTP connection.
+    DEFAULT_OPEN_TIMEOUT = 2
+
+    # Retry middleware configuration used for idempotent GET requests.
+    # Retries on 429/5xx with exponential backoff and jitter.
+    RETRY_OPTIONS = {
+      max: 2,
+      interval: 0.1,
+      interval_randomness: 0.2,
+      backoff_factor: 2,
+      methods: %i[get],
+      retry_statuses: [429, 500, 502, 503, 504]
+    }.freeze
+
+    # Builds a Faraday connection with conservative defaults suitable for
+    # network-bound operations (discovery and JWKs fetching).
+    #
+    # @return [Faraday::Connection]
+    def self.default_connection
+      Faraday.new do |f|
+        f.request :retry, RETRY_OPTIONS
+        f.options.timeout = DEFAULT_TIMEOUT
+        f.options.open_timeout = DEFAULT_OPEN_TIMEOUT
+        f.adapter Faraday.default_adapter
+      end
+    end
+  end
+end

data/lib/verikloak/jwks_cache.rb

@@ -3,6 +3,8 @@
 require 'faraday'
 require 'json'
 
+require 'verikloak/http'
+
 module Verikloak
   # Caches and revalidates JSON Web Key Sets (JWKs) fetched from a remote endpoint.
   #
@@ -43,7 +45,7 @@ module Verikloak
       end
 
       @jwks_uri    = jwks_uri
-      @connection  = connection || Faraday.new
+      @connection  = connection || Verikloak::HTTP.default_connection
       @cached_keys = nil
       @etag        = nil
       @fetched_at  = nil
@@ -59,6 +61,8 @@ module Verikloak
     # @return [Array<Hash>] the cached JWKs after fetch/revalidation
     # @raise [JwksCacheError] on HTTP failures, invalid JSON, invalid structure, or cache miss on 304
     def fetch!
+      return @cached_keys if fresh_by_ttl?
+
       with_error_handling do
         # Build conditional request headers (ETag-based)
         headers  = build_conditional_headers

data/lib/verikloak/middleware.rb

@@ -5,6 +5,8 @@ require 'json'
 require 'set'
 require 'faraday'
 
+require 'verikloak/http'
+
 module Verikloak
   # @api private
   #
@@ -106,12 +108,12 @@ module Verikloak
 
     # Returns a cached TokenDecoder instance for current inputs.
     # Cache key uses issuer, audience, leeway, token_verify_options, and JWKs fetched_at timestamp.
-    def decoder_for
+    def decoder_for(audience)
       keys = @jwks_cache.cached
       fetched_at = @jwks_cache.respond_to?(:fetched_at) ? @jwks_cache.fetched_at : nil
       cache_key = [
         @issuer,
-        @audience,
+        audience,
         @leeway,
         @token_verify_options,
         fetched_at
@@ -120,7 +122,7 @@ module Verikloak
         @decoder_cache[cache_key] ||= TokenDecoder.new(
           jwks: keys,
           issuer: @issuer,
-          audience: @audience,
+          audience: audience,
           leeway: @leeway,
           options: @token_verify_options
         )
@@ -142,14 +144,16 @@ module Verikloak
     # @param token [String]
     # @return [Hash] decoded JWT claims
     # @raise [Verikloak::Error] bubbles up verification/fetch errors for centralized handling
-    def decode_token(token)
+    def decode_token(env, token)
       ensure_jwks_cache!
       if @jwks_cache.cached.nil? || @jwks_cache.cached.empty?
         raise MiddlewareError.new('JWKs cache is empty, cannot verify token', code: 'jwks_cache_miss')
       end
 
+      audience = resolve_audience(env)
+
       # First attempt
-      decoder = decoder_for
+      decoder = decoder_for(audience)
 
       begin
         decoder.decode!(token)
@@ -160,11 +164,78 @@ module Verikloak
         refresh_jwks!
 
         # Rebuild decoder with refreshed keys and try once more.
-        decoder = decoder_for
+        decoder = decoder_for(audience)
         decoder.decode!(token)
       end
     end
 
+    # Resolves the expected audience for the current request.
+    #
+    # @param env [Hash] Rack environment.
+    # @return [String, Array<String>] The expected audience value.
+    # @raise [MiddlewareError] when the resolved audience is blank.
+    def resolve_audience(env)
+      source = @audience_source
+      value = if source.respond_to?(:call)
+                callable = source
+                arity = callable.respond_to?(:arity) ? callable.arity : safe_callable_arity(callable)
+                call_with_optional_env(callable, env, arity)
+              else
+                source
+              end
+
+      raise MiddlewareError.new('Audience is blank for the request', code: 'invalid_audience') if value.nil?
+
+      if value.is_a?(Array)
+        raise MiddlewareError.new('Audience is blank for the request', code: 'invalid_audience') if value.empty?
+
+        return value
+      end
+
+      normalized = value.to_s
+      raise MiddlewareError.new('Audience is blank for the request', code: 'invalid_audience') if normalized.empty?
+
+      normalized
+    end
+
+    # Invokes the audience callable, passing the Rack env only when required.
+    # Falls back to a zero-argument invocation if the callable raises
+    # `ArgumentError` due to an unexpected argument.
+    #
+    # @param callable [#call] Audience resolver callable.
+    # @param env [Hash] Rack environment.
+    # @param arity [Integer, nil] Callable arity when known, nil otherwise.
+    # @return [Object] Audience value returned by the callable.
+    # @raise [ArgumentError] when the callable raises for reasons other than arity mismatch.
+    def call_with_optional_env(callable, env, arity)
+      return callable.call if arity&.zero?
+
+      callable.call(env)
+    rescue ArgumentError => e
+      raise unless arity.nil? && wrong_arity_error?(e)
+
+      callable.call
+    end
+
+    # Safely obtains a callable's arity, returning nil when `#method(:call)`
+    # cannot be resolved (e.g., BasicObject-based objects).
+    #
+    # @param callable [#call]
+    # @return [Integer, nil]
+    def safe_callable_arity(callable)
+      callable.method(:call).arity
+    rescue NameError
+      nil
+    end
+
+    # Returns true when the ArgumentError message indicates a wrong arity.
+    #
+    # @param error [ArgumentError]
+    # @return [Boolean]
+    def wrong_arity_error?(error)
+      error.message.include?('wrong number of arguments')
+    end
+
     # Ensures that discovery metadata and JWKs cache are initialized and up-to-date.
     # This method is thread-safe.
     #
@@ -278,17 +349,24 @@ module Verikloak
     include SkipPathMatcher
     include MiddlewareTokenVerification
 
+    DEFAULT_REALM = 'verikloak'
+    DEFAULT_TOKEN_ENV_KEY = 'verikloak.token'
+    DEFAULT_USER_ENV_KEY = 'verikloak.user'
+
     # @param app [#call] downstream Rack app
     # @param discovery_url [String] OIDC discovery endpoint URL
-    # @param audience [String] expected `aud` claim
+    # @param audience [String, #call] Expected `aud` claim. When a callable is provided it
+    #   receives the Rack env and may return a String or Array of audiences.
     # @param skip_paths [Array<String>] literal paths or wildcard patterns to bypass auth
     # @param discovery [Discovery, nil] custom discovery instance (for DI/tests)
     # @param jwks_cache [JwksCache, nil] custom JWKs cache instance (for DI/tests)
-    # @param connection [Faraday::Connection, nil] Optional injected Faraday connection (defaults to Faraday.new)
+    # @param connection [Faraday::Connection, nil] Optional injected Faraday connection
+    #   (defaults to {Verikloak::HTTP.default_connection})
     # @param leeway [Integer] Clock skew tolerance in seconds for token verification (delegated to TokenDecoder)
     # @param token_verify_options [Hash] Additional JWT verification options passed through
     #   to TokenDecoder.
     #   e.g., { verify_iat: false, leeway: 10 }
+    # rubocop:disable Metrics/ParameterLists
     def initialize(app,
                    discovery_url:,
                    audience:,
@@ -297,20 +375,29 @@ module Verikloak
                    jwks_cache: nil,
                    connection: nil,
                    leeway: Verikloak::TokenDecoder::DEFAULT_LEEWAY,
-                   token_verify_options: {})
-      @app           = app
-      @audience      = audience
-      @discovery     = discovery || Discovery.new(discovery_url: discovery_url)
-      @jwks_cache    = jwks_cache
-      @connection    = connection || Faraday.new
-      @leeway        = leeway
+                   token_verify_options: {},
+                   token_env_key: DEFAULT_TOKEN_ENV_KEY,
+                   user_env_key: DEFAULT_USER_ENV_KEY,
+                   realm: DEFAULT_REALM,
+                   logger: nil)
+      @app             = app
+      @connection      = connection || Verikloak::HTTP.default_connection
+      @audience_source = audience
+      @discovery       = discovery || Discovery.new(discovery_url: discovery_url, connection: @connection)
+      @jwks_cache      = jwks_cache
+      @leeway = leeway
       @token_verify_options = token_verify_options || {}
       @issuer        = nil
       @mutex         = Mutex.new
       @decoder_cache = {}
+      @token_env_key = normalize_env_key(token_env_key, 'token_env_key')
+      @user_env_key  = normalize_env_key(user_env_key, 'user_env_key')
+      @realm         = normalize_realm(realm)
+      @logger        = logger
 
       compile_skip_paths(skip_paths)
     end
+    # rubocop:enable Metrics/ParameterLists
 
     # Rack entrypoint.
     #
@@ -344,9 +431,9 @@ module Verikloak
     # @param token [String]
     # @return [Array(Integer, Hash, Array<String>)] Rack response triple
     def handle_request(env, token)
-      claims = decode_token(token)
-      env['verikloak.token'] = token
-      env['verikloak.user']  = claims
+      claims = decode_token(env, token)
+      env[@token_env_key] = token
+      env[@user_env_key]  = claims
       @app.call(env)
     end
 
@@ -402,7 +489,7 @@ module Verikloak
       headers = { 'Content-Type' => 'application/json' }
       if status == 401
         headers['WWW-Authenticate'] =
-          %(Bearer realm="verikloak", error="#{code}", error_description="#{message.gsub('"', '\\"')}")
+          %(Bearer realm="#{@realm}", error="#{code}", error_description="#{message.gsub('"', '\\"')}")
       end
       [status, headers, [body]]
     end
@@ -412,8 +499,62 @@ module Verikloak
     # @param error [Exception]
     # @return [void]
     def log_internal_error(error)
-      warn "[verikloak] Internal error: #{error.class} - #{error.message}"
-      warn error.backtrace.join("\n") if error.backtrace
+      message = "[verikloak] Internal error: #{error.class} - #{error.message}"
+      backtrace = error.backtrace&.join("\n")
+
+      if logger_available?
+        log_with_logger(message, backtrace)
+      else
+        warn message
+        warn backtrace if backtrace
+      end
+    end
+
+    def logger_available?
+      return false unless @logger
+
+      @logger.respond_to?(:error) || @logger.respond_to?(:warn) || @logger.respond_to?(:debug)
+    end
+
+    def log_with_logger(message, backtrace)
+      log_message(@logger, message)
+      log_backtrace(@logger, backtrace)
+    end
+
+    def log_message(logger, message)
+      if logger.respond_to?(:error)
+        logger.error(message)
+      elsif logger.respond_to?(:warn)
+        logger.warn(message)
+      end
+    end
+
+    def log_backtrace(logger, backtrace)
+      return unless backtrace
+
+      if logger.respond_to?(:debug)
+        logger.debug(backtrace)
+      elsif logger.respond_to?(:error)
+        logger.error(backtrace)
+      elsif logger.respond_to?(:warn)
+        logger.warn(backtrace)
+      end
+    end
+
+    def normalize_env_key(value, option_name)
+      normalized = value.to_s.strip
+      raise ArgumentError, "#{option_name} cannot be blank" if normalized.empty?
+
+      normalized
+    end
+
+    def normalize_realm(value)
+      return DEFAULT_REALM if value.nil?
+
+      normalized = value.to_s.strip
+      raise ArgumentError, 'realm cannot be blank' if normalized.empty?
+
+      normalized
     end
   end
 end

data/lib/verikloak/version.rb

@@ -2,5 +2,5 @@
 
 module Verikloak
   # Defines the current version of the Verikloak gem.
-  VERSION = '0.1.4'
+  VERSION = '0.2.0'
 end

data/lib/verikloak.rb

@@ -5,6 +5,7 @@
 # by simply requiring 'verikloak'.
 require 'verikloak/version'
 require 'verikloak/errors'
+require 'verikloak/http'
 require 'verikloak/discovery'
 require 'verikloak/jwks_cache'
 require 'verikloak/token_decoder'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: verikloak
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.2.0
 platform: ruby
 authors:
 - taiyaky
@@ -29,6 +29,26 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: faraday-retry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
 - !ruby/object:Gem::Dependency
   name: json
   requirement: !ruby/object:Gem::Requirement
@@ -77,6 +97,7 @@ files:
 - lib/verikloak.rb
 - lib/verikloak/discovery.rb
 - lib/verikloak/errors.rb
+- lib/verikloak/http.rb
 - lib/verikloak/jwks_cache.rb
 - lib/verikloak/middleware.rb
 - lib/verikloak/token_decoder.rb
@@ -88,7 +109,7 @@ metadata:
   source_code_uri: https://github.com/taiyaky/verikloak
   changelog_uri: https://github.com/taiyaky/verikloak/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/taiyaky/verikloak/issues
-  documentation_uri: https://rubydoc.info/gems/verikloak/0.1.4
+  documentation_uri: https://rubydoc.info/gems/verikloak/0.2.0
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: