verikloak-audience 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d97d79e3f6ccd8f2c920cc7dcb66612e9edbd577ba4be2f5948eddd16145dd9b
-  data.tar.gz: 4517ee945923ec595fa7447f33dd0e9370cc72a2a561bc04d4f910efed018595
+  metadata.gz: 400925f130b177647a3d7007cf4e43b566451e5b131968fbca2946d8a2f47d06
+  data.tar.gz: 89fa1b482fe9cdaa9278f56380cc59bba52325dd7db6b0e9aeb473e658568eb8
 SHA512:
-  metadata.gz: 83c14846297272179ccf6f4480dab677c82be3d21b32a6c374c3b40fc5be04dd0cf9c9c439457e9dd33d4b4a9fca393aca31b7104b4282479b872ad8987c8632
-  data.tar.gz: e2e125eab982f983e6447166bcd6b9d9413f15573301335f15ef53ba0bafb6d07020848ec942e9b532db69b29ab3fc6280ae9fc6f74d12ff9786a39fc64dccde
+  metadata.gz: 0d39de8ac4bfb587b968e4017e36edc03fbe49c4a7495963671aacb32a5d65fa06b39957922344b1dd3336614bb20b5ad8eeef9c7248eb6ea9c82dd772323072
+  data.tar.gz: bc01de7533c0388fc4e9f8ed35747b9136c04f166cbcfe0dbc75ff2895703aed960ed0d3845beb0dd3ecc2a3bffae786609864a59ae335672f6754a216adda4d

data/CHANGELOG.md

@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [0.3.1] - 2026-01-01
+
+### Added
+- **`:any_match` profile**: New audience validation profile that passes when at least one of the required audiences is present in the token.
+- **`skip_paths` configuration**: Skip audience validation for specific paths (e.g., health checks). Supports exact matches, prefix matches, wildcard patterns, and Regexp.
+- **Generator improvements**: Install generator now includes `Verikloak::Audience.configure` block with all four profiles documented.
+
+### Fixed
+- **Regexp support in `skip_paths`**: Fixed `NoMethodError` when passing Regexp patterns.
+- **Warning message accuracy**: Unconfigured warning now correctly states "ALL requests will be rejected with 403".
+- Configuration sync now happens before middleware insertion.
+
+### Changed
+- README now correctly describes that the Railtie automatically inserts the middleware.
+- Removed manual `insert_middleware` call from generated initializer (Railtie handles this automatically).
+
 ## [0.3.0] - 2026-01-01
 
 ### Fixed

data/README.md

@@ -22,6 +22,7 @@ For the full error behaviour (response shapes, exception classes, logging hints)
 |---------|---------|-----------------------------------------------------------|
 | `:strict_single` *(recommended)* | Requires `aud` to match `required_aud` exactly (order-insensitive, no extras). | APIs where audiences are cleanly separated. Logged suggestion when the observed `aud` already equals the configured list. |
 | `:allow_account` | Allows `account` in addition to required audiences (e.g. `["rails-api","account"]`). | SPA + API mixes where Keycloak always emits `account`. Suggested when strict mode fails and the log shows `profile=:allow_account`. |
+| `:any_match` | Passes when at least one of the required audiences is present. | Shared APIs where multiple clients may have overlapping audiences. More permissive than `:strict_single`. |
 | `:resource_or_aud` | Passes when `resource_access[client].roles` is present; otherwise falls back to `:allow_account`. | Services relying on resource roles. Suggested when logs output `profile=:resource_or_aud`. |
 
 ## Installation
@@ -30,13 +31,14 @@ For the full error behaviour (response shapes, exception classes, logging hints)
 bundle add verikloak-audience
 ```
 
-In Rails applications, generate the initializer that automatically inserts the middleware:
+In Rails applications, run the generator to create a configuration initializer:
 
 ```bash
 rails g verikloak:audience:install
 ```
 
-This creates `config/initializers/verikloak_audience.rb` that will insert the audience middleware after the core Verikloak middleware once it's available.
+This creates `config/initializers/verikloak_audience.rb` with configuration options.
+The middleware is automatically inserted by the Railtie after `Verikloak::Middleware`.
 
 ## Manual Rack / Rails setup
 
@@ -58,7 +60,7 @@ See [`examples/rack.ru`](examples/rack.ru) for a full Rack sample. In Rails, alw
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `profile` | Symbol | `:strict_single` | Profile selector. Accepts `:strict_single`, `:allow_account`, or `:resource_or_aud`. |
+| `profile` | Symbol | `:strict_single` | Profile selector. Accepts `:strict_single`, `:allow_account`, `:any_match`, or `:resource_or_aud`. |
 | `required_aud` | Array/String/Symbol | `[]` | Required audience values; coerced to an array internally. |
 | `resource_client` | String | `"rails-api"` | Keycloak client id used to look up `resource_access[client].roles`. |
 | `env_claims_key` | String | `"verikloak.user"` | Rack env key where verified claims are stored. |

data/lib/generators/verikloak/audience/install/templates/initializer.rb.erb

@@ -1,11 +1,24 @@
 # frozen_string_literal: true
 
-# Insert the audience middleware after the core Verikloak middleware once it
-# has been loaded into the application.
+# Verikloak Audience Configuration
 #
-# The Railtie's insert_middleware method includes internal guards to prevent
-# duplicate insertion when both the railtie initializer and this generated
-# initializer are loaded. This is safe to call multiple times.
-if defined?(Rails) && Rails.respond_to?(:application)
-  Verikloak::Audience::Railtie.insert_middleware(Rails.application)
+# Configure the audience validation profile and settings.
+# This middleware provides stricter audience validation than core Verikloak.
+#
+# The middleware is automatically inserted after Verikloak::Middleware by the
+# Railtie. No manual middleware insertion is required.
+#
+Verikloak::Audience.configure do |config|
+  # Audience validation profile
+  # :strict_single   - Only exact single audience match (default, recommended)
+  # :allow_account   - Allow "account" alongside your API audience
+  # :any_match       - At least one required audience is present (more permissive)
+  # :resource_or_aud - Check resource_access roles first, fallback to :allow_account
+  # config.profile = :strict_single
+
+  # Required audience(s) - synced from verikloak-rails automatically
+  # config.required_aud = ['rails-api']
+
+  # Skip paths for audience validation (synced from verikloak-rails automatically)
+  # config.skip_paths = %w[/up /health]
 end

data/lib/verikloak/audience/checker.rb

@@ -7,7 +7,7 @@ module Verikloak
     # This module provides predicate helpers used by the middleware to decide
     # whether a given set of claims satisfies the configured profile.
     module Checker
-      VALID_PROFILES = %i[strict_single allow_account resource_or_aud].freeze
+      VALID_PROFILES = %i[strict_single allow_account any_match resource_or_aud].freeze
 
       module_function
 
@@ -33,6 +33,8 @@ module Verikloak
           strict_single?(claims, cfg.required_aud_list)
         when :allow_account
           allow_account?(claims, cfg.required_aud_list)
+        when :any_match
+          any_match?(claims, cfg.required_aud_list)
         when :resource_or_aud
           resource_or_aud?(claims, cfg.resource_client.to_s, cfg.required_aud_list)
         end
@@ -66,6 +68,20 @@ module Verikloak
         extras.empty? && (required - aud).empty?
       end
 
+      # Validate that at least one required audience is present in the token.
+      # More permissive than :strict_single; useful when multiple clients share audiences.
+      #
+      # @param claims [Hash]
+      # @param required [Array<String>]
+      # @return [Boolean]
+      def any_match?(claims, required)
+        aud = normalized_audiences(claims)
+        return false if required.empty?
+
+        # At least one of the required audiences must be present
+        aud.intersect?(required.map(&:to_s))
+      end
+
       # Permit when resource roles exist for the client; otherwise fallback to
       # {#allow_account?}.
       #
@@ -92,6 +108,7 @@ module Verikloak
         required = cfg.required_aud_list
         return :strict_single if strict_single?(claims, required)
         return :allow_account if allow_account?(claims, required)
+        return :any_match if any_match?(claims, required)
         return :resource_or_aud if resource_or_aud?(claims, cfg.resource_client.to_s, required)
 
         :strict_single

data/lib/verikloak/audience/configuration.rb

@@ -8,7 +8,7 @@ module Verikloak
     #
     # @!attribute [rw] profile
     #   The enforcement profile to use.
-    #   @return [:strict_single, :allow_account, :resource_or_aud]
+    #   @return [:strict_single, :allow_account, :any_match, :resource_or_aud]
     # @!attribute [rw] required_aud
     #   Required audience(s). Can be a String/Symbol or an Array of them.
     #   @return [Array<String,Symbol>, String, Symbol]
@@ -21,12 +21,16 @@ module Verikloak
     # @!attribute [rw] suggest_in_logs
     #   Whether to log a suggestion when audience validation fails.
     #   @return [Boolean]
+    # @!attribute [rw] skip_paths
+    #   Paths to skip audience validation for (e.g., health checks).
+    #   Synced from verikloak-rails when available.
+    #   @return [Array<String, Regexp>]
     class Configuration
       DEFAULT_RESOURCE_CLIENT = 'rails-api'
       DEFAULT_ENV_CLAIMS_KEY = 'verikloak.user'
 
       attr_accessor :profile, :required_aud, :resource_client,
-                    :suggest_in_logs
+                    :suggest_in_logs, :skip_paths
       attr_reader :env_claims_key
 
       # Create a configuration with safe defaults.
@@ -38,6 +42,7 @@ module Verikloak
         @resource_client = DEFAULT_RESOURCE_CLIENT
         self.env_claims_key = DEFAULT_ENV_CLAIMS_KEY
         @suggest_in_logs = true
+        @skip_paths      = []
       end
 
       # Ensure `dup` produces an independent copy.
@@ -51,6 +56,7 @@ module Verikloak
         @resource_client = safe_dup(source.resource_client)
         self.env_claims_key = safe_dup(source.env_claims_key)
         @suggest_in_logs = source.suggest_in_logs
+        @skip_paths      = source.skip_paths&.dup || []
       end
 
       # Coerce `required_aud` into an array of strings.

data/lib/verikloak/audience/middleware.rb

@@ -15,11 +15,12 @@ module Verikloak
     class Middleware
       # @param app [#call] next Rack application
       # @param opts [Hash] configuration overrides (see {Configuration})
-      # @option opts [Symbol] :profile
+      # @option opts [Symbol] :profile (:strict_single, :allow_account, :any_match, :resource_or_aud)
       # @option opts [Array<String>,String,Symbol] :required_aud
       # @option opts [String] :resource_client
       # @option opts [String] :env_claims_key
       # @option opts [Boolean] :suggest_in_logs
+      # @option opts [Array<String, Regexp>] :skip_paths
       def initialize(app, **opts)
         @app = app
         @config = Verikloak::Audience.config.dup
@@ -32,6 +33,9 @@ module Verikloak
       # @param env [Hash] Rack environment
       # @return [Array(Integer, Hash, #each)] Rack response triple
       def call(env)
+        # Skip audience validation for configured paths (e.g., health checks)
+        return @app.call(env) if skip_path?(env)
+
         env_key = @config.env_claims_key
         claims = env[env_key] || env[env_key&.to_sym] || {}
         return @app.call(env) if Checker.ok?(claims, @config)
@@ -51,6 +55,36 @@ module Verikloak
 
       private
 
+      # Check if the current request path should skip audience validation.
+      #
+      # @param env [Hash] Rack environment
+      # @return [Boolean]
+      def skip_path?(env)
+        paths = @config.skip_paths
+        return false if paths.nil? || paths.empty?
+
+        request_path = env['PATH_INFO'] || env['REQUEST_PATH'] || ''
+        paths.any? { |pattern| path_matches?(request_path, pattern) }
+      end
+
+      # Determine if a request path matches the given pattern.
+      # Supports exact matches and prefix matches (pattern ending with *).
+      #
+      # @param request_path [String]
+      # @param pattern [String, Regexp]
+      # @return [Boolean]
+      def path_matches?(request_path, pattern)
+        return false if pattern.nil?
+        return request_path.match?(pattern) if pattern.is_a?(Regexp)
+        return false if pattern.empty?
+
+        if pattern.end_with?('*')
+          request_path.start_with?(pattern.chomp('*'))
+        else
+          request_path == pattern || request_path.start_with?("#{pattern}/")
+        end
+      end
+
       # Apply provided options to the configuration instance.
       #
       # @param opts [Hash] raw overrides provided to the middleware
@@ -70,14 +104,24 @@ module Verikloak
 
       # Determine whether configuration validation should run. This allows
       # Rails generators to boot without a fully-populated configuration since
-      # the install task is responsible for creating it.
+      # the install task is responsible for creating it. Also skips validation
+      # when configuration is not explicitly set up.
       #
       # @return [Boolean]
       def skip_validation?
-        return false unless defined?(::Verikloak::Audience::Railtie)
-        return false unless ::Verikloak::Audience::Railtie.respond_to?(:skip_configuration_validation?)
+        # Skip if Railtie indicates generator mode
+        if defined?(::Verikloak::Audience::Railtie)
+          if ::Verikloak::Audience::Railtie.respond_to?(:skip_configuration_validation?) && ::Verikloak::Audience::Railtie.skip_configuration_validation?
+            return true
+          end
+
+          # Skip if configuration is incomplete (no audiences configured)
+          if ::Verikloak::Audience::Railtie.respond_to?(:skip_unconfigured_validation?) && ::Verikloak::Audience::Railtie.skip_unconfigured_validation?
+            return true
+          end
+        end
 
-        ::Verikloak::Audience::Railtie.skip_configuration_validation?
+        false
       end
 
       # Emit a warning for failed audience checks using request-scoped loggers

data/lib/verikloak/audience/railtie.rb

@@ -4,6 +4,177 @@ require 'rails/railtie'
 
 module Verikloak
   module Audience
+    # Warning messages for Railtie.
+    module RailtieWarnings
+      WARNING_MESSAGE = <<~MSG
+        [verikloak-audience] Skipping automatic middleware insertion because ::Verikloak::Middleware
+        is not present in the Rails middleware stack.
+
+        To enable verikloak-audience, first ensure that the core Verikloak middleware (`Verikloak::Middleware`)
+        is added to your Rails middleware stack. Once the core middleware is present, you can run
+        `rails g verikloak:audience:install` to generate the initializer for the audience middleware,
+        or manually add:
+
+          config.middleware.insert_after Verikloak::Middleware, Verikloak::Audience::Middleware
+
+        This warning will disappear once the core middleware is properly configured and the audience
+        middleware is inserted.
+      MSG
+
+      CORE_NOT_CONFIGURED_WARNING = <<~MSG
+        [verikloak-audience] Skipping automatic middleware insertion because verikloak-rails
+        is not fully configured (discovery_url is not set).
+
+        The audience middleware requires the core Verikloak middleware to be present in the stack.
+        Please configure verikloak-rails first by setting the discovery_url in your initializer.
+      MSG
+
+      UNCONFIGURED_WARNING = <<~MSG
+        [verikloak-audience] Skipping configuration validation because required_aud is not configured.
+
+        To use verikloak-audience, you must configure at least one required audience.
+        Run `rails g verikloak:audience:install` to generate the initializer, or add:
+
+          Verikloak::Audience.configure do |config|
+            config.required_aud = ['your-audience']
+          end
+
+        WARNING: Without this configuration, ALL requests will be rejected with 403.
+      MSG
+
+      def log_warning(message)
+        logger = (::Rails.logger if defined?(::Rails) && ::Rails.respond_to?(:logger))
+        logger ? logger.warn(message) : Kernel.warn(message)
+      end
+
+      def warn_core_not_configured = log_warning(CORE_NOT_CONFIGURED_WARNING)
+      def warn_missing_core_middleware = log_warning(WARNING_MESSAGE)
+      def warn_unconfigured = log_warning(UNCONFIGURED_WARNING)
+    end
+
+    # Helper methods for Railtie configuration sync.
+    module RailtieHelpers
+      include RailtieWarnings
+
+      def apply_verikloak_rails_configuration
+        rails_config = verikloak_rails_config
+        return unless rails_config
+
+        Verikloak::Audience.configure do |cfg|
+          sync_env_claims_key(cfg, rails_config)
+          sync_required_aud(cfg, rails_config)
+          sync_resource_client(cfg, rails_config)
+          sync_skip_paths(cfg, rails_config)
+        end
+      end
+
+      def discovery_url_configured?(value)
+        return false unless value
+        return !value.blank? if value.respond_to?(:blank?)
+        return !value.empty? if value.respond_to?(:empty?)
+
+        true
+      end
+
+      def middleware_not_found_error?(error)
+        return true if error.class.name.to_s.include?('MiddlewareNotFound')
+
+        message = error.message.to_s
+        message.include?('No such middleware') ||
+          message.include?('does not exist') ||
+          message.match?(/middleware.*not found/i)
+      end
+
+      def verikloak_install_generator?(command)
+        return false unless command.is_a?(String)
+
+        command.start_with?('verikloak:') && command.end_with?(':install')
+      end
+
+      def first_cli_tokens
+        tokens = []
+        ARGV.each do |arg|
+          next if arg.start_with?('-') || arg == 'rails'
+
+          tokens << arg
+          break if tokens.size >= 2
+        end
+        tokens
+      end
+
+      private
+
+      def verikloak_rails_config
+        return unless defined?(::Verikloak::Rails)
+        return unless ::Verikloak::Rails.respond_to?(:config)
+
+        ::Verikloak::Rails.config
+      rescue StandardError
+        nil
+      end
+
+      def sync_env_claims_key(cfg, rails_config)
+        return unless rails_config.respond_to?(:user_env_key)
+
+        user_key = rails_config.user_env_key
+        return if blank?(user_key)
+
+        current = cfg.env_claims_key
+        return unless current.nil? || current == Verikloak::Audience::Configuration::DEFAULT_ENV_CLAIMS_KEY
+
+        cfg.env_claims_key = user_key
+      end
+
+      def sync_required_aud(cfg, rails_config)
+        return unless cfg_required_aud_blank?(cfg)
+        return unless rails_config.respond_to?(:audience)
+
+        audiences = normalized_audiences(rails_config.audience)
+        return if audiences.empty?
+
+        cfg.required_aud = audiences.size == 1 ? audiences.first : audiences
+      end
+
+      def sync_resource_client(cfg, rails_config)
+        return unless rails_config.respond_to?(:audience)
+
+        audiences = normalized_audiences(rails_config.audience)
+        return unless audiences.size == 1
+
+        current_client = cfg.resource_client
+        unless blank?(current_client) || current_client == Verikloak::Audience::Configuration::DEFAULT_RESOURCE_CLIENT
+          return
+        end
+
+        cfg.resource_client = audiences.first
+      end
+
+      def sync_skip_paths(cfg, rails_config)
+        return unless rails_config.respond_to?(:skip_paths)
+
+        paths = rails_config.skip_paths
+        return if paths.nil?
+        return unless cfg.skip_paths.nil? || cfg.skip_paths.empty?
+
+        cfg.skip_paths = Array(paths).compact
+      end
+
+      def cfg_required_aud_blank?(cfg) = value_blank?(cfg.required_aud)
+
+      def value_blank?(value)
+        return true if value.nil?
+        return true if value.respond_to?(:empty?) && value.empty?
+
+        value.to_s.empty?
+      end
+
+      alias blank? value_blank?
+
+      def normalized_audiences(source)
+        Array(source).compact.map(&:to_s).reject(&:empty?)
+      end
+    end
+
     # Rails integration for verikloak-audience.
     #
     # This Railtie automatically inserts {Verikloak::Audience::Middleware}
@@ -24,305 +195,96 @@ module Verikloak
     #     env_claims_key: 'verikloak.user',
     #     suggest_in_logs: true
     class Railtie < ::Rails::Railtie
-      # Adds the audience middleware after the core Verikloak middleware
-      # when available.
-      #
-      # @param app [Rails::Application] the Rails application instance
+      class << self
+        attr_accessor :middleware_insertion_attempted, :unconfigured_warning_emitted
+
+        include RailtieHelpers
+      end
+
+      @middleware_insertion_attempted = false
+      @unconfigured_warning_emitted = false
+
       initializer 'verikloak_audience.middleware',
                   after: 'verikloak.configure',
                   before: :build_middleware_stack do |app|
-        # Insert automatically after core verikloak if present
+        self.class.apply_verikloak_rails_configuration
         self.class.insert_middleware(app)
       end
 
       initializer 'verikloak_audience.configuration' do
         config.after_initialize do
-          self.class.apply_verikloak_rails_configuration
           next if Verikloak::Audience::Railtie.skip_configuration_validation?
+          next if Verikloak::Audience::Railtie.skip_unconfigured_validation?
 
           Verikloak::Audience.config.validate!
         end
       end
 
-      # Tracks whether middleware insertion has been attempted to prevent
-      # duplicate insertions when both railtie and generator initializer run.
-      # In Rails 8.x+, middleware operations may be queued and `include?` may
-      # not reflect pending insertions, so we use this flag as an additional
-      # safeguard.
-      @middleware_insertion_attempted = false
-
-      class << self
-        attr_accessor :middleware_insertion_attempted
-      end
+      COMMANDS_SKIPPING_VALIDATION = %w[generate g destroy d].freeze
 
-      # Performs the insertion into the middleware stack when the core
-      # Verikloak middleware is available and already present. Extracted for
-      # testability without requiring a full Rails boot process.
-      #
-      # Insert the audience middleware after the base Verikloak middleware when
-      # both are available on the stack.
-      #
-      # In Rails 8.x+, middleware stack operations may be queued rather than
-      # immediately applied, so `include?` checks may return false even when
-      # the middleware will be inserted. We use `insert_after` with exception
-      # handling to gracefully handle this case.
-      #
-      # @param app [#middleware] An object exposing a Rack middleware stack via `#middleware`.
-      # @return [void]
       def self.insert_middleware(app)
         return unless defined?(::Verikloak::Middleware)
 
-        # Skip if we have already attempted insertion (handles Rails 8+ queued operations)
+        if defined?(::Verikloak::Rails) && ::Verikloak::Rails.respond_to?(:config)
+          discovery_url = ::Verikloak::Rails.config.discovery_url
+          unless discovery_url_configured?(discovery_url)
+            warn_core_not_configured
+            return
+          end
+        end
+
         return if middleware_insertion_attempted
 
-        # Use app.config.middleware for queued operations in Rails 8.x+
-        # This ensures the insert_after operation is queued and applied during
-        # build_middleware_stack, maintaining proper ordering with verikloak-rails
         middleware_stack = app.respond_to?(:config) ? app.config.middleware : app.middleware
 
-        # Skip if already present (avoid duplicate insertion)
-        if middleware_stack.respond_to?(:include?) &&
-           middleware_stack.include?(::Verikloak::Audience::Middleware)
+        if middleware_stack.respond_to?(:include?) && middleware_stack.include?(::Verikloak::Audience::Middleware)
           return
         end
 
-        # Mark as attempted before insertion to prevent concurrent/subsequent calls
         self.middleware_insertion_attempted = true
 
-        # Attempt to insert after the core Verikloak middleware.
-        # In Rails 8.x+, the middleware may be queued but not yet visible via include?,
-        # so we try the insertion and handle any exceptions gracefully.
         begin
           middleware_stack.insert_after ::Verikloak::Middleware, ::Verikloak::Audience::Middleware
         rescue StandardError => e
-          # Handle middleware not found errors (varies by Rails version):
-          # - Rails 8+: RuntimeError with "No such middleware" message
-          # - Earlier: ActionDispatch::MiddlewareStack::MiddlewareNotFound
           raise unless middleware_not_found_error?(e)
 
           warn_missing_core_middleware
         end
       end
 
-      # Determines if the given exception indicates a middleware not found error.
-      # This handles variations across Rails versions:
-      # - Rails 8+: RuntimeError with "No such middleware" message
-      # - Rails 7 and earlier: ActionDispatch::MiddlewareStack::MiddlewareNotFound
-      #
-      # @param error [StandardError] the exception to check
-      # @return [Boolean] true if the error indicates missing middleware
-      def self.middleware_not_found_error?(error)
-        # Check exception class name (works for Rails 7's MiddlewareNotFound)
-        return true if error.class.name.to_s.include?('MiddlewareNotFound')
-
-        # Check message patterns for Rails 8+ RuntimeError
-        message = error.message.to_s
-        message.include?('No such middleware') ||
-          message.include?('does not exist') ||
-          message.match?(/middleware.*not found/i)
-      end
-
-      # Resets the insertion flag. Primarily used for testing to allow
-      # multiple insertion attempts within the same process.
-      #
-      # @return [void]
       def self.reset_middleware_insertion_flag!
         self.middleware_insertion_attempted = false
       end
 
-      WARNING_MESSAGE = <<~MSG
-        [verikloak-audience] Skipping automatic middleware insertion because ::Verikloak::Middleware
-        is not present in the Rails middleware stack.
-
-        To enable verikloak-audience, first ensure that the core Verikloak middleware (`Verikloak::Middleware`)
-        is added to your Rails middleware stack. Once the core middleware is present, you can run
-        `rails g verikloak:audience:install` to generate the initializer for the audience middleware,
-        or manually add:
-
-          config.middleware.insert_after Verikloak::Middleware, Verikloak::Audience::Middleware
-
-        This warning will disappear once the core middleware is properly configured and the audience
-        middleware is inserted.
-      MSG
-
-      # Logs a warning message when the core Verikloak middleware is missing
-      # from the Rails middleware stack. Uses the Rails logger if available,
-      # otherwise falls back to Kernel.warn for output.
-      #
-      # This method is called when automatic middleware insertion is skipped
-      # due to the absence of the required core middleware.
-      #
-      # @return [void]
-      def self.warn_missing_core_middleware
-        logger = (::Rails.logger if defined?(::Rails) && ::Rails.respond_to?(:logger))
-
-        if logger
-          logger.warn(WARNING_MESSAGE)
-        else
-          Kernel.warn(WARNING_MESSAGE)
-        end
-      end
-
-      # Rails short commands (`g`, `d`) are stripped from ARGV fairly early in
-      # the boot process. Treat `verikloak:*:install` generators as safe so they
-      # can run before configuration files exist.
-      COMMANDS_SKIPPING_VALIDATION = %w[generate g destroy d].freeze
-
-      # Detect whether Rails is currently executing a generator-style command.
-      # Generators boot the application before configuration exists, so we
-      # temporarily skip validation to let the install task complete.
-      #
-      # @return [Boolean]
       def self.skip_configuration_validation?
         tokens = first_cli_tokens
         return false if tokens.empty?
 
-        command = tokens.first
-        return true if COMMANDS_SKIPPING_VALIDATION.include?(command)
+        return true if COMMANDS_SKIPPING_VALIDATION.include?(tokens.first)
 
         tokens.any? { |token| verikloak_install_generator?(token) }
       end
 
-      # Capture the first non-option arguments passed to the Rails CLI,
-      # ignoring wrapper tokens such as "rails". Only the first two tokens are
-      # relevant for generator detection, so we keep the return list short.
-      #
-      # @return [Array<String>] ordered CLI tokens that may signal a generator
-      def self.first_cli_tokens
-        tokens = []
-
-        ARGV.each do |arg|
-          next if arg.start_with?('-')
-          next if arg == 'rails'
-
-          tokens << arg
-          break if tokens.size >= 2
-        end
-
-        tokens
-      end
-
-      # Detect whether the provided CLI token refers to a Verikloak install
-      # generator (e.g. `verikloak:install`, `verikloak:pundit:install`).
-      #
-      # @param command [String, nil] first non-option argument from ARGV
-      # @return [Boolean]
-      def self.verikloak_install_generator?(command)
-        return false unless command.is_a?(String)
-
-        command.start_with?('verikloak:') && command.end_with?(':install')
+      def self.skip_unconfigured_validation?
+        audiences_unconfigured?
       end
 
-      class << self
-        # Synchronize configuration with verikloak-rails when it is present.
-        # Aligns env_claims_key, required_aud, and resource_client defaults so
-        # that both gems operate on the same Rack env payload and audience list.
-        #
-        # @return [void]
-        def apply_verikloak_rails_configuration
-          rails_config = verikloak_rails_config
-          return unless rails_config
-
-          Verikloak::Audience.configure do |cfg|
-            sync_env_claims_key(cfg, rails_config)
-            sync_required_aud(cfg, rails_config)
-            sync_resource_client(cfg, rails_config)
-          end
-        end
-
-        private
-
-        # Resolve the verikloak-rails configuration object if the gem is loaded.
-        #
-        # @return [Verikloak::Rails::Configuration, nil]
-        def verikloak_rails_config
-          return unless defined?(::Verikloak::Rails)
-          return unless ::Verikloak::Rails.respond_to?(:config)
+      def self.audiences_unconfigured?
+        audiences = Verikloak::Audience.config.required_aud_list
 
-          ::Verikloak::Rails.config
-        rescue StandardError
-          nil
+        if audiences.empty?
+          warn_unconfigured_once
+          return true
         end
 
-        # Align the environment claims key with the one configured in verikloak-rails.
-        #
-        # @param cfg [Verikloak::Audience::Configuration]
-        # @param rails_config [Verikloak::Rails::Configuration]
-        # @return [void]
-        def sync_env_claims_key(cfg, rails_config)
-          return unless rails_config.respond_to?(:user_env_key)
-
-          user_key = rails_config.user_env_key
-          return if blank?(user_key)
-
-          current = cfg.env_claims_key
-          return unless current.nil? || current == Verikloak::Audience::Configuration::DEFAULT_ENV_CLAIMS_KEY
-
-          cfg.env_claims_key = user_key
-        end
-
-        # Populate required audiences from the verikloak-rails configuration when absent.
-        #
-        # @param cfg [Verikloak::Audience::Configuration]
-        # @param rails_config [Verikloak::Rails::Configuration]
-        # @return [void]
-        def sync_required_aud(cfg, rails_config)
-          return unless cfg_required_aud_blank?(cfg)
-          return unless rails_config.respond_to?(:audience)
-
-          audiences = normalized_audiences(rails_config.audience)
-          return if audiences.empty?
-
-          cfg.required_aud = audiences.size == 1 ? audiences.first : audiences
-        end
-
-        # Infer the resource client based on the configured audience when possible.
-        #
-        # @param cfg [Verikloak::Audience::Configuration]
-        # @param rails_config [Verikloak::Rails::Configuration]
-        # @return [void]
-        def sync_resource_client(cfg, rails_config)
-          return unless rails_config.respond_to?(:audience)
-
-          audiences = normalized_audiences(rails_config.audience)
-          return unless audiences.size == 1
-
-          current_client = cfg.resource_client
-          unless blank?(current_client) || current_client == Verikloak::Audience::Configuration::DEFAULT_RESOURCE_CLIENT
-            return
-          end
-
-          cfg.resource_client = audiences.first
-        end
-
-        # Determine whether the audience configuration is effectively empty.
-        #
-        # @param cfg [Verikloak::Audience::Configuration]
-        # @return [Boolean]
-        def cfg_required_aud_blank?(cfg)
-          value_blank?(cfg.required_aud)
-        end
-
-        # Generic blank? helper that tolerates nil, empty, or blank-ish values.
-        #
-        # @param value [Object]
-        # @return [Boolean]
-        def value_blank?(value)
-          return true if value.nil?
-          return true if value.respond_to?(:empty?) && value.empty?
-
-          value.to_s.empty?
-        end
+        false
+      end
 
-        alias blank? value_blank?
+      def self.warn_unconfigured_once
+        return if unconfigured_warning_emitted
 
-        # Coerce the given source into an array of non-empty string audiences.
-        #
-        # @param source [Object]
-        # @return [Array<String>]
-        def normalized_audiences(source)
-          Array(source).compact.map(&:to_s).reject(&:empty?)
-        end
+        self.unconfigured_warning_emitted = true
+        warn_unconfigured
       end
     end
   end

data/lib/verikloak/audience/version.rb

@@ -4,6 +4,6 @@ module Verikloak
   module Audience
     # Current gem version.
     # @return [String]
-    VERSION = '0.3.0'
+    VERSION = '0.3.1'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: verikloak-audience
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - taiyaky
@@ -76,7 +76,7 @@ metadata:
   source_code_uri: https://github.com/taiyaky/verikloak-audience
   changelog_uri: https://github.com/taiyaky/verikloak-audience/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/taiyaky/verikloak-audience/issues
-  documentation_uri: https://rubydoc.info/gems/verikloak-audience/0.3.0
+  documentation_uri: https://rubydoc.info/gems/verikloak-audience/0.3.1
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: