verikloak-audience 0.2.9 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 53894e2af5f290a98ec6f438b9d0271e1f8e86d18c6404c9b0394c5cd5741312
-  data.tar.gz: 0cc799a43b2559f34113e6d738d1e2ee004c1292c86115dc83918ca32aeef04f
+  metadata.gz: 400925f130b177647a3d7007cf4e43b566451e5b131968fbca2946d8a2f47d06
+  data.tar.gz: 89fa1b482fe9cdaa9278f56380cc59bba52325dd7db6b0e9aeb473e658568eb8
 SHA512:
-  metadata.gz: 9536f08a7ce2f5de4113483215386221dec1867c6affbea7a0e3074239017c1d7e0d4135476f72cf45cbda1de2fc17781fdf9662d038eb110afdb336a5ee6bb3
-  data.tar.gz: 5730013314cd5dd393c9936256a5fe31cb3aa13fac4c3dda6dabb7ca308424167235d0482167f2cc92c13e26ee5bdef23eaeddab5f01b7898ea31474aeb3211d
+  metadata.gz: 0d39de8ac4bfb587b968e4017e36edc03fbe49c4a7495963671aacb32a5d65fa06b39957922344b1dd3336614bb20b5ad8eeef9c7248eb6ea9c82dd772323072
+  data.tar.gz: bc01de7533c0388fc4e9f8ed35747b9136c04f166cbcfe0dbc75ff2895703aed960ed0d3845beb0dd3ecc2a3bffae786609864a59ae335672f6754a216adda4d

data/CHANGELOG.md

@@ -7,6 +7,43 @@ 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
+- **Rails 8.x+ middleware insertion**: Fixed automatic middleware insertion not working in Rails 8.x+ due to queued middleware operations not being visible via `include?` checks.
+
+### Changed
+- Railtie initializer now specifies `before: :build_middleware_stack` to ensure middleware insertion is queued before stack construction.
+- Middleware insertion now uses `app.config.middleware` instead of `app.middleware` for more reliable queuing in Rails 8.x+.
+- Extracted `middleware_not_found_error?` method to handle error detection across Rails versions (Rails 7's `MiddlewareNotFound` and Rails 8+'s `RuntimeError`).
+
+### Added
+- `@middleware_insertion_attempted` class variable to prevent duplicate middleware insertion when both railtie and generator initializer run.
+- `reset_middleware_insertion_flag!` method for testing purposes.
+- Support for alternative error message patterns (`"does not exist"`, `/middleware.*not found/i`) for future Rails version compatibility.
+- Comprehensive test coverage for:
+  - `include?` early return when middleware is already present
+  - Duplicate insertion prevention via flag
+  - Rails 7 `MiddlewareNotFound` exception handling
+  - Alternative error message patterns
+  - Unexpected exception re-raising
+
 ## [0.2.9] - 2025-12-31
 
 ### Added

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,7 +1,24 @@
 # frozen_string_literal: true
 
-# Insert the audience middleware after the core Verikloak middleware once it
-# has been loaded into the application.
-if defined?(Rails) && Rails.respond_to?(:application)
-  Verikloak::Audience::Railtie.insert_middleware(Rails.application)
+# Verikloak Audience Configuration
+#
+# 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,69 +4,8 @@ require 'rails/railtie'
 
 module Verikloak
   module Audience
-    # Rails integration for verikloak-audience.
-    #
-    # This Railtie automatically inserts {Verikloak::Audience::Middleware}
-    # into the Rails middleware stack directly after {::Verikloak::Middleware}
-    # when it is present.
-    #
-    # If the core Verikloak middleware is not available, nothing is inserted.
-    # You may still customize the placement in your application via
-    # `config.middleware`.
-    #
-    # @example Configure placement and options
-    #   # config/application.rb
-    #   config.middleware.insert_after Verikloak::Middleware,
-    #     Verikloak::Audience::Middleware,
-    #     profile: :allow_account,
-    #     required_aud: ['rails-api'],
-    #     resource_client: 'rails-api',
-    #     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
-      initializer 'verikloak_audience.middleware' do |app|
-        # Insert automatically after core verikloak if present
-        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?
-
-          Verikloak::Audience.config.validate!
-        end
-      end
-
-      # 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.
-      #
-      # @param app [#middleware] An object exposing a Rack middleware stack via `#middleware`.
-      # @return [void]
-      def self.insert_middleware(app)
-        return unless defined?(::Verikloak::Middleware)
-
-        middleware_stack = app.middleware
-        return unless middleware_stack.respond_to?(:include?)
-
-        return if middleware_stack.include?(::Verikloak::Audience::Middleware)
-
-        unless middleware_stack.include?(::Verikloak::Middleware)
-          warn_missing_core_middleware
-          return
-        end
-
-        middleware_stack.insert_after ::Verikloak::Middleware, ::Verikloak::Audience::Middleware
-      end
-
+    # 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.
@@ -82,184 +21,270 @@ module Verikloak
         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
+      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
 
-        if logger
-          logger.warn(WARNING_MESSAGE)
-        else
-          Kernel.warn(WARNING_MESSAGE)
+    # 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
 
-      # 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
+      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?)
 
-      # 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?
+        true
+      end
 
-        command = tokens.first
-        return true if COMMANDS_SKIPPING_VALIDATION.include?(command)
+      def middleware_not_found_error?(error)
+        return true if error.class.name.to_s.include?('MiddlewareNotFound')
 
-        tokens.any? { |token| verikloak_install_generator?(token) }
+        message = error.message.to_s
+        message.include?('No such middleware') ||
+          message.include?('does not exist') ||
+          message.match?(/middleware.*not found/i)
       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 = []
+      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?('-')
-          next if arg == 'rails'
+          next if arg.start_with?('-') || 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)
+      private
 
-        command.start_with?('verikloak:') && command.end_with?(':install')
+      def verikloak_rails_config
+        return unless defined?(::Verikloak::Rails)
+        return unless ::Verikloak::Rails.respond_to?(:config)
+
+        ::Verikloak::Rails.config
+      rescue StandardError
+        nil
       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
+      def sync_env_claims_key(cfg, rails_config)
+        return unless rails_config.respond_to?(:user_env_key)
 
-        private
+        user_key = rails_config.user_env_key
+        return if blank?(user_key)
 
-        # 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)
+        current = cfg.env_claims_key
+        return unless current.nil? || current == Verikloak::Audience::Configuration::DEFAULT_ENV_CLAIMS_KEY
 
-          ::Verikloak::Rails.config
-        rescue StandardError
-          nil
-        end
+        cfg.env_claims_key = user_key
+      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)
+      def sync_required_aud(cfg, rails_config)
+        return unless cfg_required_aud_blank?(cfg)
+        return unless rails_config.respond_to?(:audience)
 
-          user_key = rails_config.user_env_key
-          return if blank?(user_key)
+        audiences = normalized_audiences(rails_config.audience)
+        return if audiences.empty?
 
-          current = cfg.env_claims_key
-          return unless current.nil? || current == Verikloak::Audience::Configuration::DEFAULT_ENV_CLAIMS_KEY
+        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
 
-          cfg.env_claims_key = user_key
+        current_client = cfg.resource_client
+        unless blank?(current_client) || current_client == Verikloak::Audience::Configuration::DEFAULT_RESOURCE_CLIENT
+          return
         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)
+        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}
+    # into the Rails middleware stack directly after {::Verikloak::Middleware}
+    # when it is present.
+    #
+    # If the core Verikloak middleware is not available, nothing is inserted.
+    # You may still customize the placement in your application via
+    # `config.middleware`.
+    #
+    # @example Configure placement and options
+    #   # config/application.rb
+    #   config.middleware.insert_after Verikloak::Middleware,
+    #     Verikloak::Audience::Middleware,
+    #     profile: :allow_account,
+    #     required_aud: ['rails-api'],
+    #     resource_client: 'rails-api',
+    #     env_claims_key: 'verikloak.user',
+    #     suggest_in_logs: true
+    class Railtie < ::Rails::Railtie
+      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|
+        self.class.apply_verikloak_rails_configuration
+        self.class.insert_middleware(app)
+      end
 
-          audiences = normalized_audiences(rails_config.audience)
-          return if audiences.empty?
+      initializer 'verikloak_audience.configuration' do
+        config.after_initialize do
+          next if Verikloak::Audience::Railtie.skip_configuration_validation?
+          next if Verikloak::Audience::Railtie.skip_unconfigured_validation?
 
-          cfg.required_aud = audiences.size == 1 ? audiences.first : audiences
+          Verikloak::Audience.config.validate!
         end
+      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)
+      COMMANDS_SKIPPING_VALIDATION = %w[generate g destroy d].freeze
 
-          audiences = normalized_audiences(rails_config.audience)
-          return unless audiences.size == 1
+      def self.insert_middleware(app)
+        return unless defined?(::Verikloak::Middleware)
 
-          current_client = cfg.resource_client
-          unless blank?(current_client) || current_client == Verikloak::Audience::Configuration::DEFAULT_RESOURCE_CLIENT
+        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
-
-          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)
+        return if middleware_insertion_attempted
+
+        middleware_stack = app.respond_to?(:config) ? app.config.middleware : app.middleware
+
+        if middleware_stack.respond_to?(:include?) && middleware_stack.include?(::Verikloak::Audience::Middleware)
+          return
         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?
+        self.middleware_insertion_attempted = true
 
-          value.to_s.empty?
+        begin
+          middleware_stack.insert_after ::Verikloak::Middleware, ::Verikloak::Audience::Middleware
+        rescue StandardError => e
+          raise unless middleware_not_found_error?(e)
+
+          warn_missing_core_middleware
         end
+      end
+
+      def self.reset_middleware_insertion_flag!
+        self.middleware_insertion_attempted = false
+      end
 
-        alias blank? value_blank?
+      def self.skip_configuration_validation?
+        tokens = first_cli_tokens
+        return false if tokens.empty?
 
-        # 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?)
+        return true if COMMANDS_SKIPPING_VALIDATION.include?(tokens.first)
+
+        tokens.any? { |token| verikloak_install_generator?(token) }
+      end
+
+      def self.skip_unconfigured_validation?
+        audiences_unconfigured?
+      end
+
+      def self.audiences_unconfigured?
+        audiences = Verikloak::Audience.config.required_aud_list
+
+        if audiences.empty?
+          warn_unconfigured_once
+          return true
         end
+
+        false
+      end
+
+      def self.warn_unconfigured_once
+        return if unconfigured_warning_emitted
+
+        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.2.9'
+    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.2.9
+  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.2.9
+  documentation_uri: https://rubydoc.info/gems/verikloak-audience/0.3.1
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: